# kapruka/mcp architecture

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

- Interactive diagram: https://gitdiagram.com/kapruka/mcp
- Repository: https://github.com/kapruka/mcp

## Overview

1. **What this repo is**
   - A Python **MCP server** that fronts the **Kapruka.com REST API** and exposes selected capabilities as MCP tools for LLMs and other MCP clients.
   - The runtime boundary is: **MCP client → local server → Kapruka API**.

2. **Primary runtime entrypoint**
   - `src/server.py` is the main server assembly point.
   - The README shows it runs either as **streamable HTTP** (`python cli.py server`) or **stdio** (`--stdio`) for MCP Inspector and similar tooling.
   - `cli.py` is the developer-facing wrapper for server startup and utility commands like pinging the upstream API and listing tools.

3. **Tool layer: the exposed MCP surface**
   - `src/tools/` is organized by domain: `products.py`, `orders.py`, `categories.py`, and `delivery.py`.
   - This is the main public capability boundary of the system: each tool module maps MCP actions to a specific Kapruka business area.
   - For diagramming, treat these modules as the “API facade” exposed to external MCP consumers.

4. **API integration boundary**
   - `src/api/client.py` is the dedicated outbound HTTP client to Kapruka’s REST API.
   - This is the key integration layer where request/response handling, upstream error normalization, and HTTP concerns live.
   - The rest of the server should be viewed as calling this client rather than talking to Kapruka directly.

5. **Configuration and environment**
   - `src/config/settings.py` centralizes environment-based settings such as API endpoint/key and server behavior.
   - `.env.example` documents the required operational inputs.
   - This keeps deployment/runtime configuration outside the tool and transport layers.

6. **Cross-cutting runtime concerns**
   - `src/cache.py`, `src/order_rate_limit.py`, `src/middleware.py`, and `src/activity_log.py` indicate shared concerns around:
     - caching of repeated upstream data,
     - rate limiting for order-related operations,
     - request/response middleware,
     - activity/audit logging.
   - These are not separate product domains; they are architectural guards and observability/efficiency layers around tool execution and upstream calls.

7. **MCP discovery and HTTP-facing metadata**
   - `src/well_known.py` plus `src/static/index.html` suggest support for discovery/landing metadata and a small static surface alongside the MCP transport.
   - `server.json` likely supports publication/registration of the server in MCP tooling ecosystems.
   - In a diagram, place these as auxiliary endpoints around the main MCP server rather than core business logic.

8. **Operational and deployment boundary**
   - `deploy/` contains production packaging/infrastructure artifacts:
     - `kapruka-mcp.service` for service management,
     - `Caddyfile.snippet` for reverse proxy setup,
     - `sync-to-prod.sh` for deployment synchronization.
   - These files indicate the server is intended to run as a managed long-lived service behind a proxy.

9. **Developer and validation tooling**
   - `scripts/` contains support tasks such as API exploration, registry publishing, smoke tests, and activity table setup.
   - `tests/test_client.py` focuses on the outbound client layer, which is the most critical integration boundary to validate.
   - `pytest` is the main verification path.

10. **Documentation as architecture context**
   - `docs/` contains design and handover notes for API enhancements and checkout/API flows.
   - These docs are useful for understanding domain evolution, but the runtime architecture remains centered on the MCP server, tool modules, and upstream REST client.

11. **Suggested diagram framing**
   - Draw four main zones:
     - **External consumers**: MCP clients / inspector / LLM hosts.
     - **Kapruka MCP server**: transport, middleware, tool routing, cache/rate-limit/logging.
     - **Integration layer**: async REST client.
     - **External dependency**: Kapruka.com REST API.
   - Surround with operational blocks for config, deployment, and tooling.

