43 lines
2.5 KiB
Markdown
43 lines
2.5 KiB
Markdown
# System Architecture (`SYSTEM.md`)
|
|
|
|
## Overview
|
|
|
|
`trymemcp` is a stateless Python **FastMCP** server using the **Streamable HTTP** transport bound to `0.0.0.0:8000`. It translates Model Context Protocol (MCP) `tools/call` invocations into authenticated asynchronous HTTP requests against the **TryMe Gaming App API** (`https://tryme.tpk.pw`).
|
|
|
|
## Architecture Diagram
|
|
|
|
```mermaid
|
|
graph TB
|
|
Client["MCP Client (IDE / Agent / CLI)"] -->|"Streamable HTTP (0.0.0.0:8000/mcp)"| API["FastMCP HTTP Server (app/main.py)"]
|
|
Probe["Docker / K8s Health Probe"] -->|"GET /health"| API
|
|
API --> Tools["29 Typed MCP Tools"]
|
|
Tools --> Service["TryMeClient & Auth Resolver (app/client.py)"]
|
|
Service -->|"HTTPS REST (X-API-Key / Bearer / Cookie)"| External["TryMe Gaming App API (https://tryme.tpk.pw)"]
|
|
```
|
|
|
|
## Request & Authentication Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant C as MCP HTTP Client
|
|
participant M as FastMCP Server (0.0.0.0:8000)
|
|
participant A as TryMeClient Auth Resolver
|
|
participant T as TryMe API (tryme.tpk.pw)
|
|
|
|
C->>M: POST /mcp (tools/call + optional HTTP headers)
|
|
M->>A: Validate tool args via Pydantic models
|
|
A->>A: Resolve auth (1: Tool Arg -> 2: MCP HTTP Header -> 3: Env Var)
|
|
A->>T: Async HTTPS request (httpx.AsyncClient)
|
|
T-->>A: JSON / 204 No Content / 302 Redirect
|
|
A-->>M: Structured Python dict/list (or TryMeApiError)
|
|
M-->>C: MCP JSON-RPC CallToolResult
|
|
```
|
|
|
|
## Module Breakdown
|
|
|
|
- **[`app/config.py`](./app/config.py)**: Reads [`version.ini`](./version.ini) and environment variables (`MCP_HOST=0.0.0.0`, `MCP_PORT=8000`, `MCP_PATH=/mcp`, `TRYME_BASE_URL=https://tryme.tpk.pw`, timeouts, and default credentials).
|
|
- **[`app/models.py`](./app/models.py)**: Pydantic v2 models (`QuestionOptionSchema`, `QuestionIn`) enforcing OpenAPI 3.1 field constraints and generating rich JSON Schemas for MCP tool discovery.
|
|
- **[`app/client.py`](./app/client.py)**: Async `httpx.AsyncClient` wrapper handling three-tier credential resolution, Bearer header normalization, `tryme_session` cookie extraction, redirect reporting, and structured upstream error reporting (`TryMeApiError`).
|
|
- **[`app/main.py`](./app/main.py)**: FastMCP server instance, custom HTTP endpoints (`/health`, `/openapi.yaml`, `/openapi.json`), all 29 MCP tool definitions, ASGI `app`, and `run_server()` CLI entrypoint.
|
|
- **[`helm-chart/`](./helm-chart)** & **[`.gitea/workflows/cicd.yaml`](./.gitea/workflows/cicd.yaml)**: Automated Docker multi-stage build, Harbor & DockerHub image publishing, and Helm OCI chart delivery.
|