# 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.