# kct-git/ecom-mcp architecture

> Architecture diagram of the GitHub repository kct-git/ecom-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kct-git/ecom-mcp
- Repository: https://github.com/kct-git/ecom-mcp

## Overview

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.

Main entry points: [`src/server.py`](https://github.com/kct-git/ecom-mcp/blob/main/src/server.py) (Server), [`src/api/client.py`](https://github.com/kct-git/ecom-mcp/blob/main/src/api/client.py) (API client), [`src/middleware.py`](https://github.com/kct-git/ecom-mcp/blob/main/src/middleware.py) (Middleware), [`src/config/settings.py`](https://github.com/kct-git/ecom-mcp/blob/main/src/config/settings.py) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External systems"]
  node_mcp_client(("MCP client<br/>external client"))
  node_kapruka_api(("Kapruka API<br/>upstream REST"))
end

subgraph group_runtime["Runtime entrypoints"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_server["Server<br/>mcp bootstrap<br/>[server.py]"]
end

subgraph group_tools["Domain tools"]
  node_products["Products<br/>tool group<br/>[products.py]"]
  node_orders["Orders<br/>tool group<br/>[orders.py]"]
  node_delivery["Delivery<br/>tool group<br/>[delivery.py]"]
  node_categories["Categories<br/>tool group<br/>[categories.py]"]
end

subgraph group_integration["Integration layer"]
  node_middleware["Middleware<br/>cross-cutting<br/>[middleware.py]"]
  node_cache["Cache<br/>[cache.py]"]
  node_rate_limit["Rate limit<br/>order guard"]
  node_activity_log["Activity log<br/>audit logging<br/>[activity_log.py]"]
  node_api_client["API client<br/>kapruka client<br/>[client.py]"]
end

subgraph group_support["Support surface"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
  node_well_known["Well-known<br/>discovery surface<br/>[well_known.py]"]
  node_static_index["Landing page<br/>static ui<br/>[index.html]"]
end

subgraph group_ops["Operations"]
  node_deploy_caddy["Caddy snippet<br/>deployment<br/>[Caddyfile.snippet]"]
  node_deploy_systemd["Systemd unit<br/>deployment"]
  node_deploy_sync["Sync script<br/>deployment helper<br/>[sync-to-prod.sh]"]
  node_scripts["Ops scripts<br/>maintenance<br/>[explore_api.py]"]
end

node_mcp_client -->|"tool calls"| node_server
node_cli -->|"start"| node_server
node_server -->|"wraps"| node_middleware
node_middleware -->|"uses"| node_cache
node_middleware -->|"guards"| node_rate_limit
node_middleware -->|"records"| node_activity_log
node_server -->|"serves"| node_well_known
node_server -->|"serves"| node_static_index
node_server -->|"registers"| node_products
node_server -->|"registers"| node_orders
node_server -->|"registers"| node_delivery
node_server -->|"registers"| node_categories
node_products -->|"calls"| node_api_client
node_orders -->|"calls"| node_api_client
node_delivery -->|"calls"| node_api_client
node_categories -->|"calls"| node_api_client
node_api_client -->|"HTTP"| node_kapruka_api
node_settings -->|"configures"| node_server
node_settings -->|"configures"| node_api_client
node_deploy_caddy -.->|"fronts"| node_server
node_deploy_systemd -.->|"runs"| node_server
node_deploy_sync -.->|"deploys"| node_deploy_systemd
node_scripts -.->|"exercise"| node_api_client

click node_cli "https://github.com/kct-git/ecom-mcp/blob/main/cli.py"
click node_server "https://github.com/kct-git/ecom-mcp/blob/main/src/server.py"
click node_settings "https://github.com/kct-git/ecom-mcp/blob/main/src/config/settings.py"
click node_well_known "https://github.com/kct-git/ecom-mcp/blob/main/src/well_known.py"
click node_static_index "https://github.com/kct-git/ecom-mcp/blob/main/src/static/index.html"
click node_middleware "https://github.com/kct-git/ecom-mcp/blob/main/src/middleware.py"
click node_cache "https://github.com/kct-git/ecom-mcp/blob/main/src/cache.py"
click node_rate_limit "https://github.com/kct-git/ecom-mcp/blob/main/src/order_rate_limit.py"
click node_activity_log "https://github.com/kct-git/ecom-mcp/blob/main/src/activity_log.py"
click node_api_client "https://github.com/kct-git/ecom-mcp/blob/main/src/api/client.py"
click node_products "https://github.com/kct-git/ecom-mcp/blob/main/src/tools/products.py"
click node_orders "https://github.com/kct-git/ecom-mcp/blob/main/src/tools/orders.py"
click node_delivery "https://github.com/kct-git/ecom-mcp/blob/main/src/tools/delivery.py"
click node_categories "https://github.com/kct-git/ecom-mcp/blob/main/src/tools/categories.py"
click node_deploy_caddy "https://github.com/kct-git/ecom-mcp/blob/main/deploy/Caddyfile.snippet"
click node_deploy_systemd "https://github.com/kct-git/ecom-mcp/blob/main/deploy/kapruka-mcp.service"
click node_deploy_sync "https://github.com/kct-git/ecom-mcp/blob/main/deploy/sync-to-prod.sh"
click node_scripts "https://github.com/kct-git/ecom-mcp/blob/main/scripts/explore_api.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_client,node_kapruka_api toneBlue
class node_cli,node_server toneAmber
class node_products,node_orders,node_delivery,node_categories toneMint
class node_middleware,node_cache,node_rate_limit,node_activity_log,node_api_client toneRose
class node_settings,node_well_known,node_static_index toneIndigo
class node_deploy_caddy,node_deploy_systemd,node_deploy_sync,node_scripts toneTeal
```

## Components

### External systems

Clients and upstream service outside this repository.

- **MCP client**: external client · Any MCP host or inspector invoking tools over stdio or HTTP.
- **Kapruka API**: upstream REST · External Kapruka.com service consumed by the server.

### Runtime entrypoints

Server bootstrap and developer-facing commands.

- [CLI](https://github.com/kct-git/ecom-mcp/blob/main/cli.py): entrypoint · Developer-facing command entry for running the server and utility actions. · `cli.py`
- [Server](https://github.com/kct-git/ecom-mcp/blob/main/src/server.py): mcp bootstrap · Main MCP server bootstrap and transport setup. · `src/server.py`

### Domain tools

Business-capability tool modules exposed through MCP.

- [Products](https://github.com/kct-git/ecom-mcp/blob/main/src/tools/products.py): tool group · Tools for product-related lookup and shaping. · `src/tools/products.py`
- [Orders](https://github.com/kct-git/ecom-mcp/blob/main/src/tools/orders.py): tool group · Tools for order-related workflows and actions. · `src/tools/orders.py`
- [Delivery](https://github.com/kct-git/ecom-mcp/blob/main/src/tools/delivery.py): tool group · Tools for delivery-related capabilities. · `src/tools/delivery.py`
- [Categories](https://github.com/kct-git/ecom-mcp/blob/main/src/tools/categories.py): tool group · Tools for category discovery and navigation. · `src/tools/categories.py`

### Integration layer

Shared API client and operational safeguards around outbound requests.

- [Middleware](https://github.com/kct-git/ecom-mcp/blob/main/src/middleware.py): cross-cutting · Request-layer hooks that wrap tool execution and server behavior. · `src/middleware.py`
- [Cache](https://github.com/kct-git/ecom-mcp/blob/main/src/cache.py): response cache · Shared caching layer for repeated or expensive lookups. · `src/cache.py`
- [Rate limit](https://github.com/kct-git/ecom-mcp/blob/main/src/order_rate_limit.py): order guard · Order-specific throttling and request protection. · `src/order_rate_limit.py`
- [Activity log](https://github.com/kct-git/ecom-mcp/blob/main/src/activity_log.py): audit logging · Operational logging or tracking of activity across requests. · `src/activity_log.py`
- [API client](https://github.com/kct-git/ecom-mcp/blob/main/src/api/client.py): kapruka client · Shared async HTTP client and error handling for Kapruka REST calls. · `src/api/client.py`

### Support surface

Configuration and lightweight auxiliary server surfaces.

- [Settings](https://github.com/kct-git/ecom-mcp/blob/main/src/config/settings.py): config · Environment-driven configuration used across the runtime. · `src/config/settings.py`
- [Well-known](https://github.com/kct-git/ecom-mcp/blob/main/src/well_known.py): discovery surface · Lightweight discovery or metadata endpoint surface. · `src/well_known.py`
- [Landing page](https://github.com/kct-git/ecom-mcp/blob/main/src/static/index.html): static ui · Simple static index served alongside the MCP runtime. · `src/static/index.html`

### Operations

Deployment and maintenance helpers.

- [Caddy snippet](https://github.com/kct-git/ecom-mcp/blob/main/deploy/Caddyfile.snippet): deployment · Reverse-proxy configuration fragment for production hosting. · `deploy/Caddyfile.snippet`
- [Systemd unit](https://github.com/kct-git/ecom-mcp/blob/main/deploy/kapruka-mcp.service): deployment · Managed service definition for production runtime. · `deploy/kapruka-mcp.service`
- [Sync script](https://github.com/kct-git/ecom-mcp/blob/main/deploy/sync-to-prod.sh): deployment helper · Production deployment synchronization script. · `deploy/sync-to-prod.sh`
- [Ops scripts](https://github.com/kct-git/ecom-mcp/blob/main/scripts/explore_api.py): maintenance · Support scripts for exploration, smoke tests, registry publishing, and setup. · `scripts/explore_api.py`

## Connections

- MCP client → Server: tool calls · Clients invoke MCP tools through the server transport.
- CLI → Server: start · CLI launches or manages the MCP server runtime.
- Server → Middleware: wraps · The server applies cross-cutting request handling.
- Middleware → Cache: uses · Request processing can consult shared caching.
- Middleware → Rate limit: guards · Order flows are protected by throttling.
- Middleware → Activity log: records · Operational activity is tracked during request handling.
- Server → Well-known: serves · The runtime exposes discovery metadata.
- Server → Landing page: serves · The runtime can serve a lightweight landing page.
- Server → Products: registers · Product tools are exposed through the MCP server.
- Server → Orders: registers · Order tools are exposed through the MCP server.
- Server → Delivery: registers · Delivery tools are exposed through the MCP server.
- Server → Categories: registers · Category tools are exposed through the MCP server.
- Products → API client: calls · Product tools fetch data through the shared API client.
- Orders → API client: calls · Order tools fetch and mutate via the shared API client.
- Delivery → API client: calls · Delivery tools retrieve upstream data through the shared client.
- Categories → API client: calls · Category tools query Kapruka through the shared client.
- API client → Kapruka API: HTTP · Shared async client talks to the Kapruka REST service.
- Settings → Server: configures · Runtime settings shape transport and server behavior.
- Settings → API client: configures · API base URL, keys, and related client settings.
- Caddy snippet → Server: fronts · Reverse proxy configuration routes traffic to the server.
- Systemd unit → Server: runs · System service manages the production process.
- Sync script → Systemd unit: deploys · Sync script supports production rollout of service assets.
- Ops scripts → API client: exercise · Maintenance scripts probe and smoke test the API layer.