Main entry points: [`src/server.py`](https://github.com/kapruka/mcp/blob/main/src/server.py) (Server core), [`src/tools/__init__.py`](https://github.com/kapruka/mcp/blob/main/src/tools/__init__.py) (Tool facade), [`src/api/client.py`](https://github.com/kapruka/mcp/blob/main/src/api/client.py) (API client), [`cli.py`](https://github.com/kapruka/mcp/blob/main/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External consumers"]
  node_mcp_clients(("MCP clients<br/>consumer"))
end

subgraph group_server["Kapruka MCP server"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_server_main["Server core<br/>mcp server<br/>[server.py]"]
  node_middleware["Middleware<br/>cross-cutting<br/>[middleware.py]"]
  node_cache["Cache<br/>cross-cutting<br/>[cache.py]"]
  node_rate_limit["Order limits<br/>guard"]
  node_activity_log["Activity log<br/>observability<br/>[activity_log.py]"]
  node_tool_router["Tool facade<br/>mcp tools<br/>[__init__.py]"]
  node_products_tools["Products<br/>tool domain<br/>[products.py]"]
  node_orders_tools["Orders<br/>tool domain<br/>[orders.py]"]
  node_categories_tools["Categories<br/>tool domain<br/>[categories.py]"]
  node_delivery_tools["Delivery<br/>tool domain<br/>[delivery.py]"]
  node_well_known["Discovery<br/>metadata<br/>[well_known.py]"]
  node_static_site["Static page<br/>landing page<br/>[index.html]"]
end

subgraph group_integration["Integration layer"]
  node_api_client["API client<br/>http client<br/>[client.py]"]
  node_kapruka_api(("Kapruka API<br/>external api"))
end

subgraph group_ops["Ops and support"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
  node_server_json["Registry meta<br/>publication<br/>[server.json]"]
  node_deploy_pkg["Deploy files<br/>ops bundle<br/>[README.md]"]
  node_scripts["Scripts<br/>dev tools<br/>[smoke_test.py]"]
  node_tests["Client tests<br/>test suite<br/>[test_client.py]"]
end

node_mcp_clients -->|"start / inspect"| node_cli
node_mcp_clients -->|"MCP calls"| node_server_main
node_cli -->|"launches"| node_server_main
node_server_main -->|"wraps"| node_middleware
node_server_main -->|"registers tools"| node_tool_router
node_tool_router -->|"routes"| node_products_tools
node_tool_router -->|"routes"| node_orders_tools
node_tool_router -->|"routes"| node_categories_tools
node_tool_router -->|"routes"| node_delivery_tools
node_orders_tools -->|"guards"| node_rate_limit
node_tool_router -->|"uses"| node_cache
node_tool_router -->|"logs"| node_activity_log
node_server_main -->|"publishes"| node_well_known
node_server_main -->|"serves"| node_static_site
node_server_main -->|"reads"| node_settings
node_tool_router -->|"calls"| node_api_client
node_api_client -->|"requests"| node_kapruka_api
node_server_main -->|"publishes"| node_server_json
node_deploy_pkg -.->|"operates"| node_server_main
node_scripts -.->|"exercises"| node_api_client
node_tests -.->|"verifies"| node_api_client

click node_cli "https://github.com/kapruka/mcp/blob/main/cli.py"
click node_server_main "https://github.com/kapruka/mcp/blob/main/src/server.py"
click node_middleware "https://github.com/kapruka/mcp/blob/main/src/middleware.py"
click node_cache "https://github.com/kapruka/mcp/blob/main/src/cache.py"
click node_rate_limit "https://github.com/kapruka/mcp/blob/main/src/order_rate_limit.py"
click node_activity_log "https://github.com/kapruka/mcp/blob/main/src/activity_log.py"
click node_tool_router "https://github.com/kapruka/mcp/blob/main/src/tools/__init__.py"
click node_products_tools "https://github.com/kapruka/mcp/blob/main/src/tools/products.py"
click node_orders_tools "https://github.com/kapruka/mcp/blob/main/src/tools/orders.py"
click node_categories_tools "https://github.com/kapruka/mcp/blob/main/src/tools/categories.py"
click node_delivery_tools "https://github.com/kapruka/mcp/blob/main/src/tools/delivery.py"
click node_settings "https://github.com/kapruka/mcp/blob/main/src/config/settings.py"
click node_api_client "https://github.com/kapruka/mcp/blob/main/src/api/client.py"
click node_well_known "https://github.com/kapruka/mcp/blob/main/src/well_known.py"
click node_static_site "https://github.com/kapruka/mcp/blob/main/src/static/index.html"
click node_server_json "https://github.com/kapruka/mcp/blob/main/server.json"
click node_deploy_pkg "https://github.com/kapruka/mcp/blob/main/deploy/README.md"
click node_scripts "https://github.com/kapruka/mcp/blob/main/scripts/smoke_test.py"
click node_tests "https://github.com/kapruka/mcp/blob/main/tests/test_client.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_clients toneBlue
class node_cli,node_server_main,node_middleware,node_cache,node_rate_limit,node_activity_log,node_tool_router,node_products_tools,node_orders_tools,node_categories_tools,node_delivery_tools,node_well_known,node_static_site toneAmber
class node_api_client,node_kapruka_api toneMint
class node_settings,node_server_json,node_deploy_pkg,node_scripts,node_tests toneRose
```

## Components

### External consumers

MCP clients and human-facing tooling that talk to the server.

- **MCP clients**: consumer · LLMs, MCP hosts, and inspector-style clients that invoke the server.

### Kapruka MCP server

Transport, tool routing, and cross-cutting runtime concerns.

- [CLI](https://github.com/kapruka/mcp/blob/main/cli.py): entrypoint · Developer-facing wrapper for starting the server and running utility commands. · `cli.py`
- [Server core](https://github.com/kapruka/mcp/blob/main/src/server.py): mcp server · Main assembly point for the MCP server runtime. · `src/server.py`
- [Middleware](https://github.com/kapruka/mcp/blob/main/src/middleware.py): cross-cutting · Request/response interception and shared runtime hooks. · `src/middleware.py`
- [Cache](https://github.com/kapruka/mcp/blob/main/src/cache.py): cross-cutting · Shared caching for repeated upstream data. · `src/cache.py`
- [Order limits](https://github.com/kapruka/mcp/blob/main/src/order_rate_limit.py): guard · Rate limiting for order-related operations. · `src/order_rate_limit.py`
- [Activity log](https://github.com/kapruka/mcp/blob/main/src/activity_log.py): observability · Audit and activity recording across tool execution. · `src/activity_log.py`
- [Tool facade](https://github.com/kapruka/mcp/blob/main/src/tools/__init__.py): mcp tools · Public MCP action surface that routes requests into domain tools. · `src/tools/__init__.py`
- [Products](https://github.com/kapruka/mcp/blob/main/src/tools/products.py): tool domain · MCP tools for product browsing and related product actions. · `src/tools/products.py`
- [Orders](https://github.com/kapruka/mcp/blob/main/src/tools/orders.py): tool domain · MCP tools for order lifecycle operations. · `src/tools/orders.py`
- [Categories](https://github.com/kapruka/mcp/blob/main/src/tools/categories.py): tool domain · MCP tools for category discovery and navigation. · `src/tools/categories.py`
- [Delivery](https://github.com/kapruka/mcp/blob/main/src/tools/delivery.py): tool domain · MCP tools for delivery and shipping-related actions. · `src/tools/delivery.py`
- [Discovery](https://github.com/kapruka/mcp/blob/main/src/well_known.py): metadata · Well-known and landing metadata for MCP/HTTP discovery. · `src/well_known.py`
- [Static page](https://github.com/kapruka/mcp/blob/main/src/static/index.html): landing page · Minimal static HTTP surface for server landing or discovery. · `src/static/index.html`

### Integration layer

Outbound client boundary to Kapruka's REST API.

- [API client](https://github.com/kapruka/mcp/blob/main/src/api/client.py): http client · Outbound REST client that normalizes requests, responses, and upstream errors. · `src/api/client.py`
- **Kapruka API**: external api · Upstream Kapruka.com REST API consumed by the server.

### Ops and support

Configuration, deployment, docs, and developer tooling around the runtime.

- [Settings](https://github.com/kapruka/mcp/blob/main/src/config/settings.py): config · Environment-driven configuration for API access and server behavior. · `src/config/settings.py`
- [Registry meta](https://github.com/kapruka/mcp/blob/main/server.json): publication · Publication metadata for MCP tooling ecosystems. · `server.json`
- [Deploy files](https://github.com/kapruka/mcp/blob/main/deploy/README.md): ops bundle · Service, proxy, and sync artifacts for long-lived production deployment. · `deploy/README.md`
- [Scripts](https://github.com/kapruka/mcp/blob/main/scripts/smoke_test.py): dev tools · Support scripts for API exploration, publishing, smoke tests, and setup. · `scripts/smoke_test.py`
- [Client tests](https://github.com/kapruka/mcp/blob/main/tests/test_client.py): test suite · Validation focused on the outbound client integration boundary. · `tests/test_client.py`

## Connections

- MCP clients → CLI: start / inspect · Humans and MCP hosts invoke the CLI for local server startup.
- MCP clients → Server core: MCP calls · External clients communicate with the server runtime over MCP transports.
- CLI → Server core: launches · CLI boots the main server assembly.
- Server core → Middleware: wraps · Server applies shared middleware around request handling.
- Server core → Tool facade: registers tools · Server exposes the MCP tool surface.
- Tool facade → Products: routes · Tool facade dispatches product actions.
- Tool facade → Orders: routes · Tool facade dispatches order actions.
- Tool facade → Categories: routes · Tool facade dispatches category actions.
- Tool facade → Delivery: routes · Tool facade dispatches delivery actions.
- Orders → Order limits: guards · Order workflows are constrained by rate limiting.
- Tool facade → Cache: uses · Tool execution may reuse cached upstream data.
- Tool facade → Activity log: logs · Tool activity is recorded for auditing and observability.
- Server core → Discovery: publishes · Server serves discovery metadata.
- Server core → Static page: serves · Server exposes a minimal static HTTP surface.
- Server core → Settings: reads · Runtime behavior is driven by environment settings.
- Tool facade → API client: calls · Tools use the shared REST client rather than talking upstream directly.
- API client → Kapruka API: requests · Outbound HTTP integration with Kapruka's API.
- Server core → Registry meta: publishes · Metadata supports tooling and registry publication.
- Deploy files → Server core: operates · Deployment artifacts manage the server as a long-lived service.
- Scripts → API client: exercises · Support scripts probe and validate the integration layer.
- Client tests → API client: verifies · Tests focus on client behavior and upstream error handling.
