thejandeera/kapruka-mcp

1. Repository shape

- This repo is split into two major runtimes:

- a Python MCP server at the repo root (src/, cli.py)

- a Next.js/TypeScript client app in ayubowan/

- They are related but distinct: the Python side exposes Kapruka API capabilities as MCP tools, while the Next.js app provides the end-user shopping/chat experience.

2. Core backend purpose: MCP wrapper around Kapruka REST API

- The Python server is the integration boundary to the external Kapruka.com REST API.

- Its job is to translate API operations into MCP tools consumable by LLMs and MCP clients.

- The README makes clear the server supports both streamable HTTP and stdio transports, so transport is separated from the tool logic.

3. Backend layering

- src/server.py is the FastMCP entry point.

- src/tools/ contains one module per capability area:

- products.py

- categories.py

- orders.py

- delivery.py

- src/api/client.py is the shared async HTTP client layer and centralizes outbound REST calls plus error handling.

- src/config/settings.py holds environment-driven configuration, keeping API endpoint/key concerns out of business logic.

4. Backend cross-cutting concerns

- src/cache.py suggests response or lookup caching to reduce repeated API calls.

- src/order_rate_limit.py indicates order-related protections or throttling around sensitive operations.

- src/middleware.py implies request/response handling at the server boundary, likely for transport concerns or observability.

- src/activity_log.py suggests auditing or event recording for tool usage.

- src/well_known.py likely serves discovery metadata for clients.

5. Backend developer/runtime interface

- cli.py is the operator-facing entry point for local development and validation.

- It supports:

- running the MCP server

- stdio mode for inspector/debugging

- pinging the upstream Kapruka API

- listing registered tools

- tests/test_client.py covers the API client boundary, which is the most important integration seam.

6. Frontend application purpose

- ayubowan/ is a separate Next.js app that provides a shopping/chat UI.

- It appears to be an AI-assisted storefront, with the user interacting through a chat interface and product/cart components.

- The frontend is not just static UI; it includes agent logic and server routes, so it acts as a thin application layer over tool/agent capabilities.

7. Frontend UI composition

- components/ holds the visible experience:

- ChatInterface.tsx for conversational interaction

- ProductCard.tsx for catalog items

- CartDrawer.tsx for cart state and checkout preview

- MessageRenderer.tsx for rendering assistant/user messages

- Navbar.tsx for top-level navigation

- store/useStore.ts indicates client-side state management, likely for cart/session/UI state shared across components.

8. Frontend agent/orchestration boundary

- agents/orchestrator.ts, agents/shopper.ts, and agents/tools.ts show an internal agent layer inside the Next app.

- This layer likely turns user chat into structured shopping actions and tool calls.

- lib/mcp.ts is the bridge into the MCP world, so the frontend can talk to the backend server instead of embedding Kapruka API logic directly.

- This keeps the UI decoupled from the external REST API and centralizes backend tool access.

9. Frontend server routes

- app/api/chat/route.ts is the main application-facing backend endpoint for chat-driven interactions.

- app/api/proxy-image/route.ts suggests images are fetched through the app server, likely to work around remote image restrictions or CORS/hotlinking.

- app/api/test/route.ts is a small diagnostic route.

- app/page.tsx, layout.tsx, and globals.css define the app shell and presentation.

10. Deployment and packaging boundary

- deploy/ contains operational artifacts for production hosting:

- kapruka-mcp.service for systemd

- Caddyfile.snippet for reverse proxying

- sync-to-prod.sh for deployment sync

- That points to a self-hosted backend deployment behind a web proxy.

- server.json, pyproject.toml, and the two package.json/lockfile sets reinforce that the repo intentionally ships two independently deployable stacks.

11. Data flow at a high level

- User interacts with the Next.js UI.

- The UI/chat layer uses the agent/orchestrator logic and talks to MCP tools through lib/mcp.ts and the app API routes.

- The Python MCP server receives tool calls, uses src/api/client.py to call the external Kapruka REST API, and returns structured results.

- Some operations may flow back through frontend state management (useStore) for cart and display updates.

12. Architectural boundary summary

- The clearest separation is:

- presentation + conversational orchestration in ayubowan/

- API normalization + tool exposure in the Python MCP server

- external commerce data/source of truth in Kapruka’s REST API

- If you are drawing the diagram, the key boundaries are the transport boundary (Next.js routes / MCP transport), the tool boundary (MCP server), and the external service boundary (Kapruka API).