trymemcp/SYSTEM.md

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

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

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: Reads 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: Pydantic v2 models (QuestionOptionSchema, QuestionIn) enforcing OpenAPI 3.1 field constraints and generating rich JSON Schemas for MCP tool discovery.
• 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: 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/ & .gitea/workflows/cicd.yaml: Automated Docker multi-stage build, Harbor & DockerHub image publishing, and Helm OCI chart delivery.