sethikamoraes/kapruka-agentchallenge

1. What this repo is

- A Python MCP (Model Context Protocol) server that fronts the Kapruka.com REST API and exposes Kapruka capabilities as LLM-friendly tools for MCP clients.

2. Top-level execution path

- cli.py is the developer entrypoint. It can start the server, run it over stdio for inspection/testing, print registered tools, or ping the upstream API.

- src/server.py is the main server bootstrap and likely the place where the MCP app is assembled and tool handlers are registered.

3. Inbound server interfaces

- The server supports at least two transports:

- Streamable HTTP for normal deployment.

- stdio for local MCP Inspector use.

- src/well_known.py and src/static/index.html suggest a small public-facing HTTP surface in addition to MCP transport, likely for discovery/landing-page behavior.

4. Tool layer

- src/tools/ is the main functional boundary. It is organized by domain:

- products.py

- orders.py

- categories.py

- delivery.py

- Each module likely defines one tool group and translates MCP calls into Kapruka API operations. This is the primary business-logic layer exposed to clients.

5. External API boundary

- src/api/client.py is the single outbound integration layer to Kapruka’s REST API.

- This is where async HTTP behavior, request/response shaping, and error handling are centralized, keeping the tool modules thin and consistent.

6. Cross-cutting concerns

- src/cache.py handles caching for repeated API lookups or metadata.

- src/order_rate_limit.py suggests order-related operations have special throttling or abuse protection.

- src/middleware.py is the shared place for request-level concerns that apply across tools and endpoints.

7. Observability / activity tracking

- src/activity_log.py indicates the server records tool usage or API activity, likely to support auditing, diagnostics, or operational reporting.

- scripts/setup_activity_table.py implies this logging may depend on a backing datastore/table that must be provisioned separately.

8. Configuration boundary

- src/config/settings.py and .env.example show the service is environment-driven.

- Configuration likely includes Kapruka API base URL, API key, server mode, and deployment/runtime settings. This keeps deployment concerns out of tool code.

9. Deployment shape

- deploy/kapruka-mcp.service, deploy/Caddyfile.snippet, and deploy/sync-to-prod.sh indicate a production setup that runs the Python server as a service and places it behind Caddy or another reverse proxy.

- server.json likely contains MCP/server metadata used by hosting or registry tooling.

10. Development and validation tooling

- scripts/ contains operational helpers:

- API exploration and model listing

- registry publishing

- smoke tests

- tests/test_client.py focuses on the outbound API client, which makes sense because the client is the most critical integration boundary.

- The repo therefore has a clear split between protocol/server concerns, Kapruka API integration, and small operational scripts.

11. How data flows through the system

- Client request enters via MCP transport.

- Server dispatches to a tool module.

- Tool module uses the shared API client, cache, and rate-limit/activity subsystems.

- The API client calls Kapruka’s REST API.

- Responses are normalized and returned to the MCP caller, with optional logging and caching applied along the way.

12. Architecture boundaries to show in a diagram

- External clients / MCP Inspector

- MCP server entrypoints and transport layer

- Tool modules by domain

- Shared platform services: config, cache, middleware, rate limiting, activity log

- External Kapruka REST API

- Deployment/reverse-proxy/runtime packaging around the server