How shanujans/mcp works
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: server.py Server Core · __init__.py Tool Boundary · client.py Kapruka Client · middleware.py Middleware
Components 22
MCP Clients
LLM clients and other MCP consumers
- MCP Clients · MCP-capable clients that call the server
Python Server
Transport, tool, and integration layer
- CLI · Developer entrypoint for starting and probing the server
cli.py - Server Core · Main wiring for transports, tool registration, and request handling
src/server.py - Transports · Streamable HTTP and stdio connection handling
src/server.py - Discovery · Well-known metadata and discovery surface
src/well_known.py - Static Front · Simple browser-facing landing page
src/static/index.html - Tool Boundary · Domain tool surface exposed to MCP clients
src/tools/__init__.py - Products · Product-related MCP tools and mappings
src/tools/products.py - Orders · Order-related MCP tools and mappings
src/tools/orders.py - Delivery · Delivery-related MCP tools and mappings
src/tools/delivery.py - Categories · Category-related MCP tools and mappings
src/tools/categories.py - Middleware · Shared wrapping and request/tool concerns
src/middleware.py - Cache · Reusable caching layer for requests or tool calls
src/cache.py - Rate Limit · Order throttling and protection logic
src/order_rate_limit.py - Settings · Environment-based runtime configuration
src/config/settings.py
External Systems
Kapruka API and supporting infrastructure
- Kapruka Client · Outbound adapter to the Kapruka REST API
src/api/client.py - Kapruka API · Upstream Kapruka.com REST service
- Activity Log · Records tool usage or API activity
src/activity_log.py - Activity Store · External persistence for activity records
Operations
Deployment and maintenance artifacts
- Setup Table · Creates or prepares the activity log table
scripts/setup_activity_table.py - Systemd Service · Service definition for hosting the server
deploy/kapruka-mcp.service - Caddy Edge · TLS and reverse-proxy edge configuration
deploy/Caddyfile.snippet
Connections 24
- 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