# shanujans/mcp architecture

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

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

## Overview

1. **What this repository is**
   - This is a **Python MCP server** that adapts the **Kapruka.com REST API** into **Model Context Protocol tools** for LLM clients and other MCP consumers.
   - The core architecture is an **integration layer**: MCP requests come in, are mapped to tool handlers, then translated into outbound Kapruka API calls.

2. **Primary runtime entry point**
   - `src/server.py` is the main server wiring point.
   - `cli.py` is the developer-facing launcher, with commands to start the server, run a ping check, and list available tools.
   - The server supports both **streamable HTTP** and **stdio** transport, which affects how clients connect but not the internal tool architecture.

3. **MCP tool boundary**
   - `src/tools/` is the main business-facing surface.
   - It is split by domain: `products`, `orders`, `delivery`, and `categories`.
   - Each module likely exposes one or more MCP tools and keeps domain logic separate from transport and HTTP client concerns.

4. **External API adapter layer**
   - `src/api/client.py` is the dedicated **Kapruka REST client**.
   - This is the boundary between MCP/tool logic and the external Kapruka API.
   - The README indicates async HTTP usage, so the architecture is likely built around **async request/response flow** and centralized error handling.

5. **Configuration and environment**
   - `src/config/settings.py` holds environment-based configuration.
   - `.env.example` shows the repo expects runtime settings such as API base URL and API key.
   - This configuration layer isolates deployment/runtime differences from server and tool code.

6. **Cross-cutting concerns**
   - `src/middleware.py`, `src/cache.py`, and `src/order_rate_limit.py` indicate shared request/tool concerns.
   - These likely implement reusable controls such as caching, throttling, or middleware-style wrapping around tool execution or API calls.
   - `src/activity_log.py` suggests there is also an auditing/telemetry path for tool usage or API activity.

7. **Well-known and static surfaces**
   - `src/well_known.py` and `src/static/index.html` indicate the server exposes at least one **discovery/metadata endpoint** and a simple static front door.
   - This is useful for client discovery, diagnostics, or a lightweight browser-facing landing page, alongside the MCP interface itself.

8. **Data and persistence boundary**
   - The presence of `src/activity_log.py` plus `scripts/setup_activity_table.py` implies the server may write to an **activity log table** in an external datastore.
   - That means the architecture is not purely stateless: tool invocations may be recorded outside the process for auditing or analytics.

9. **Operational and deployment layer**
   - `deploy/kapruka-mcp.service` shows a **systemd service** deployment option.
   - `deploy/Caddyfile.snippet` suggests **Caddy** is used as a reverse proxy / TLS edge.
   - `deploy/sync-to-prod.sh` and `scripts/publish-registry.sh` indicate production rollout and registry publishing are handled by scripts rather than embedded in the app.

10. **Testing and validation**
   - `tests/test_client.py` focuses on the API client boundary, which is the most critical integration point.
   - `scripts/smoke_test.py` and `scripts/explore_api.py` are operational helpers for checking Kapruka API behavior and server readiness.
   - This suggests the repo validates both the outbound API adapter and the overall server behavior.

11. **Documentation and handoff artifacts**
   - The `docs/` folder contains API briefings and handover notes, which implies the API surface and tool contracts are actively evolving.
   - These documents are part of the system architecture because they define how the MCP tool layer should map to Kapruka API capabilities.

12. **How to draw the diagram**
   - Show three main zones: **MCP clients** on the left, the **Python MCP server/tool layer** in the center, and the **Kapruka REST API** on the right.
   - Add a side path for **logging/activity persistence** and a deployment edge for **Caddy/systemd**.
   - Within the server, separate the diagram into **transport/server entry**, **domain tools**, **API client**, and **shared middleware/config**.

