kct-git/ecom-mcp

1. What this repo is

- This is a Python MCP server that wraps the Kapruka.com REST API and exposes Kapruka capabilities as LLM-friendly tools for MCP clients.

- The core architectural boundary is between MCP/tool requests on one side and the external Kapruka API on the other.

2. Primary request flow

- An MCP client connects to the server, invokes a tool, and the request is routed into a domain-specific module under src/tools/.

- Tool code calls a shared async API client in src/api/client.py, which talks to the Kapruka REST service and returns normalized results or errors back through the MCP layer.

3. Server/runtime entry points

- cli.py is the developer-facing entry point for starting the server and running utility commands like pinging the upstream API or listing registered tools.

- src/server.py is the main server bootstrap for the MCP runtime.

- The server supports both streamable HTTP and stdio transport, which matters because it can run as a network service or as a local subprocess for MCP Inspector/testing.

4. Tooling boundary

- src/tools/ is split by domain: products, orders, delivery, and categories.

- Each module represents a tool group, so the architecture is organized around business capability rather than a single generic API wrapper.

- This is the main place where domain-specific parameter mapping and response shaping happen.

5. API integration layer

- src/api/client.py is the shared integration point to Kapruka.

- It centralizes outbound HTTP behavior, error handling, and likely request composition, so the rest of the codebase does not need to know Kapruka-specific transport details.

- tests/test_client.py indicates this layer is important enough to have direct unit coverage.

6. Configuration and secrets

- src/config/settings.py provides environment-based configuration.

- .env.example shows the external dependencies that define the runtime boundary: Kapruka API base URL, API key, and related server settings.

- This keeps the server deployable across environments without code changes.

7. Cross-cutting concerns

- src/middleware.py, src/cache.py, src/order_rate_limit.py, and src/activity_log.py are supporting subsystems that sit around the tool/API flow.

- They suggest the server adds operational safeguards such as caching, order-specific throttling, and activity tracking/audit logging.

- These are important diagram boundaries because they affect requests across multiple tool groups, not just one module.

8. Discovery and static surface

- src/well_known.py and src/static/index.html imply the server also serves lightweight discovery or landing content alongside MCP functionality.

- This is not the core business logic, but it is part of the external interface surface that clients or operators may hit.

9. Operational/deployment layer

- The deploy/ directory contains a Caddyfile.snippet, a systemd service file, and a production sync script.

- That indicates the server is designed to run behind a reverse proxy and as a managed service in production, rather than only as a local dev process.

10. Maintenance and support scripts

- scripts/ contains operational helpers for API exploration, smoke testing, registry publishing, and activity-table setup.

- These scripts support onboarding, verification, and deployment workflows; they are not part of the runtime request path but are relevant to how the system is operated.

11. Documentation and handoff artifacts

- docs/ contains design briefs and handoff notes, which suggests the repo has evolved through explicit API/product iterations.

- For architecture purposes, treat these as context for behavior and evolution, not runtime dependencies.

12. Overall structure to diagram

- The diagram should show: MCP client → server/transport → tool modules → shared API client → Kapruka REST API, with configuration, middleware/caching/rate limiting/activity logging, and deployment/runtime wrappers as surrounding layers.