How kapruka/mcp works
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: server.py Server core · __init__.py Tool facade · client.py API client · cli.py CLI
Components 21
External consumers
MCP clients and human-facing tooling that talk to the server.
- MCP clients · LLMs, MCP hosts, and inspector-style clients that invoke the server.
Kapruka MCP server
Transport, tool routing, and cross-cutting runtime concerns.
- CLI · Developer-facing wrapper for starting the server and running utility commands.
cli.py - Server core · Main assembly point for the MCP server runtime.
src/server.py - Middleware · Request/response interception and shared runtime hooks.
src/middleware.py - Cache · Shared caching for repeated upstream data.
src/cache.py - Order limits · Rate limiting for order-related operations.
src/order_rate_limit.py - Activity log · Audit and activity recording across tool execution.
src/activity_log.py - Tool facade · Public MCP action surface that routes requests into domain tools.
src/tools/__init__.py - Products · MCP tools for product browsing and related product actions.
src/tools/products.py - Orders · MCP tools for order lifecycle operations.
src/tools/orders.py - Categories · MCP tools for category discovery and navigation.
src/tools/categories.py - Delivery · MCP tools for delivery and shipping-related actions.
src/tools/delivery.py - Discovery · Well-known and landing metadata for MCP/HTTP discovery.
src/well_known.py - Static 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 · Outbound REST client that normalizes requests, responses, and upstream errors.
src/api/client.py - Kapruka API · Upstream Kapruka.com REST API consumed by the server.
Ops and support
Configuration, deployment, docs, and developer tooling around the runtime.
- Settings · Environment-driven configuration for API access and server behavior.
src/config/settings.py - Registry meta · Publication metadata for MCP tooling ecosystems.
server.json - Deploy files · Service, proxy, and sync artifacts for long-lived production deployment.
deploy/README.md - Scripts · Support scripts for API exploration, publishing, smoke tests, and setup.
scripts/smoke_test.py - Client tests · Validation focused on the outbound client integration boundary.
tests/test_client.py
Connections 21
- 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.