Main entry points: [`src/server.py`](https://github.com/shanujans/mcp/blob/main/src/server.py) (Server Core), [`src/tools/__init__.py`](https://github.com/shanujans/mcp/blob/main/src/tools/__init__.py) (Tool Boundary), [`src/api/client.py`](https://github.com/shanujans/mcp/blob/main/src/api/client.py) (Kapruka Client), [`src/middleware.py`](https://github.com/shanujans/mcp/blob/main/src/middleware.py) (Middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["MCP Clients"]
  node_mcp_clients(("MCP Clients<br/>consumer"))
end

subgraph group_server["Python Server"]
  node_cli["CLI<br/>launcher<br/>[cli.py]"]
  node_server_core["Server Core<br/>mcp server<br/>[server.py]"]
  node_transports["Transports<br/>http/stdio<br/>[server.py]"]
  node_well_known["Discovery<br/>endpoint<br/>[well_known.py]"]
  node_static_site["Static Front<br/>static asset<br/>[index.html]"]
  node_tools_index["Tool Boundary<br/>mcp tools<br/>[__init__.py]"]
  node_products_tools["Products<br/>domain tools<br/>[products.py]"]
  node_orders_tools["Orders<br/>domain tools<br/>[orders.py]"]
  node_delivery_tools["Delivery<br/>domain tools<br/>[delivery.py]"]
  node_categories_tools["Categories<br/>domain tools<br/>[categories.py]"]
  node_middleware["Middleware<br/>cross-cutting<br/>[middleware.py]"]
  node_cache["Cache<br/>cross-cutting<br/>[cache.py]"]
  node_rate_limit["Rate Limit<br/>cross-cutting"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
end

subgraph group_external["External Systems"]
  node_api_client["Kapruka Client<br/>async REST client<br/>[client.py]"]
  node_kapruka_api[("Kapruka API<br/>external REST")]
  node_activity_log["Activity Log<br/>audit/logging<br/>[activity_log.py]"]
  node_activity_store[("Activity Store<br/>datastore")]
end

subgraph group_ops["Operations"]
  node_setup_table["Setup Table<br/>ops script"]
  node_systemd["Systemd Service<br/>deployment"]
  node_caddy["Caddy Edge<br/>reverse proxy<br/>[Caddyfile.snippet]"]
end

node_mcp_clients -->|"MCP requests"| node_transports
node_cli -->|"launches"| node_server_core
node_server_core -->|"wires"| node_transports
node_server_core -->|"registers"| node_tools_index
node_tools_index -->|"includes"| node_products_tools
node_tools_index -->|"includes"| node_orders_tools
node_tools_index -->|"includes"| node_delivery_tools
node_tools_index -->|"includes"| node_categories_tools
node_products_tools -->|"calls"| node_api_client
node_orders_tools -->|"calls"| node_api_client
node_delivery_tools -->|"calls"| node_api_client
node_categories_tools -->|"calls"| node_api_client
node_server_core -->|"exposes"| node_well_known
node_server_core -->|"serves"| node_static_site
node_server_core -->|"uses"| node_middleware
node_middleware -->|"wraps"| node_cache
node_middleware -->|"wraps"| node_rate_limit
node_server_core -->|"loads"| node_settings
node_api_client -->|"requests"| node_kapruka_api
node_activity_log -->|"writes"| node_activity_store
node_server_core -->|"records"| node_activity_log
node_setup_table -.->|"prepares"| node_activity_store
node_systemd -->|"runs"| node_server_core
node_caddy -->|"proxies"| node_transports

click node_cli "https://github.com/shanujans/mcp/blob/main/cli.py"
click node_server_core "https://github.com/shanujans/mcp/blob/main/src/server.py"
click node_transports "https://github.com/shanujans/mcp/blob/main/src/server.py"
click node_well_known "https://github.com/shanujans/mcp/blob/main/src/well_known.py"
click node_static_site "https://github.com/shanujans/mcp/blob/main/src/static/index.html"
click node_tools_index "https://github.com/shanujans/mcp/blob/main/src/tools/__init__.py"
click node_products_tools "https://github.com/shanujans/mcp/blob/main/src/tools/products.py"
click node_orders_tools "https://github.com/shanujans/mcp/blob/main/src/tools/orders.py"
click node_delivery_tools "https://github.com/shanujans/mcp/blob/main/src/tools/delivery.py"
click node_categories_tools "https://github.com/shanujans/mcp/blob/main/src/tools/categories.py"
click node_middleware "https://github.com/shanujans/mcp/blob/main/src/middleware.py"
click node_cache "https://github.com/shanujans/mcp/blob/main/src/cache.py"
click node_rate_limit "https://github.com/shanujans/mcp/blob/main/src/order_rate_limit.py"
click node_settings "https://github.com/shanujans/mcp/blob/main/src/config/settings.py"
click node_api_client "https://github.com/shanujans/mcp/blob/main/src/api/client.py"
click node_activity_log "https://github.com/shanujans/mcp/blob/main/src/activity_log.py"
click node_setup_table "https://github.com/shanujans/mcp/blob/main/scripts/setup_activity_table.py"
click node_systemd "https://github.com/shanujans/mcp/blob/main/deploy/kapruka-mcp.service"
click node_caddy "https://github.com/shanujans/mcp/blob/main/deploy/Caddyfile.snippet"

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_core,node_transports,node_well_known,node_static_site,node_tools_index,node_products_tools,node_orders_tools,node_delivery_tools,node_categories_tools,node_middleware,node_cache,node_rate_limit,node_settings toneAmber
class node_api_client,node_kapruka_api,node_activity_log,node_activity_store toneMint
class node_setup_table,node_systemd,node_caddy toneRose
```

## Components

### MCP Clients

LLM clients and other MCP consumers

- **MCP Clients**: consumer · MCP-capable clients that call the server

### Python Server

Transport, tool, and integration layer

- [CLI](https://github.com/shanujans/mcp/blob/main/cli.py): launcher · Developer entrypoint for starting and probing the server · `cli.py`
- [Server Core](https://github.com/shanujans/mcp/blob/main/src/server.py): mcp server · Main wiring for transports, tool registration, and request handling · `src/server.py`
- [Transports](https://github.com/shanujans/mcp/blob/main/src/server.py): http/stdio · Streamable HTTP and stdio connection handling · `src/server.py`
- [Discovery](https://github.com/shanujans/mcp/blob/main/src/well_known.py): endpoint · Well-known metadata and discovery surface · `src/well_known.py`
- [Static Front](https://github.com/shanujans/mcp/blob/main/src/static/index.html): static asset · Simple browser-facing landing page · `src/static/index.html`
- [Tool Boundary](https://github.com/shanujans/mcp/blob/main/src/tools/__init__.py): mcp tools · Domain tool surface exposed to MCP clients · `src/tools/__init__.py`
- [Products](https://github.com/shanujans/mcp/blob/main/src/tools/products.py): domain tools · Product-related MCP tools and mappings · `src/tools/products.py`
- [Orders](https://github.com/shanujans/mcp/blob/main/src/tools/orders.py): domain tools · Order-related MCP tools and mappings · `src/tools/orders.py`
- [Delivery](https://github.com/shanujans/mcp/blob/main/src/tools/delivery.py): domain tools · Delivery-related MCP tools and mappings · `src/tools/delivery.py`
- [Categories](https://github.com/shanujans/mcp/blob/main/src/tools/categories.py): domain tools · Category-related MCP tools and mappings · `src/tools/categories.py`
- [Middleware](https://github.com/shanujans/mcp/blob/main/src/middleware.py): cross-cutting · Shared wrapping and request/tool concerns · `src/middleware.py`
- [Cache](https://github.com/shanujans/mcp/blob/main/src/cache.py): cross-cutting · Reusable caching layer for requests or tool calls · `src/cache.py`
- [Rate Limit](https://github.com/shanujans/mcp/blob/main/src/order_rate_limit.py): cross-cutting · Order throttling and protection logic · `src/order_rate_limit.py`
- [Settings](https://github.com/shanujans/mcp/blob/main/src/config/settings.py): config · Environment-based runtime configuration · `src/config/settings.py`

### External Systems

Kapruka API and supporting infrastructure

- [Kapruka Client](https://github.com/shanujans/mcp/blob/main/src/api/client.py): async REST client · Outbound adapter to the Kapruka REST API · `src/api/client.py`
- **Kapruka API**: external REST · Upstream Kapruka.com REST service
- [Activity Log](https://github.com/shanujans/mcp/blob/main/src/activity_log.py): audit/logging · Records tool usage or API activity · `src/activity_log.py`
- **Activity Store**: datastore · External persistence for activity records

### Operations

Deployment and maintenance artifacts

- [Setup Table](https://github.com/shanujans/mcp/blob/main/scripts/setup_activity_table.py): ops script · Creates or prepares the activity log table · `scripts/setup_activity_table.py`
- [Systemd Service](https://github.com/shanujans/mcp/blob/main/deploy/kapruka-mcp.service): deployment · Service definition for hosting the server · `deploy/kapruka-mcp.service`
- [Caddy Edge](https://github.com/shanujans/mcp/blob/main/deploy/Caddyfile.snippet): reverse proxy · TLS and reverse-proxy edge configuration · `deploy/Caddyfile.snippet`

## Connections

- MCP Clients → Transports: MCP requests · Clients connect over HTTP or stdio
- CLI → Server Core: launches · Developer command starts the server process
- Server Core → Transports: wires · Server core binds transport modes
- Server Core → Tool Boundary: registers · Tool boundary is assembled into the server
- Tool Boundary → Products: includes · Product tool set is exposed through the boundary
- Tool Boundary → Orders: includes · Order tool set is exposed through the boundary
- Tool Boundary → Delivery: includes · Delivery tool set is exposed through the boundary
- Tool Boundary → Categories: includes · Category tool set is exposed through the boundary
- Products → Kapruka Client: calls · Product tools translate to upstream API calls
- Orders → Kapruka Client: calls · Order tools translate to upstream API calls
- Delivery → Kapruka Client: calls · Delivery tools translate to upstream API calls
- Categories → Kapruka Client: calls · Category tools translate to upstream API calls
- Server Core → Discovery: exposes · Discovery metadata endpoint is served alongside MCP
- Server Core → Static Front: serves · Static landing page is available from the server
- Server Core → Middleware: uses · Shared wrappers sit around request handling
- Middleware → Cache: wraps · Caching is applied as a shared concern
- Middleware → Rate Limit: wraps · Rate limiting is applied as a shared concern
- Server Core → Settings: loads · Runtime settings are injected into the server
- Kapruka Client → Kapruka API: requests · Outbound async HTTP calls reach Kapruka
- Activity Log → Activity Store: writes · Audit events persist outside the process
- Server Core → Activity Log: records · Tool or request activity can be logged
- Setup Table → Activity Store: prepares · Schema/setup script initializes persistence
- Systemd Service → Server Core: runs · Production service hosts the server process
- Caddy Edge → Transports: proxies · Edge proxy forwards traffic to the server
