it24100500/ai-agent

1. Overall shape

- This repo is centered on a Python MCP server that exposes the Kapruka.com REST API as MCP tools for LLM clients and other MCP consumers.

- The main production boundary is: MCP client → FastMCP server → internal tool modules → async HTTP client → Kapruka REST API.

2. Primary runtime entry points

- cli.py is the developer-facing entry point for running the server and utility commands.

- src/server.py is the actual server bootstrap for the MCP runtime.

- The server supports at least two transports: streamable HTTP and stdio for MCP Inspector / local tooling.

3. MCP tool layer

- src/tools/ contains the domain-facing tool groups:

- products.py

- orders.py

- categories.py

- delivery.py

- These modules are the main contract exposed to MCP clients and likely define the tool schemas, input validation, and tool-specific orchestration logic.

- This is the layer where the API is reshaped from Kapruka’s raw REST semantics into LLM-friendly operations.

4. API integration layer

- src/api/client.py is the outbound integration boundary.

- It wraps the Kapruka REST API with an async HTTP client and centralized error handling.

- The rest of the system should not talk directly to Kapruka; tools go through this client, which keeps external API concerns isolated.

5. Cross-cutting runtime concerns

- src/middleware.py likely hosts request/response concerns that apply across the server, such as logging, headers, authentication-related handling, or other request shaping.

- src/cache.py provides caching support to reduce repeated external API calls and stabilize tool performance.

- src/order_rate_limit.py indicates explicit throttling or protection around order-related actions, which is important because those are usually higher-risk or higher-cost operations.

6. Configuration boundary

- src/config/settings.py centralizes environment-based configuration.

- .env.example shows the system is configured primarily through environment variables, including Kapruka API URL and API key.

- This keeps deployment-specific values out of code and makes the server portable across environments.

7. Operational and observability support

- src/activity_log.py plus scripts/setup_activity_table.py suggest the server records tool or request activity in a persistent table, likely for auditability or usage tracking.

- That creates a second data path besides the main API proxy path: server activity → storage/logging backend.

- tests/test_client.py shows the HTTP client is a key unit boundary worthy of direct test coverage.

8. Well-known / metadata support

- src/well_known.py suggests the server exposes protocol or discovery metadata through a well-known endpoint or standardized integration surface.

- This is relevant for clients that need to discover server capabilities without hardcoding tool details.

9. Frontend boundary

- frontend/ is a separate React + TypeScript application.

- Based on the repo structure, it is a standalone UI, likely for browsing or demonstrating functionality, and is architecturally separate from the Python MCP runtime.

- It should be treated as an independent client-side subsystem rather than part of the server execution path.

10. Static content

- src/static/index.html and src/static/ indicate the Python service also serves some static HTML assets, likely for a landing page, docs, or a minimal web surface.

- This is distinct from the React frontend, which lives in its own package.

11. Deployment topology

- deploy/ contains production-oriented artifacts: a systemd service, a Caddy config snippet, and a sync-to-prod script.

- That implies the server is intended to run as a long-lived Linux service, usually behind a reverse proxy.

- server.json likely supports runtime/hosting configuration for the MCP/server environment.

12. Developer and validation tooling

- scripts/ includes helpers for API exploration, smoke testing, registry publishing, and activity-table setup.

- tests/ contains automated tests, while docs/ holds API notes and handover material.

- These support the repo’s main purpose: safely adapting an external commerce API into a stable MCP surface.

13. Key architectural flow to diagram

- A good diagram would show:

- MCP clients on the left

- FastMCP server / CLI entrypoint in the center

- Tool modules as the domain adapter layer

- Async Kapruka API client as the outbound integration boundary

- Kapruka REST API on the right

- Side paths for config/env, cache, rate limiting, and activity logging

- Separate boxes for frontend, deployment, and test/tooling as supporting subsystems