Update

2026-11-11 21:23:16 -06:00 · 2026-11-11 21:23:16 -06:00 · b267cf09ed
parent d58010c735
commit b267cf09ed
25 changed files with 3649 additions and 1 deletions
--- a/.dockerignore
+++ b/.dockerignore
@ -0,0 +1,21 @@
 .git
 .gitignore
 .gitea
 venv
 .venv
 __pycache__
 *.pyc
 *.pyo
 *.pyd
 .pytest_cache
 .mypy_cache
 .ruff_cache
 .coverage
 htmlcov
 dist
 build
 *.egg-info
 .env
 .env.*
 helm-chart/*.tgz
 *.tgz
--- a/.gitea/workflows/cicd.yaml
+++ b/.gitea/workflows/cicd.yaml
@ -0,0 +1,89 @@
 name: Build and Publish Docker Image
 on:
    push:
        branches:
            - main
 jobs:
    build-and-push:
        name: Build and Push Docker Image
        runs-on: my_custom_label
        container: node:22
        steps:
            - name: Checkout Code
              uses: actions/checkout@v3
            - name: Prepare Env for Docker
              run: |
                  whoami
                  which docker || true
                  apt update
                  cat /etc/os-release
                  apt install -y ca-certificates curl gnupg
                  mkdir -p /etc/apt/keyrings
                  curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
                  echo \
                    "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
                    focal stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
                  apt update
                  DEBIAN_FRONTEND=noninteractive apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
            - name: Get Version from version.ini
              id: get_version
              run: |
                  # Extract version value from version.ini
                  VERSION=$(awk -F'=[ \t]*' '/^version[ \t]*=/ {gsub(/[ \t"'\''\r]/, "", $2); print $2}' version.ini)
                  echo "VERSION=$VERSION" >> $GITHUB_ENV
                  echo "version=$VERSION" >> $GITHUB_OUTPUT
            - name: Build Dockerfile
              run: |
                  export BUILDIMGTAG="`cat Dockerfile | tail -n1 | sed 's/^.*\///g'`"
                  docker build -t $BUILDIMGTAG:${{ env.VERSION }} .
                  docker images
            - name: Tag and Push (Harbor)
              run: |
                  export BUILDIMGTAG="`cat Dockerfile | tail -n1 | sed 's/^.*\///g'`"
                  export FINALBUILDTAG="`cat Dockerfile | tail -n1 | sed 's/^#//g'`"
                  docker tag $BUILDIMGTAG:${{ env.VERSION }} $FINALBUILDTAG:${{ env.VERSION }}
                  docker images
                  echo $CR_PAT | docker login harbor.freshbrewed.science -u $CR_USER --password-stdin
                  docker push $FINALBUILDTAG:${{ env.VERSION }}
              env: # Or as an environment variable
                  CR_PAT: ${{ secrets.CR_PAT }}
                  CR_USER: ${{ secrets.CR_USER }}
            - name: Tag and Push (Dockerhub)
              run: |
                  export BUILDIMGTAG="`cat Dockerfile | tail -n1 | sed 's/^.*\///g'`"
                  docker tag $BUILDIMGTAG:${{ env.VERSION }} $DHUSER/$BUILDIMGTAG:${{ env.VERSION }}
                  docker images
                  echo $DHPAT | docker login -u $DHUSER --password-stdin
                  docker push $DHUSER/$BUILDIMGTAG:${{ env.VERSION }}
              env: # Or as an environment variable
                  DHPAT: ${{ secrets.DHPAT }}
                  DHUSER: ${{ secrets.DHUSER }}
            - name: Prepare Env for Helm OCI Push (Helm v3 reference only)
              run: |
                  if [ ! -f /tmp/linux-amd64/helm ]; then
                    apt update
                    DEBIAN_FRONTEND=noninteractive apt-get install -y unzip curl || true
                    wget https://get.helm.sh/helm-v3.14.0-linux-amd64.tar.gz -O /tmp/helm.tar.gz || true
                    cd /tmp
                    tar xzvf helm.tar.gz
                    chmod +x linux-amd64/helm
                  fi
            - name: Package Helm Chart
              run: |
                  set -x
                  /tmp/linux-amd64/helm package ./helm-chart
                  export HLMPKG=`ls -tr *.tgz | tail -n1 |  tr -d '\n'`
                  /tmp/linux-amd64/helm registry login harbor.freshbrewed.science -u $CR_USER -p $CR_PAT
                  /tmp/linux-amd64/helm push ./$HLMPKG oci://harbor.freshbrewed.science/chartrepo/trymemcp-helm
              env: # Or as an environment variable
                  CR_PAT: ${{ secrets.CR_PAT }}
                  CR_USER: ${{ secrets.CR_USER }}
--- a/46
+++ b/46
@ -0,0 +1,46 @@
 # Stage 1: Builder
 FROM python:3.11-slim AS builder
 ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1
 WORKDIR /build
 RUN python -m venv /opt/venv
 ENV PATH="/opt/venv/bin:$PATH"
 COPY pyproject.toml README.md version.ini ./
 COPY app ./app
 RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir .
 # Stage 2: Production runtime
 FROM python:3.11-slim AS runtime
 ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PATH="/opt/venv/bin:$PATH" \
    MCP_HOST="0.0.0.0" \
    MCP_PORT="8000" \
    MCP_PATH="/mcp" \
    TRYME_BASE_URL="https://tryme.tpk.pw"
 WORKDIR /app
 RUN groupadd --gid 1000 appuser && \
    useradd --uid 1000 --gid 1000 --create-home --shell /bin/bash appuser
 COPY --from=builder /opt/venv /opt/venv
 COPY app ./app
 COPY openapi.yaml version.ini README.md ./
 USER appuser
 EXPOSE 8000
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=4)" || exit 1
 CMD ["python", "-m", "app.main"]
 #harbor.freshbrewed.science/library/trymemcp
--- a/INSTALL.md
+++ b/INSTALL.md
@ -0,0 +1,69 @@
 # Installation Guide (`INSTALL.md`)
 Detailed installation, environment configuration, container build, and operator setup instructions for `trymemcp`.
 ## Prerequisites
 - **Python**: `3.11` or newer
 - **Docker**: `24.0+` and Docker Compose v2 (for containerized execution)
 - **Helm**: `v3.14+` (optional, for Kubernetes deployments)
 ## 1. Virtual Environment Installation
 ```bash
 # Create virtual environment
 python3 -m venv venv
 # Upgrade pip and install package + dev dependencies
 venv/bin/pip install --upgrade pip
 venv/bin/pip install -e ".[dev]"
 ```
 ## 2. Environment Variables
 Create an optional `.env` file or export variables directly in your shell:
 ```bash
 export MCP_HOST="0.0.0.0"
 export MCP_PORT="8000"
 export MCP_PATH="/mcp"
 export TRYME_BASE_URL="https://tryme.tpk.pw"
 export TRYME_TIMEOUT_SECONDS="30"
 # Optional server-wide default credentials
 export TRYME_API_KEY=""
 export TRYME_BEARER_TOKEN=""
 export TRYME_SESSION_COOKIE=""
 ```
 > **Database Note**: `trymemcp` is a stateless MCP HTTP proxy/adapter over the upstream TryMe REST API (`https://tryme.tpk.pw`) and does not require a local database or Alembic migrations.
 ## 3. Running the Service
 ```bash
 # Direct Python execution (serves HTTP on 0.0.0.0:8000)
 venv/bin/python -m app.main
 # Run test suite
 venv/bin/pytest
 ```
 ## 4. Docker & Docker Compose Installation
 ```bash
 # Build production multi-stage image
 docker build -t trymemcp:0.1 .
 # Run container on port 8000
 docker run -p 8000:8000 trymemcp:0.1
 # Or run via Docker Compose
 docker compose up --build
 ```
 ## 5. Gitea CI/CD Secrets Setup
 Before pushing to `main`, operators must configure these secrets in the Gitea repository settings for [`.gitea/workflows/cicd.yaml`](./.gitea/workflows/cicd.yaml):
 - `CR_USER` / `CR_PAT`: Harbor container registry & OCI Helm chart repo (`harbor.freshbrewed.science`) credentials.
 - `DHUSER` / `DHPAT`: DockerHub registry credentials.
--- a/README.md
+++ b/README.md
@ -1 +1,149 @@
-# TryMe TPK MCP Server
+# TryMe TPK MCP Server (`trymemcp`)
 A Python [FastMCP](https://gofastmcp.com) **Streamable HTTP** Model Context Protocol (MCP) server bound to all interfaces (`0.0.0.0:8000`) that exposes all **29** API operations from [`https://tryme.tpk.pw/openapi.json`](https://tryme.tpk.pw/openapi.json) as strongly typed MCP tools.
 ## Features
 - **HTTP Transport on All Interfaces (`0.0.0.0`)**: Serves MCP Streamable HTTP at `http://0.0.0.0:8000/mcp` out of the box.
 - **Complete OpenAPI Coverage (29 Tools)**: Covers System Health, Auth0 & Dev Authentication, User Profiles & Personal API Keys, Quiz Creation/Play/Voting, Favourites, and Admin Moderation.
 - **Flexible Authentication**: Supports per-tool credentials (`api_key`, `authorization`, `tryme_session`), automatic HTTP header/cookie passthrough from MCP clients (`X-API-Key`, `Authorization`, `Cookie: tryme_session=...`), and server environment variable defaults (`TRYME_API_KEY`, `TRYME_BEARER_TOKEN`, `TRYME_SESSION_COOKIE`).
 - **Production Container & CI/CD Ready**: Multi-stage `python:3.11-slim` `Dockerfile` with `/health` healthcheck, `docker-compose.yaml`, `helm-chart/`, OpenAPI 3.1 spec (`/openapi.yaml`, `/openapi.json`), and Gitea Actions CI/CD workflow (`.gitea/workflows/cicd.yaml`).
 ---
 ## Quick Start
 ### Prerequisites
 - Python **3.11+** (or Docker 24+ / Docker Compose v2)
 - Optional: A personal TryMe API key (`X-API-Key`) or Bearer token for authenticated endpoints
 ### Run Locally
 ```bash
 python3 -m venv venv
 venv/bin/pip install --upgrade pip
 venv/bin/pip install -e ".[dev]"
 # Start the FastMCP HTTP server on 0.0.0.0:8000
 venv/bin/python -m app.main
 ```
 Or run via Uvicorn directly:
 ```bash
 venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
 ```
 ### Run with Docker / Docker Compose
 ```bash
 # Docker
 docker build -t trymemcp:0.1 .
 docker run --rm -p 8000:8000 -e TRYME_API_KEY="your-api-key" trymemcp:0.1
 # Docker Compose
 docker compose up --build -d
 ```
 ---
 ## Connecting an MCP Client
 Point any Streamable HTTP MCP client at `http://<server-ip>:8000/mcp`:
 ```json
 {
  "mcpServers": {
    "tryme": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "YOUR_TRYME_API_KEY"
      }
    }
  }
 }
 ```
 ---
 ## HTTP Endpoints
 | Method | Path | Description |
 | :--- | :--- | :--- |
 | `POST` / `GET` / `DELETE` | `/mcp` | MCP Streamable HTTP endpoint (JSON-RPC 2.0 + SSE) |
 | `GET` | `/health` | Container & Kubernetes liveness/readiness healthcheck |
 | `GET` | `/openapi.yaml` | OpenAPI 3.1 YAML specification & MCP tool schemas |
 | `GET` | `/openapi.json` | OpenAPI 3.1 JSON specification & MCP tool schemas |
 ---
 ## Exposed MCP Tools (29 Tools)
 ### System
 | Tool | Upstream Endpoint | Description |
 | :--- | :--- | :--- |
 | `healthcheck` | `GET /health` | Check upstream TryMe Gaming App API health |
 ### Authentication
 | Tool | Upstream Endpoint | Description |
 | :--- | :--- | :--- |
 | `get_auth_config` | `GET /api/v1/auth/config` | Get Auth0 settings, dev-auth status, and unclaimed admin status |
 | `auth0_login` | `GET /api/v1/auth/login` | Initiate Auth0 federated login flow |
 | `auth0_callback` | `GET /api/v1/auth/callback` | Complete Auth0 OAuth callback (`code`, `state`) |
 | `dev_login` | `POST /api/v1/auth/dev-login` | Authenticate via dev login (`nickname`, `email`, `as_moderator`) |
 | `logout` | `POST /api/v1/auth/logout` | Log out the active session |
 ### Users & API Keys
 | Tool | Upstream Endpoint | Description |
 | :--- | :--- | :--- |
 | `get_me` | `GET /api/v1/users/me` | Retrieve the authenticated user's profile |
 | `update_me` | `PATCH /api/v1/users/me` | Update nickname, name, age, gender, avatar, or consent |
 | `get_my_scores` | `GET /api/v1/users/me/scores` | Retrieve quiz attempt counts, latest, best, and global best scores |
 | `list_api_keys` | `GET /api/v1/users/me/api-keys` | List personal API keys |
 | `create_api_key` | `POST /api/v1/users/me/api-keys` | Create a personal API key (`name`, `expires_in_days`) |
 | `expire_api_key` | `POST /api/v1/users/me/api-keys/{key_id}/expire` | Immediately expire/revoke an API key |
 ### Quizzes
 | Tool | Upstream Endpoint | Description |
 | :--- | :--- | :--- |
 | `list_quizzes` | `GET /api/v1/quizzes` | Search and list quizzes (`q`, `mode`, `mine_only`) |
 | `create_quiz` | `POST /api/v1/quizzes` | Create a new quiz with multiple-choice or write-in questions |
 | `get_quiz` | `GET /api/v1/quizzes/{slug_or_id}` | Fetch full quiz details by share slug or ID |
 | `update_quiz` | `PUT /api/v1/quizzes/{quiz_id}` | Update an existing quiz |
 | `delete_quiz` | `DELETE /api/v1/quizzes/{quiz_id}` | Delete a quiz owned by the authenticated user |
 | `submit_quiz` | `POST /api/v1/quizzes/{quiz_id}/submit` | Submit quiz answers and receive graded results & scores |
 | `vote_quiz` | `POST /api/v1/quizzes/{quiz_id}/vote` | Upvote (`1`), downvote (`-1`), or clear vote (`0`) on a quiz |
 ### Favourites
 | Tool | Upstream Endpoint | Description |
 | :--- | :--- | :--- |
 | `list_favourites` | `GET /api/v1/favourites` | List favourited quizzes in display order |
 | `add_favourite` | `POST /api/v1/favourites` | Add a quiz to favourites at an optional `position` |
 | `reorder_favourites` | `PUT /api/v1/favourites/reorder` | Reorder favourited quizzes by `quiz_ids` |
 | `remove_favourite` | `DELETE /api/v1/favourites/{quiz_id}` | Remove a quiz from favourites |
 ### Moderation
 | Tool | Upstream Endpoint | Description |
 | :--- | :--- | :--- |
 | `claim_initial_moderator` | `POST /api/v1/admin/claim` | Claim initial moderator/admin privileges if unclaimed |
 | `list_users_for_moderation` | `GET /api/v1/admin/users` | List all users for moderation |
 | `ban_user` | `POST /api/v1/admin/users/{user_id}/ban` | Ban a user with a moderation `reason` |
 | `unban_user` | `POST /api/v1/admin/users/{user_id}/unban` | Unban a user |
 | `list_quizzes_for_moderation` | `GET /api/v1/admin/quizzes` | List all quizzes for moderation |
 | `moderator_remove_quiz` | `DELETE /api/v1/admin/quizzes/{quiz_id}` | Remove any quiz as moderator |
 ---
 ## Testing
 ```bash
 venv/bin/pytest
 ```
 ## Documentation
 - [`SETUP.md`](./SETUP.md) — End-to-end setup, authentication configuration, MCP client setup, Docker/Helm deployment, and Gitea CI/CD guide
 - [`INSTALL.md`](./INSTALL.md) — Environment installation & operator reference
 - [`SYSTEM.md`](./SYSTEM.md) — System architecture & Mermaid diagrams
--- a/SETUP.md
+++ b/SETUP.md
@ -0,0 +1,177 @@
 # Setup Guide (`SETUP.md`)
 This guide walks through configuring, running, authenticating, and deploying the **TryMe TPK FastMCP HTTP Server (`trymemcp`)**.
 ---
 ## 1. Local Development Setup
 1. **Clone the repository and enter the workspace:**
   ```bash
   git clone <your-gitea-repo-url> trymemcp
   cd trymemcp
   ```
 2. **Create an isolated Python virtual environment and install dependencies:**
   ```bash
   python3 -m venv venv
   venv/bin/pip install --upgrade pip
   venv/bin/pip install -e ".[dev]"
   ```
 3. **Verify the test suite:**
   ```bash
   venv/bin/pytest
   ```
 4. **Start the HTTP MCP server on all interfaces (`0.0.0.0:8000`):**
   ```bash
   venv/bin/python -m app.main
   ```
   You can also invoke the installed CLI script:
   ```bash
   venv/bin/trymemcp
   ```
   Or run with Uvicorn directly:
   ```bash
   venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
   ```
 ---
 ## 2. Environment Variables
 | Variable | Default | Description |
 | :--- | :--- | :--- |
 | `MCP_HOST` | `0.0.0.0` | Network interface to bind (defaults to all interfaces) |
 | `MCP_PORT` | `8000` | TCP port for the HTTP server |
 | `MCP_PATH` | `/mcp` | URL path where the MCP Streamable HTTP endpoint is mounted |
 | `TRYME_BASE_URL` | `https://tryme.tpk.pw` | Base URL of the upstream TryMe Gaming App API |
 | `TRYME_TIMEOUT_SECONDS` | `30` | HTTP request timeout (in seconds) when calling TryMe |
 | `TRYME_API_KEY` | *(unset)* | Optional default `X-API-Key` sent on upstream requests |
 | `TRYME_BEARER_TOKEN` | *(unset)* | Optional default `Authorization: Bearer <token>` |
 | `TRYME_SESSION_COOKIE` | *(unset)* | Optional default `tryme_session` cookie value |
 ---
 ## 3. Authentication Options
 Authenticated TryMe endpoints accept credentials from three sources in order of precedence:
 1. **Per-Tool Arguments** (highest priority):
   Pass `api_key`, `authorization`, or `tryme_session` directly in any authenticated MCP tool call.
 2. **Incoming MCP HTTP Headers** (recommended for multi-user HTTP deployments):
   Configure your MCP client to send `X-API-Key: <raw_key>`, `Authorization: Bearer <token>`, or `Cookie: tryme_session=<cookie>` when connecting to `http://<host>:8000/mcp`. The server forwards those credentials per request without storing them globally.
 3. **Server Environment Variables** (convenient for single-user containers):
   Set `TRYME_API_KEY`, `TRYME_BEARER_TOKEN`, or `TRYME_SESSION_COOKIE` in the server environment.
 ### Obtaining an API Key via Dev Login (if enabled upstream)
 1. Call the `get_auth_config` tool to check `dev_auth_enabled`.
 2. Call `dev_login(nickname="my_agent")` to obtain an `access_token`.
 3. Call `create_api_key(name="mcp-client", expires_in_days=90, authorization="<access_token>")` to generate a persistent `raw_key`.
 4. Use `raw_key` in your MCP client's `X-API-Key` header or `TRYME_API_KEY` environment variable.
 ---
 ## 4. Connecting MCP Clients
 ### Antigravity / Claude Code / Cursor (`mcp_config.json`)
 ```json
 {
  "mcpServers": {
    "trymemcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "YOUR_TRYME_API_KEY"
      }
    }
  }
 }
 ```
 ### Python FastMCP Client
 ```python
 import asyncio
 from fastmcp import Client
 from fastmcp.client.transports import StreamableHttpTransport
 async def main():
    transport = StreamableHttpTransport(
        url="http://localhost:8000/mcp",
        headers={"X-API-Key": "YOUR_TRYME_API_KEY"},
    )
    async with Client(transport) as client:
        tools = await client.list_tools()
        print(f"Connected! {len(tools)} tools available.")
        quizzes = await client.call_tool("list_quizzes", {"q": ""})
        print(quizzes)
 asyncio.run(main())
 ```
 ---
 ## 5. Docker & Docker Compose Setup
 ### Build and Run with Docker
 ```bash
 docker build -t trymemcp:0.1 .
 docker run -d \
  --name trymemcp \
  -p 8000:8000 \
  -e TRYME_BASE_URL="https://tryme.tpk.pw" \
  -e TRYME_API_KEY="YOUR_TRYME_API_KEY" \
  trymemcp:0.1
 ```
 Check container health:
 ```bash
 curl http://localhost:8000/health
 ```
 ### Run with Docker Compose
 ```bash
 TRYME_API_KEY="YOUR_TRYME_API_KEY" docker compose up --build -d
 ```
 ---
 ## 6. Helm / Kubernetes Deployment
 A Helm chart is included under [`helm-chart/`](./helm-chart):
 ```bash
 helm upgrade --install trymemcp ./helm-chart \
  --namespace tryme --create-namespace \
  --set image.tag="0.1" \
  --set secrets.trymeApiKey="YOUR_TRYME_API_KEY"
 ```
 ---
 ## 7. Gitea Actions CI/CD Configuration
 The workflow at [`.gitea/workflows/cicd.yaml`](./.gitea/workflows/cicd.yaml) triggers automatically on pushes to `main` and performs:
 1. Version extraction from [`version.ini`](./version.ini) (`0.1`).
 2. Multi-stage Docker image build tagged from the final line of [`Dockerfile`](./Dockerfile) (`#harbor.freshbrewed.science/library/trymemcp`).
 3. Image push to Harbor (`harbor.freshbrewed.science/library/trymemcp:<version>`) and DockerHub (`<DHUSER>/trymemcp:<version>`).
 4. Helm chart packaging (`./helm-chart`) and OCI push to `oci://harbor.freshbrewed.science/chartrepo/trymemcp-helm`.
 ### Required Gitea Repository Secrets
 Configure the following secrets in your Gitea repository (**Settings -> Actions -> Secrets**):
 | Secret | Purpose |
 | :--- | :--- |
 | `CR_USER` | Harbor registry & OCI chart repository username |
 | `CR_PAT` | Harbor registry & OCI chart repository access token / password |
 | `DHUSER` | DockerHub username |
 | `DHPAT` | DockerHub personal access token |
--- a/SYSTEM.md
+++ b/SYSTEM.md
@ -0,0 +1,42 @@
 # 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.
--- a/app/init.py
+++ b/app/init.py
@ -0,0 +1,5 @@
 """TryMe TPK FastMCP HTTP Server package."""
 from app.config import get_version
 __version__ = get_version()
--- a/app/client.py
+++ b/app/client.py
@ -0,0 +1,178 @@
 """Async HTTP client for the TryMe Gaming App API."""
 from __future__ import annotations
 from http.cookies import SimpleCookie
 from typing import Any
 import httpx
 from fastmcp.server.dependencies import get_http_headers
 from app.config import Settings, settings
 class TryMeApiError(RuntimeError):
    """Raised when the upstream TryMe API returns an error response."""
    def __init__(self, status_code: int, detail: Any, path: str) -> None:
        self.status_code = status_code
        self.detail = detail
        self.path = path
        super().__init__(f"TryMe API error ({status_code}) on {path}: {detail}")
 def _normalize_authorization(value: str) -> str:
    """Ensure raw tokens are prefixed with 'Bearer ' while preserving full auth headers."""
    cleaned = value.strip()
    if not cleaned:
        return ""
    if " " in cleaned:
        return cleaned
    return f"Bearer {cleaned}"
 def _extract_cookie_from_header(cookie_header: str | None, name: str) -> str | None:
    """Extract a named cookie from an incoming HTTP Cookie header string."""
    if not cookie_header:
        return None
    cookie = SimpleCookie()
    try:
        cookie.load(cookie_header)
    except Exception:
        return None
    morsel = cookie.get(name)
    return morsel.value if morsel else None
 def _safe_incoming_headers() -> dict[str, str]:
    """Read incoming MCP HTTP headers if running inside an HTTP request context."""
    try:
        raw = get_http_headers(include_all=True) or {}
        return {k.lower(): v for k, v in raw.items() if isinstance(v, str)}
    except Exception:
        return {}
 class TryMeClient:
    """HTTP client wrapper for interacting with https://tryme.tpk.pw."""
    def __init__(
        self,
        config: Settings | None = None,
        transport: httpx.AsyncBaseTransport | None = None,
    ) -> None:
        self.config = config or settings
        self._transport = transport
    def build_auth(
        self,
        *,
        api_key: str | None = None,
        authorization: str | None = None,
        tryme_session: str | None = None,
    ) -> tuple[dict[str, str], dict[str, str]]:
        """Resolve authentication headers and cookies with precedence:
        1. Explicit tool parameters
        2. Incoming MCP HTTP request headers/cookies
        3. Server environment variables
        """
        incoming = _safe_incoming_headers()
        headers: dict[str, str] = {}
        cookies: dict[str, str] = {}
        resolved_api_key = (
            api_key
            or incoming.get("x-api-key")
            or self.config.tryme_api_key
        )
        if resolved_api_key:
            headers["X-API-Key"] = resolved_api_key.strip()
        resolved_auth = (
            authorization
            or incoming.get("authorization")
            or self.config.tryme_bearer_token
        )
        if resolved_auth:
            norm = _normalize_authorization(resolved_auth)
            if norm:
                headers["Authorization"] = norm
        resolved_session = (
            tryme_session
            or _extract_cookie_from_header(incoming.get("cookie"), "tryme_session")
            or self.config.tryme_session_cookie
        )
        if resolved_session:
            cookies["tryme_session"] = resolved_session.strip()
        return headers, cookies
    async def request(
        self,
        method: str,
        path: str,
        *,
        params: dict[str, Any] | None = None,
        json_body: Any = None,
        api_key: str | None = None,
        authorization: str | None = None,
        tryme_session: str | None = None,
        follow_redirects: bool = False,
    ) -> Any:
        """Send an async HTTP request to the TryMe API and parse the response."""
        headers, cookies = self.build_auth(
            api_key=api_key,
            authorization=authorization,
            tryme_session=tryme_session,
        )
        headers.setdefault("Accept", "application/json")
        cleaned_params: dict[str, Any] | None = None
        if params:
            cleaned_params = {k: v for k, v in params.items() if v is not None}
        async with httpx.AsyncClient(
            base_url=self.config.tryme_base_url,
            timeout=self.config.tryme_timeout_seconds,
            follow_redirects=follow_redirects,
            cookies=cookies,
            transport=self._transport,
        ) as http:
            response = await http.request(
                method=method.upper(),
                url=path,
                params=cleaned_params,
                json=json_body,
                headers=headers,
            )
        if 300 <= response.status_code < 400:
            result: dict[str, Any] = {
                "status_code": response.status_code,
                "redirect_url": response.headers.get("location", ""),
            }
            set_cookie = response.headers.get("set-cookie")
            if set_cookie:
                result["cookies_set"] = True
            return result
        if response.status_code == 204 or not response.content:
            return None
        if response.status_code >= 400:
            try:
                err_payload = response.json()
                detail = err_payload.get("detail", err_payload) if isinstance(err_payload, dict) else err_payload
            except Exception:
                detail = response.text
            raise TryMeApiError(response.status_code, detail, path)
        content_type = response.headers.get("content-type", "")
        if "application/json" in content_type:
            return response.json()
        try:
            return response.json()
        except Exception:
            return {"status_code": response.status_code, "text": response.text}
--- a/app/config.py
+++ b/app/config.py
@ -0,0 +1,65 @@
 """Configuration management for the TryMe FastMCP HTTP server."""
 from __future__ import annotations
 import configparser
 import os
 from dataclasses import dataclass
 from pathlib import Path
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
 def get_version() -> str:
    """Read application version from version.ini."""
    version_file = PROJECT_ROOT / "version.ini"
    if version_file.exists():
        parser = configparser.ConfigParser()
        parser.read(version_file, encoding="utf-8")
        if parser.has_option("version", "version"):
            return parser.get("version", "version").strip()
    return "0.1"
@dataclass(slots=True)
 class Settings:
    """Runtime settings populated from environment variables."""
    version: str
    mcp_host: str
    mcp_port: int
    mcp_path: str
    tryme_base_url: str
    tryme_timeout_seconds: float
    tryme_api_key: str | None
    tryme_bearer_token: str | None
    tryme_session_cookie: str | None
    @classmethod
    def from_env(cls) -> Settings:
        """Load settings from current process environment."""
        raw_path = os.getenv("MCP_PATH", "/mcp").strip() or "/mcp"
        if not raw_path.startswith("/"):
            raw_path = f"/{raw_path}"
        api_key = os.getenv("TRYME_API_KEY", "").strip() or None
        bearer_token = os.getenv("TRYME_BEARER_TOKEN", "").strip() or None
        session_cookie = os.getenv("TRYME_SESSION_COOKIE", "").strip() or None
        return cls(
            version=get_version(),
            mcp_host=os.getenv("MCP_HOST", "0.0.0.0").strip() or "0.0.0.0",
            mcp_port=int(os.getenv("MCP_PORT", "8000")),
            mcp_path=raw_path,
            tryme_base_url=(
                os.getenv("TRYME_BASE_URL", "https://tryme.tpk.pw").strip().rstrip("/")
                or "https://tryme.tpk.pw"
            ),
            tryme_timeout_seconds=float(os.getenv("TRYME_TIMEOUT_SECONDS", "30")),
            tryme_api_key=api_key,
            tryme_bearer_token=bearer_token,
            tryme_session_cookie=session_cookie,
        )
 settings = Settings.from_env()
--- a/app/main.py
+++ b/app/main.py
@ -0,0 +1,801 @@
 """FastMCP HTTP server exposing all tools from https://tryme.tpk.pw/openapi.json."""
 from __future__ import annotations
 from typing import Annotated, Any, Literal
 import yaml
 from fastmcp import FastMCP
 from pydantic import Field
 from starlette.requests import Request
 from starlette.responses import JSONResponse, PlainTextResponse, Response
 from app.client import TryMeClient
 from app.config import PROJECT_ROOT, settings
 from app.models import QuestionIn
 _client = TryMeClient(config=settings)
 def get_client() -> TryMeClient:
    """Return the active TryMe API client instance."""
    return _client
 def set_client(client: TryMeClient) -> None:
    """Override the active TryMe API client instance (primarily for testing)."""
    global _client
    _client = client
 mcp = FastMCP(
    name="TryMe TPK MCP Server",
    version=settings.version,
    instructions=(
        "MCP HTTP server for the TryMe Gaming App API (https://tryme.tpk.pw). "
        "Provides tools for student quiz creation, discovery, gameplay/submission, "
        "voting, favourites, leaderboards/scores, Auth0/dev authentication, personal "
        "API keys, and admin moderation. Authenticated endpoints accept optional "
        "`api_key`, `authorization` (Bearer token), or `tryme_session` parameters, "
        "and also inherit incoming HTTP headers or server environment variables "
        "(`TRYME_API_KEY`, `TRYME_BEARER_TOKEN`, `TRYME_SESSION_COOKIE`)."
    ),
 )
 # ---------------------------------------------------------------------------
 # Custom HTTP Endpoints (Healthcheck & OpenAPI Specification)
 # ---------------------------------------------------------------------------
 OPENAPI_PATH = PROJECT_ROOT / "openapi.yaml"
@mcp.custom_route("/health", methods=["GET"], name="server_health")
 async def server_health(_request: Request) -> Response:
    """Container and service healthcheck endpoint."""
    return JSONResponse(
        {
            "status": "ok",
            "service": "trymemcp",
            "version": settings.version,
            "transport": "http",
            "host": settings.mcp_host,
            "port": settings.mcp_port,
            "mcp_endpoint": settings.mcp_path,
            "upstream_url": settings.tryme_base_url,
        }
    )
@mcp.custom_route("/openapi.yaml", methods=["GET"], name="openapi_yaml")
 async def serve_openapi_yaml(_request: Request) -> Response:
    """Serve the server's OpenAPI 3.1 YAML specification."""
    if not OPENAPI_PATH.exists():
        return JSONResponse({"detail": "openapi.yaml not found"}, status_code=404)
    content = OPENAPI_PATH.read_text(encoding="utf-8")
    return PlainTextResponse(content, media_type="application/yaml")
@mcp.custom_route("/openapi.json", methods=["GET"], name="openapi_json")
 async def serve_openapi_json(_request: Request) -> Response:
    """Serve the server's OpenAPI 3.1 JSON specification."""
    if not OPENAPI_PATH.exists():
        return JSONResponse({"detail": "openapi.yaml not found"}, status_code=404)
    spec = yaml.safe_load(OPENAPI_PATH.read_text(encoding="utf-8"))
    return JSONResponse(spec)
 # ---------------------------------------------------------------------------
 # Shared Auth Parameter Type Aliases
 # ---------------------------------------------------------------------------
 ApiKeyParam = Annotated[
    str | None,
    Field(
        default=None,
        description="Optional TryMe API key (`X-API-Key` header). Overrides server default if provided.",
    ),
 ]
 AuthorizationParam = Annotated[
    str | None,
    Field(
        default=None,
        description="Optional Bearer token or `Authorization` header value.",
    ),
 ]
 SessionCookieParam = Annotated[
    str | None,
    Field(
        default=None,
        description="Optional `tryme_session` cookie value.",
    ),
 ]
 # ---------------------------------------------------------------------------
 # System Tools
 # ---------------------------------------------------------------------------
@mcp.tool(tags={"System"})
 async def healthcheck() -> dict[str, Any]:
    """Check the health status of the upstream TryMe Gaming App API (`GET /health`)."""
    return await get_client().request("GET", "/health")
 # ---------------------------------------------------------------------------
 # Authentication Tools
 # ---------------------------------------------------------------------------
@mcp.tool(tags={"Authentication"})
 async def get_auth_config() -> dict[str, Any]:
    """Retrieve Auth0 federated login settings, dev-auth status, and admin claim status (`GET /api/v1/auth/config`)."""
    return await get_client().request("GET", "/api/v1/auth/config")
@mcp.tool(tags={"Authentication"})
 async def auth0_login(
    return_to: Annotated[
        str,
        Field(default="/", description="Relative path to redirect to after login."),
    ] = "/",
 ) -> dict[str, Any]:
    """Initiate the Auth0 federated login flow (`GET /api/v1/auth/login`)."""
    return await get_client().request(
        "GET",
        "/api/v1/auth/login",
        params={"return_to": return_to},
        follow_redirects=False,
    )
@mcp.tool(tags={"Authentication"})
 async def auth0_callback(
    code: Annotated[str, Field(description="Authorization code returned by Auth0.")],
    state: Annotated[str, Field(description="CSRF state parameter returned by Auth0.")],
 ) -> dict[str, Any]:
    """Handle the Auth0 OAuth callback (`GET /api/v1/auth/callback`)."""
    return await get_client().request(
        "GET",
        "/api/v1/auth/callback",
        params={"code": code, "state": state},
        follow_redirects=False,
    )
@mcp.tool(tags={"Authentication"})
 async def dev_login(
    nickname: Annotated[
        str,
        Field(min_length=2, max_length=48, description="User nickname (2-48 chars)."),
    ],
    email: Annotated[
        str | None,
        Field(default=None, max_length=255, description="Optional email address."),
    ] = None,
    as_moderator: Annotated[
        bool,
        Field(default=False, description="Request moderator privileges in dev mode."),
    ] = False,
 ) -> dict[str, Any]:
    """Authenticate using the development login endpoint (`POST /api/v1/auth/dev-login`).
    Returns an `access_token`, `token_type`, and `user` profile when dev auth is enabled.
    """
    payload: dict[str, Any] = {
        "nickname": nickname,
        "email": email,
        "as_moderator": as_moderator,
    }
    return await get_client().request("POST", "/api/v1/auth/dev-login", json_body=payload)
@mcp.tool(tags={"Authentication"})
 async def logout(
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Log out the current authenticated session (`POST /api/v1/auth/logout`)."""
    await get_client().request(
        "POST",
        "/api/v1/auth/logout",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
    return {"status": "logged_out"}
 # ---------------------------------------------------------------------------
 # Users & API Keys Tools
 # ---------------------------------------------------------------------------
@mcp.tool(tags={"Users & API Keys"})
 async def get_me(
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Retrieve the authenticated user's profile (`GET /api/v1/users/me`)."""
    return await get_client().request(
        "GET",
        "/api/v1/users/me",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Users & API Keys"})
 async def update_me(
    nickname: Annotated[
        str | None,
        Field(default=None, min_length=2, max_length=48, description="Updated nickname."),
    ] = None,
    first_name: Annotated[
        str | None,
        Field(default=None, max_length=80, description="Updated first name."),
    ] = None,
    last_name: Annotated[
        str | None,
        Field(default=None, max_length=80, description="Updated last name."),
    ] = None,
    age: Annotated[
        int | None,
        Field(default=None, ge=4, le=120, description="Updated age (4-120)."),
    ] = None,
    clear_age: Annotated[
        bool,
        Field(default=False, description="Set to true to clear the stored age."),
    ] = False,
    gender: Annotated[
        str | None,
        Field(default=None, description="Updated gender value."),
    ] = None,
    gender_custom: Annotated[
        str | None,
        Field(default=None, max_length=80, description="Custom gender text."),
    ] = None,
    avatar_animal: Annotated[
        str | None,
        Field(default=None, description="Avatar animal identifier."),
    ] = None,
    avatar_color: Annotated[
        str | None,
        Field(default=None, description="Avatar color identifier."),
    ] = None,
    public_website_consent: Annotated[
        bool | None,
        Field(default=None, description="Public website display consent flag."),
    ] = None,
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Update the authenticated user's profile (`PATCH /api/v1/users/me`)."""
    payload: dict[str, Any] = {}
    optional_fields = {
        "nickname": nickname,
        "first_name": first_name,
        "last_name": last_name,
        "age": age,
        "gender": gender,
        "gender_custom": gender_custom,
        "avatar_animal": avatar_animal,
        "avatar_color": avatar_color,
        "public_website_consent": public_website_consent,
    }
    for key, value in optional_fields.items():
        if value is not None:
            payload[key] = value
    if clear_age:
        payload["clear_age"] = True
    return await get_client().request(
        "PATCH",
        "/api/v1/users/me",
        json_body=payload,
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Users & API Keys"})
 async def get_my_scores(
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> list[dict[str, Any]]:
    """Retrieve quiz score summaries and attempt counts for the authenticated user (`GET /api/v1/users/me/scores`)."""
    return await get_client().request(
        "GET",
        "/api/v1/users/me/scores",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Users & API Keys"})
 async def list_api_keys(
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> list[dict[str, Any]]:
    """List personal API keys belonging to the authenticated user (`GET /api/v1/users/me/api-keys`)."""
    return await get_client().request(
        "GET",
        "/api/v1/users/me/api-keys",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Users & API Keys"})
 async def create_api_key(
    name: Annotated[
        str,
        Field(min_length=1, max_length=80, description="Descriptive name for the API key."),
    ],
    expires_in_days: Annotated[
        int | None,
        Field(
            default=90,
            ge=1,
            le=3650,
            description="Number of days until expiration (1-3650), or null for non-expiring if supported.",
        ),
    ] = 90,
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Create a new personal API key (`POST /api/v1/users/me/api-keys`). Returns `raw_key` once."""
    payload = {"name": name, "expires_in_days": expires_in_days}
    return await get_client().request(
        "POST",
        "/api/v1/users/me/api-keys",
        json_body=payload,
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Users & API Keys"})
 async def expire_api_key(
    key_id: Annotated[int, Field(description="Numeric ID of the API key to expire/revoke.")],
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Expire/revoke an existing personal API key (`POST /api/v1/users/me/api-keys/{key_id}/expire`)."""
    return await get_client().request(
        "POST",
        f"/api/v1/users/me/api-keys/{key_id}/expire",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
 # ---------------------------------------------------------------------------
 # Quizzes Tools
 # ---------------------------------------------------------------------------
@mcp.tool(tags={"Quizzes"})
 async def list_quizzes(
    q: Annotated[
        str | None,
        Field(default=None, max_length=120, description="Optional search query string."),
    ] = None,
    mode: Annotated[
        str | None,
        Field(
            default=None,
            description="Optional quiz mode filter (e.g. 'multiple_choice', 'write_in', 'mixed').",
        ),
    ] = None,
    mine_only: Annotated[
        bool,
        Field(default=False, description="If true, return only quizzes authored by the authenticated user."),
    ] = False,
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> list[dict[str, Any]]:
    """Search and list quizzes (`GET /api/v1/quizzes`)."""
    return await get_client().request(
        "GET",
        "/api/v1/quizzes",
        params={"q": q, "mode": mode, "mine_only": mine_only},
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Quizzes"})
 async def create_quiz(
    title: Annotated[
        str,
        Field(min_length=1, max_length=140, description="Quiz title (1-140 chars)."),
    ],
    description: Annotated[
        str,
        Field(default="", max_length=1000, description="Quiz description (up to 1000 chars)."),
    ] = "",
    is_public: Annotated[
        bool,
        Field(default=True, description="Whether the quiz is publicly listed."),
    ] = True,
    questions: Annotated[
        list[QuestionIn] | None,
        Field(default=None, max_length=40, description="Up to 40 quiz questions."),
    ] = None,
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Create a new quiz (`POST /api/v1/quizzes`)."""
    payload: dict[str, Any] = {
        "title": title,
        "description": description,
        "is_public": is_public,
        "questions": [q.model_dump() for q in (questions or [])],
    }
    return await get_client().request(
        "POST",
        "/api/v1/quizzes",
        json_body=payload,
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Quizzes"})
 async def get_quiz(
    slug_or_id: Annotated[
        str,
        Field(description="Quiz share slug or numeric quiz ID (passed as string)."),
    ],
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Retrieve full details and questions for a quiz (`GET /api/v1/quizzes/{slug_or_id}`)."""
    return await get_client().request(
        "GET",
        f"/api/v1/quizzes/{slug_or_id}",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Quizzes"})
 async def update_quiz(
    quiz_id: Annotated[int, Field(description="Numeric ID of the quiz to update.")],
    title: Annotated[
        str,
        Field(min_length=1, max_length=140, description="Updated quiz title (1-140 chars)."),
    ],
    description: Annotated[
        str,
        Field(default="", max_length=1000, description="Updated quiz description (up to 1000 chars)."),
    ] = "",
    is_public: Annotated[
        bool,
        Field(default=True, description="Whether the quiz is publicly listed."),
    ] = True,
    questions: Annotated[
        list[QuestionIn] | None,
        Field(default=None, max_length=40, description="Full updated list of up to 40 quiz questions."),
    ] = None,
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Update an existing quiz (`PUT /api/v1/quizzes/{quiz_id}`)."""
    payload: dict[str, Any] = {
        "title": title,
        "description": description,
        "is_public": is_public,
    }
    if questions is not None:
        payload["questions"] = [q.model_dump() for q in questions]
    return await get_client().request(
        "PUT",
        f"/api/v1/quizzes/{quiz_id}",
        json_body=payload,
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Quizzes"})
 async def delete_quiz(
    quiz_id: Annotated[int, Field(description="Numeric ID of the quiz to delete.")],
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Delete a quiz authored by the authenticated user (`DELETE /api/v1/quizzes/{quiz_id}`)."""
    await get_client().request(
        "DELETE",
        f"/api/v1/quizzes/{quiz_id}",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
    return {"status": "deleted", "quiz_id": quiz_id}
@mcp.tool(tags={"Quizzes"})
 async def submit_quiz(
    quiz_id: Annotated[int, Field(description="Numeric ID of the quiz to submit answers for.")],
    answers: Annotated[
        dict[str, str],
        Field(
            default_factory=dict,
            description="Mapping of question ID (as string) to submitted option ID or write-in answer.",
        ),
    ],
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Submit answers for a quiz and receive graded results & scores (`POST /api/v1/quizzes/{quiz_id}/submit`)."""
    return await get_client().request(
        "POST",
        f"/api/v1/quizzes/{quiz_id}/submit",
        json_body={"answers": answers},
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Quizzes"})
 async def vote_quiz(
    quiz_id: Annotated[int, Field(description="Numeric ID of the quiz to vote on.")],
    value: Annotated[
        Literal[-1, 0, 1],
        Field(description="Vote value: `1` (upvote), `-1` (downvote), or `0` (remove vote)."),
    ],
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Upvote, downvote, or clear vote on a quiz (`POST /api/v1/quizzes/{quiz_id}/vote`)."""
    return await get_client().request(
        "POST",
        f"/api/v1/quizzes/{quiz_id}/vote",
        json_body={"value": value},
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
 # ---------------------------------------------------------------------------
 # Favourites Tools
 # ---------------------------------------------------------------------------
@mcp.tool(tags={"Favourites"})
 async def list_favourites(
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> list[dict[str, Any]]:
    """List the authenticated user's favourited quizzes (`GET /api/v1/favourites`)."""
    return await get_client().request(
        "GET",
        "/api/v1/favourites",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Favourites"})
 async def add_favourite(
    quiz_id: Annotated[int, Field(description="Numeric ID of the quiz to favourite.")],
    position: Annotated[
        int | None,
        Field(default=None, ge=0, description="Optional 0-based position in the favourites list."),
    ] = None,
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> list[dict[str, Any]]:
    """Add a quiz to the authenticated user's favourites (`POST /api/v1/favourites`)."""
    payload: dict[str, Any] = {"quiz_id": quiz_id}
    if position is not None:
        payload["position"] = position
    return await get_client().request(
        "POST",
        "/api/v1/favourites",
        json_body=payload,
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Favourites"})
 async def reorder_favourites(
    quiz_ids: Annotated[
        list[int],
        Field(description="Ordered list of favourited quiz IDs representing the desired order."),
    ],
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> list[dict[str, Any]]:
    """Reorder the authenticated user's favourited quizzes (`PUT /api/v1/favourites/reorder`)."""
    return await get_client().request(
        "PUT",
        "/api/v1/favourites/reorder",
        json_body={"quiz_ids": quiz_ids},
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Favourites"})
 async def remove_favourite(
    quiz_id: Annotated[int, Field(description="Numeric ID of the quiz to remove from favourites.")],
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> list[dict[str, Any]]:
    """Remove a quiz from the authenticated user's favourites (`DELETE /api/v1/favourites/{quiz_id}`)."""
    return await get_client().request(
        "DELETE",
        f"/api/v1/favourites/{quiz_id}",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
 # ---------------------------------------------------------------------------
 # Moderation Tools
 # ---------------------------------------------------------------------------
@mcp.tool(tags={"Moderation"})
 async def claim_initial_moderator(
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Claim initial moderator/admin status when no admin exists (`POST /api/v1/admin/claim`)."""
    return await get_client().request(
        "POST",
        "/api/v1/admin/claim",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Moderation"})
 async def list_users_for_moderation(
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> list[dict[str, Any]]:
    """List all users for admin moderation (`GET /api/v1/admin/users`). Requires moderator privileges."""
    return await get_client().request(
        "GET",
        "/api/v1/admin/users",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Moderation"})
 async def ban_user(
    user_id: Annotated[int, Field(description="Numeric ID of the user to ban.")],
    reason: Annotated[
        str,
        Field(
            default="Community guidelines violation",
            max_length=255,
            description="Reason for banning the user.",
        ),
    ] = "Community guidelines violation",
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Ban a user (`POST /api/v1/admin/users/{user_id}/ban`). Requires moderator privileges."""
    return await get_client().request(
        "POST",
        f"/api/v1/admin/users/{user_id}/ban",
        json_body={"reason": reason},
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Moderation"})
 async def unban_user(
    user_id: Annotated[int, Field(description="Numeric ID of the user to unban.")],
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Unban a previously banned user (`POST /api/v1/admin/users/{user_id}/unban`). Requires moderator privileges."""
    return await get_client().request(
        "POST",
        f"/api/v1/admin/users/{user_id}/unban",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Moderation"})
 async def list_quizzes_for_moderation(
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> list[dict[str, Any]]:
    """List all quizzes for admin moderation (`GET /api/v1/admin/quizzes`). Requires moderator privileges."""
    return await get_client().request(
        "GET",
        "/api/v1/admin/quizzes",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
@mcp.tool(tags={"Moderation"})
 async def moderator_remove_quiz(
    quiz_id: Annotated[int, Field(description="Numeric ID of the quiz to remove.")],
    api_key: ApiKeyParam = None,
    authorization: AuthorizationParam = None,
    tryme_session: SessionCookieParam = None,
 ) -> dict[str, Any]:
    """Remove any quiz as a moderator (`DELETE /api/v1/admin/quizzes/{quiz_id}`). Requires moderator privileges."""
    await get_client().request(
        "DELETE",
        f"/api/v1/admin/quizzes/{quiz_id}",
        api_key=api_key,
        authorization=authorization,
        tryme_session=tryme_session,
    )
    return {"status": "removed", "quiz_id": quiz_id}
 # ASGI application for Uvicorn / Gunicorn (`uvicorn app.main:app --host 0.0.0.0 --port 8000`)
 app = mcp.http_app(path=settings.mcp_path, transport="http")
 def run_server() -> None:
    """Start the FastMCP HTTP server bound to 0.0.0.0 (all interfaces) by default."""
    mcp.run(
        transport="http",
        host=settings.mcp_host,
        port=settings.mcp_port,
        path=settings.mcp_path,
    )
 if __name__ == "__main__":
    run_server()
--- a/app/models.py
+++ b/app/models.py
@ -0,0 +1,53 @@
 """Pydantic input schemas aligned with https://tryme.tpk.pw/openapi.json."""
 from __future__ import annotations
 from typing import Literal
 from pydantic import BaseModel, Field
 class QuestionOptionSchema(BaseModel):
    """Multiple-choice option for a quiz question."""
    id: str = Field(
        ...,
        min_length=1,
        max_length=32,
        description="Option identifier (e.g. 'a', 'b', 'opt1').",
    )
    text: str = Field(
        ...,
        min_length=1,
        max_length=300,
        description="Display text of the answer option.",
    )
 class QuestionIn(BaseModel):
    """Input schema for creating or updating a quiz question."""
    question_type: Literal["multiple_choice", "write_in"] = Field(
        ...,
        description="Type of question: 'multiple_choice' or 'write_in'.",
    )
    prompt: str = Field(
        ...,
        min_length=1,
        max_length=1000,
        description="Question prompt displayed to quiz players.",
    )
    options: list[QuestionOptionSchema] = Field(
        default_factory=list,
        description="List of selectable options (used when question_type is 'multiple_choice').",
    )
    correct_answer: str = Field(
        ...,
        min_length=1,
        max_length=500,
        description="Option ID (for multiple_choice) or canonical answer text (for write_in).",
    )
    accepted_answers: list[str] = Field(
        default_factory=list,
        description="Additional accepted write-in answers.",
    )
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@ -0,0 +1,24 @@
 services:
  trymemcp:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: trymemcp
    ports:
      - "8000:8000"
    environment:
      MCP_HOST: "0.0.0.0"
      MCP_PORT: "8000"
      MCP_PATH: "/mcp"
      TRYME_BASE_URL: "${TRYME_BASE_URL:-https://tryme.tpk.pw}"
      TRYME_TIMEOUT_SECONDS: "${TRYME_TIMEOUT_SECONDS:-30}"
      TRYME_API_KEY: "${TRYME_API_KEY:-}"
      TRYME_BEARER_TOKEN: "${TRYME_BEARER_TOKEN:-}"
      TRYME_SESSION_COOKIE: "${TRYME_SESSION_COOKIE:-}"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=4)"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
--- a/helm-chart/Chart.yaml
+++ b/helm-chart/Chart.yaml
@ -0,0 +1,6 @@
 apiVersion: v2
 name: trymemcp
 description: A Helm chart for TryMe TPK FastMCP HTTP Server
 type: application
 version: 0.1.0
 appVersion: "0.1"
--- a/helm-chart/templates/_helpers.tpl
+++ b/helm-chart/templates/_helpers.tpl
@ -0,0 +1,28 @@
 {{- define "trymemcp.name" -}}
 {{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
 {{- end }}
 {{- define "trymemcp.fullname" -}}
 {{- if .Values.fullnameOverride }}
 {{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
 {{- else }}
 {{- $name := default .Chart.Name .Values.nameOverride }}
 {{- if contains $name .Release.Name }}
 {{- .Release.Name | trunc 63 | trimSuffix "-" }}
 {{- else }}
 {{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
 {{- end }}
 {{- end }}
 {{- end }}
 {{- define "trymemcp.labels" -}}
 helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
 {{ include "trymemcp.selectorLabels" . }}
 app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
 app.kubernetes.io/managed-by: {{ .Release.Service }}
 {{- end }}
 {{- define "trymemcp.selectorLabels" -}}
 app.kubernetes.io/name: {{ include "trymemcp.name" . }}
 app.kubernetes.io/instance: {{ .Release.Name }}
 {{- end }}
--- a/helm-chart/templates/deployment.yaml
+++ b/helm-chart/templates/deployment.yaml
@ -0,0 +1,61 @@
 apiVersion: apps/v1
 kind: Deployment
 metadata:
  name: {{ include "trymemcp.fullname" . }}
  labels:
    {{- include "trymemcp.labels" . | nindent 4 }}
 spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "trymemcp.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "trymemcp.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - name: http
              containerPort: {{ .Values.service.port }}
              protocol: TCP
          env:
            - name: MCP_HOST
              value: {{ .Values.env.MCP_HOST | quote }}
            - name: MCP_PORT
              value: {{ .Values.env.MCP_PORT | quote }}
            - name: MCP_PATH
              value: {{ .Values.env.MCP_PATH | quote }}
            - name: TRYME_BASE_URL
              value: {{ .Values.env.TRYME_BASE_URL | quote }}
            - name: TRYME_TIMEOUT_SECONDS
              value: {{ .Values.env.TRYME_TIMEOUT_SECONDS | quote }}
            {{- if .Values.secrets.trymeApiKey }}
            - name: TRYME_API_KEY
              value: {{ .Values.secrets.trymeApiKey | quote }}
            {{- end }}
            {{- if .Values.secrets.trymeBearerToken }}
            - name: TRYME_BEARER_TOKEN
              value: {{ .Values.secrets.trymeBearerToken | quote }}
            {{- end }}
            {{- if .Values.secrets.trymeSessionCookie }}
            - name: TRYME_SESSION_COOKIE
              value: {{ .Values.secrets.trymeSessionCookie | quote }}
            {{- end }}
          livenessProbe:
            httpGet:
              path: /health
              port: http
            initialDelaySeconds: 5
            periodSeconds: 15
          readinessProbe:
            httpGet:
              path: /health
              port: http
            initialDelaySeconds: 3
            periodSeconds: 10
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
--- a/helm-chart/templates/service.yaml
+++ b/helm-chart/templates/service.yaml
@ -0,0 +1,15 @@
 apiVersion: v1
 kind: Service
 metadata:
  name: {{ include "trymemcp.fullname" . }}
  labels:
    {{- include "trymemcp.labels" . | nindent 4 }}
 spec:
  type: {{ .Values.service.type }}
  ports:
    - port: {{ .Values.service.port }}
      targetPort: http
      protocol: TCP
      name: http
  selector:
    {{- include "trymemcp.selectorLabels" . | nindent 4 }}
--- a/helm-chart/values.yaml
+++ b/helm-chart/values.yaml
@ -0,0 +1,30 @@
 replicaCount: 1
 image:
  repository: harbor.freshbrewed.science/library/trymemcp
  pullPolicy: IfNotPresent
  tag: "0.1"
 service:
  type: ClusterIP
  port: 8000
 env:
  MCP_HOST: "0.0.0.0"
  MCP_PORT: "8000"
  MCP_PATH: "/mcp"
  TRYME_BASE_URL: "https://tryme.tpk.pw"
  TRYME_TIMEOUT_SECONDS: "30"
 secrets:
  trymeApiKey: ""
  trymeBearerToken: ""
  trymeSessionCookie: ""
 resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi
--- a/openapi.yaml
+++ b/openapi.yaml
--- a/pyproject.toml
+++ b/pyproject.toml
@ -0,0 +1,33 @@
 [build-system]
 requires = ["setuptools>=77.0", "wheel"]
 build-backend = "setuptools.build_meta"
 [project]
 name = "trymemcp"
 version = "0.1.0"
 description = "FastMCP HTTP server exposing tools for the TryMe Gaming App API (https://tryme.tpk.pw)"
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
 authors = [
    { name = "TryMe Team" }
 ]
 dependencies = [
    "fastmcp>=2.0.0",
    "httpx>=0.27.0",
    "pydantic>=2.0.0",
    "pyyaml>=6.0.0",
    "uvicorn>=0.30.0",
 ]
 [project.optional-dependencies]
 dev = [
    "pytest>=8.0.0",
    "pytest-asyncio>=0.23.0",
 ]
 [project.scripts]
 trymemcp = "app.main:run_server"
 [tool.setuptools.packages.find]
 include = ["app*"]
--- a/pytest.ini
+++ b/pytest.ini
@ -0,0 +1,8 @@
 [pytest]
 testpaths = tests
 asyncio_mode = auto
 asyncio_default_fixture_loop_scope = function
 python_files = test_*.py
 python_classes = Test*
 python_functions = test_*
 addopts = -v --tb=short
--- a/tests/init.py
+++ b/tests/init.py
@ -0,0 +1 @@
 """Test suite for TryMe TPK FastMCP HTTP Server."""
--- a/tests/conftest.py
+++ b/tests/conftest.py
@ -0,0 +1,144 @@
 """Shared pytest fixtures for testing the TryMe FastMCP HTTP server."""
 from __future__ import annotations
 import json
 from dataclasses import dataclass, field
 from typing import Any
 import httpx
 import pytest
 from app.client import TryMeClient
 from app.config import Settings
 from app.main import get_client, set_client
@dataclass
 class RecordedCall:
    """Captured upstream HTTP request made by TryMeClient."""
    method: str
    path: str
    query: dict[str, str]
    headers: dict[str, str]
    body: Any
@dataclass
 class UpstreamMockState:
    """Stateful recorder and configurable responder for MockTransport."""
    calls: list[RecordedCall] = field(default_factory=list)
    next_status: int | None = None
    next_json: Any = None
    next_headers: dict[str, str] = field(default_factory=dict)
@pytest.fixture
 def mock_upstream() -> Any:
    """Install a MockTransport-backed TryMeClient and restore original client afterward."""
    state = UpstreamMockState()
    original_client = get_client()
    async def handler(request: httpx.Request) -> httpx.Response:
        raw_body = request.content.decode("utf-8") if request.content else ""
        parsed_body: Any = None
        if raw_body:
            try:
                parsed_body = json.loads(raw_body)
            except Exception:
                parsed_body = raw_body
        state.calls.append(
            RecordedCall(
                method=request.method,
                path=request.url.path,
                query=dict(request.url.params),
                headers={k.lower(): v for k, v in request.headers.items()},
                body=parsed_body,
            )
        )
        if state.next_status is not None:
            status = state.next_status
            payload = state.next_json
            resp_headers = dict(state.next_headers)
            state.next_status = None
            state.next_json = None
            state.next_headers.clear()
            if status == 204 or (300 <= status < 400 and payload is None):
                return httpx.Response(status_code=status, headers=resp_headers)
            return httpx.Response(status_code=status, json=payload, headers=resp_headers)
        # Default realistic responses by method + path
        path = request.url.path
        method = request.method.upper()
        if path == "/health":
            return httpx.Response(200, json={"status": "ok", "service": "trymeapp", "version": "0.2"})
        if path == "/api/v1/auth/config":
            return httpx.Response(
                200,
                json={
                    "auth0_enabled": True,
                    "auth0_domain": "example.us.auth0.com",
                    "auth0_client_id": "client123",
                    "auth0_audience": "",
                    "dev_auth_enabled": True,
                    "admin_unclaimed": False,
                },
            )
        if path in ("/api/v1/auth/login", "/api/v1/auth/callback"):
            return httpx.Response(
                302,
                headers={"location": "https://example.us.auth0.com/authorize"},
            )
        if path == "/api/v1/auth/dev-login":
            return httpx.Response(
                200,
                json={
                    "access_token": "dev-jwt-token",
                    "token_type": "bearer",
                    "user": {"id": 1, "nickname": parsed_body.get("nickname", "tester")},
                },
            )
        if method in ("DELETE", "POST") and path in (
            "/api/v1/auth/logout",
        ):
            return httpx.Response(204)
        if method == "DELETE" and (
            path.startswith("/api/v1/quizzes/") or path.startswith("/api/v1/admin/quizzes/")
        ):
            return httpx.Response(204)
        if path in (
            "/api/v1/users/me/scores",
            "/api/v1/users/me/api-keys",
            "/api/v1/quizzes",
            "/api/v1/favourites",
            "/api/v1/admin/users",
            "/api/v1/admin/quizzes",
        ) and method == "GET":
            return httpx.Response(200, json=[{"ok": True, "path": path}])
        if path.startswith("/api/v1/favourites") and method in ("POST", "PUT", "DELETE"):
            return httpx.Response(200, json=[{"favourite_id": 1, "position": 0, "quiz": {"id": 10}}])
        return httpx.Response(200, json={"ok": True, "method": method, "path": path, "body": parsed_body})
    test_settings = Settings(
        version="0.1",
        mcp_host="0.0.0.0",
        mcp_port=8000,
        mcp_path="/mcp",
        tryme_base_url="https://tryme.tpk.pw",
        tryme_timeout_seconds=10.0,
        tryme_api_key="env-default-key",
        tryme_bearer_token=None,
        tryme_session_cookie=None,
    )
    client = TryMeClient(config=test_settings, transport=httpx.MockTransport(handler))
    set_client(client)
    try:
        yield state
    finally:
        set_client(original_client)
--- a/tests/test_main.py
+++ b/tests/test_main.py
@ -0,0 +1,353 @@
 """Unit and integration tests for the TryMe TPK FastMCP HTTP server."""
 from __future__ import annotations
 import asyncio
 import json
 import socket
 from typing import Any
 import httpx
 import pytest
 import uvicorn
 import yaml
 from fastmcp import Client
 from fastmcp.client.transports import StreamableHttpTransport
 from fastmcp.exceptions import ToolError
 from app.config import Settings, get_version
 from app.main import app, mcp
 from tests.conftest import UpstreamMockState
 EXPECTED_TOOLS = {
    # System
    "healthcheck",
    # Authentication
    "get_auth_config",
    "auth0_login",
    "auth0_callback",
    "dev_login",
    "logout",
    # Users & API Keys
    "get_me",
    "update_me",
    "get_my_scores",
    "list_api_keys",
    "create_api_key",
    "expire_api_key",
    # Quizzes
    "list_quizzes",
    "create_quiz",
    "get_quiz",
    "update_quiz",
    "delete_quiz",
    "submit_quiz",
    "vote_quiz",
    # Favourites
    "list_favourites",
    "add_favourite",
    "reorder_favourites",
    "remove_favourite",
    # Moderation
    "claim_initial_moderator",
    "list_users_for_moderation",
    "ban_user",
    "unban_user",
    "list_quizzes_for_moderation",
    "moderator_remove_quiz",
 }
 def _unwrap_result(result: Any) -> Any:
    """Extract structured/JSON payload from a FastMCP CallToolResult."""
    if getattr(result, "structured_content", None) is not None:
        sc = result.structured_content
        if isinstance(sc, dict) and set(sc.keys()) == {"result"}:
            return sc["result"]
        return sc
    if getattr(result, "data", None) is not None:
        return result.data
    for item in getattr(result, "content", []):
        if hasattr(item, "text"):
            return json.loads(item.text)
    return None
 def test_default_settings_bind_all_interfaces(monkeypatch: pytest.MonkeyPatch) -> None:
    """Default configuration binds HTTP server to 0.0.0.0:8000 on /mcp."""
    for var in ("MCP_HOST", "MCP_PORT", "MCP_PATH", "TRYME_BASE_URL"):
        monkeypatch.delenv(var, raising=False)
    cfg = Settings.from_env()
    assert cfg.mcp_host == "0.0.0.0"
    assert cfg.mcp_port == 8000
    assert cfg.mcp_path == "/mcp"
    assert cfg.tryme_base_url == "https://tryme.tpk.pw"
    assert get_version() == "0.1"
 async def test_custom_http_routes_health_and_openapi() -> None:
    """Verify /health, /openapi.yaml, and /openapi.json on the HTTP ASGI app."""
    transport = httpx.ASGITransport(app=app)
    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as http:
        health_resp = await http.get("/health")
        assert health_resp.status_code == 200
        health_data = health_resp.json()
        assert health_data["status"] == "ok"
        assert health_data["service"] == "trymemcp"
        assert health_data["transport"] == "http"
        assert health_data["host"] == "0.0.0.0"
        yaml_resp = await http.get("/openapi.yaml")
        assert yaml_resp.status_code == 200
        parsed_yaml = yaml.safe_load(yaml_resp.text)
        assert parsed_yaml["openapi"] == "3.1.0"
        assert len(parsed_yaml["x-mcp-tools"]) == 29
        json_resp = await http.get("/openapi.json")
        assert json_resp.status_code == 200
        assert json_resp.json()["info"]["title"] == "TryMe TPK FastMCP HTTP Server"
 async def test_all_29_openapi_tools_registered() -> None:
    """Ensure all 29 operations from https://tryme.tpk.pw/openapi.json are exposed."""
    async with Client(mcp) as client:
        tools = await client.list_tools()
        names = {t.name for t in tools}
        assert names == EXPECTED_TOOLS
        assert len(names) == 29
 async def test_system_and_auth_tools(mock_upstream: UpstreamMockState) -> None:
    """Test system healthcheck and authentication tools."""
    async with Client(mcp) as client:
        res = _unwrap_result(await client.call_tool("healthcheck", {}))
        assert res["status"] == "ok"
        assert mock_upstream.calls[-1].path == "/health"
        cfg = _unwrap_result(await client.call_tool("get_auth_config", {}))
        assert cfg["auth0_enabled"] is True
        login_res = _unwrap_result(await client.call_tool("auth0_login", {"return_to": "/dashboard"}))
        assert login_res["status_code"] == 302
        assert "authorize" in login_res["redirect_url"]
        assert mock_upstream.calls[-1].query == {"return_to": "/dashboard"}
        cb_res = _unwrap_result(
            await client.call_tool("auth0_callback", {"code": "abc", "state": "xyz"})
        )
        assert cb_res["status_code"] == 302
        assert mock_upstream.calls[-1].query == {"code": "abc", "state": "xyz"}
        dev_res = _unwrap_result(
            await client.call_tool(
                "dev_login",
                {"nickname": "quizmaster", "email": "qm@example.com", "as_moderator": True},
            )
        )
        assert dev_res["access_token"] == "dev-jwt-token"
        assert mock_upstream.calls[-1].body == {
            "nickname": "quizmaster",
            "email": "qm@example.com",
            "as_moderator": True,
        }
        logout_res = _unwrap_result(
            await client.call_tool("logout", {"authorization": "raw-jwt-token"})
        )
        assert logout_res == {"status": "logged_out"}
        assert mock_upstream.calls[-1].headers["authorization"] == "Bearer raw-jwt-token"
 async def test_users_and_api_keys_tools(mock_upstream: UpstreamMockState) -> None:
    """Test user profile, scores, and API key lifecycle tools."""
    async with Client(mcp) as client:
        # Uses env fallback X-API-Key when no explicit key is passed
        await client.call_tool("get_me", {})
        assert mock_upstream.calls[-1].path == "/api/v1/users/me"
        assert mock_upstream.calls[-1].headers["x-api-key"] == "env-default-key"
        # Explicit api_key overrides env default
        await client.call_tool(
            "update_me",
            {
                "nickname": "new_nick",
                "age": 16,
                "public_website_consent": True,
                "api_key": "override-key",
            },
        )
        last = mock_upstream.calls[-1]
        assert last.method == "PATCH"
        assert last.headers["x-api-key"] == "override-key"
        assert last.body == {
            "nickname": "new_nick",
            "age": 16,
            "public_website_consent": True,
        }
        scores = _unwrap_result(await client.call_tool("get_my_scores", {}))
        assert isinstance(scores, list)
        assert mock_upstream.calls[-1].path == "/api/v1/users/me/scores"
        keys = _unwrap_result(await client.call_tool("list_api_keys", {}))
        assert isinstance(keys, list)
        assert mock_upstream.calls[-1].path == "/api/v1/users/me/api-keys"
        await client.call_tool("create_api_key", {"name": "ci-agent", "expires_in_days": 30})
        assert mock_upstream.calls[-1].method == "POST"
        assert mock_upstream.calls[-1].body == {"name": "ci-agent", "expires_in_days": 30}
        await client.call_tool("expire_api_key", {"key_id": 42})
        assert mock_upstream.calls[-1].path == "/api/v1/users/me/api-keys/42/expire"
 async def test_quiz_tools(mock_upstream: UpstreamMockState) -> None:
    """Test quiz listing, CRUD, submission, and voting tools."""
    async with Client(mcp) as client:
        await client.call_tool(
            "list_quizzes",
            {"q": "science", "mode": "multiple_choice", "mine_only": True},
        )
        assert mock_upstream.calls[-1].query == {
            "q": "science",
            "mode": "multiple_choice",
            "mine_only": "true",
        }
        await client.call_tool(
            "create_quiz",
            {
                "title": "Space Trivia",
                "description": "Planets and stars",
                "is_public": True,
                "questions": [
                    {
                        "question_type": "multiple_choice",
                        "prompt": "Closest planet to the Sun?",
                        "options": [
                            {"id": "a", "text": "Mercury"},
                            {"id": "b", "text": "Venus"},
                        ],
                        "correct_answer": "a",
                        "accepted_answers": [],
                    }
                ],
            },
        )
        created_call = mock_upstream.calls[-1]
        assert created_call.method == "POST"
        assert created_call.path == "/api/v1/quizzes"
        assert created_call.body["title"] == "Space Trivia"
        assert created_call.body["questions"][0]["correct_answer"] == "a"
        await client.call_tool("get_quiz", {"slug_or_id": "space-trivia"})
        assert mock_upstream.calls[-1].path == "/api/v1/quizzes/space-trivia"
        await client.call_tool(
            "update_quiz",
            {"quiz_id": 7, "title": "Updated Space Trivia", "is_public": False},
        )
        assert mock_upstream.calls[-1].method == "PUT"
        assert mock_upstream.calls[-1].path == "/api/v1/quizzes/7"
        del_res = _unwrap_result(await client.call_tool("delete_quiz", {"quiz_id": 7}))
        assert del_res == {"status": "deleted", "quiz_id": 7}
        assert mock_upstream.calls[-1].method == "DELETE"
        await client.call_tool(
            "submit_quiz",
            {"quiz_id": 7, "answers": {"101": "a", "102": "42"}},
        )
        assert mock_upstream.calls[-1].path == "/api/v1/quizzes/7/submit"
        assert mock_upstream.calls[-1].body == {"answers": {"101": "a", "102": "42"}}
        await client.call_tool("vote_quiz", {"quiz_id": 7, "value": 1})
        assert mock_upstream.calls[-1].path == "/api/v1/quizzes/7/vote"
        assert mock_upstream.calls[-1].body == {"value": 1}
 async def test_favourites_and_moderation_tools(mock_upstream: UpstreamMockState) -> None:
    """Test favourites management and admin moderation tools."""
    async with Client(mcp) as client:
        await client.call_tool("list_favourites", {})
        assert mock_upstream.calls[-1].path == "/api/v1/favourites"
        await client.call_tool("add_favourite", {"quiz_id": 12, "position": 0})
        assert mock_upstream.calls[-1].body == {"quiz_id": 12, "position": 0}
        await client.call_tool("reorder_favourites", {"quiz_ids": [12, 5, 9]})
        assert mock_upstream.calls[-1].method == "PUT"
        assert mock_upstream.calls[-1].body == {"quiz_ids": [12, 5, 9]}
        await client.call_tool("remove_favourite", {"quiz_id": 12})
        assert mock_upstream.calls[-1].method == "DELETE"
        assert mock_upstream.calls[-1].path == "/api/v1/favourites/12"
        await client.call_tool("claim_initial_moderator", {})
        assert mock_upstream.calls[-1].path == "/api/v1/admin/claim"
        await client.call_tool("list_users_for_moderation", {})
        assert mock_upstream.calls[-1].path == "/api/v1/admin/users"
        await client.call_tool("ban_user", {"user_id": 99, "reason": "Spamming quizzes"})
        assert mock_upstream.calls[-1].path == "/api/v1/admin/users/99/ban"
        assert mock_upstream.calls[-1].body == {"reason": "Spamming quizzes"}
        await client.call_tool("unban_user", {"user_id": 99})
        assert mock_upstream.calls[-1].path == "/api/v1/admin/users/99/unban"
        await client.call_tool("list_quizzes_for_moderation", {})
        assert mock_upstream.calls[-1].path == "/api/v1/admin/quizzes"
        mod_del = _unwrap_result(await client.call_tool("moderator_remove_quiz", {"quiz_id": 55}))
        assert mod_del == {"status": "removed", "quiz_id": 55}
        assert mock_upstream.calls[-1].path == "/api/v1/admin/quizzes/55"
 async def test_upstream_error_raises_tool_error(mock_upstream: UpstreamMockState) -> None:
    """Verify upstream 4xx/5xx responses surface cleanly as MCP ToolErrors."""
    mock_upstream.next_status = 401
    mock_upstream.next_json = {"detail": "Invalid or expired API key"}
    async with Client(mcp) as client:
        with pytest.raises(ToolError, match="401"):
            await client.call_tool("get_me", {})
 async def test_live_http_server_on_all_interfaces_and_header_passthrough(
    mock_upstream: UpstreamMockState,
 ) -> None:
    """Start HTTP server bound to 0.0.0.0 and verify MCP HTTP client & header forwarding."""
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock.bind(("0.0.0.0", 0))
    port = sock.getsockname()[1]
    http_app = mcp.http_app(path="/mcp", transport="http")
    config = uvicorn.Config(http_app, host="0.0.0.0", port=port, log_level="error")
    server = uvicorn.Server(config)
    task = asyncio.create_task(server.serve(sockets=[sock]))
    try:
        while not server.started:
            await asyncio.sleep(0.02)
        transport = StreamableHttpTransport(
            url=f"http://127.0.0.1:{port}/mcp",
            headers={
                "X-API-Key": "client-header-api-key",
                "Cookie": "tryme_session=session-cookie-abc",
            },
        )
        async with Client(transport) as client:
            tools = await client.list_tools()
            assert len(tools) == 29
            await client.call_tool("get_me", {})
            last_call = mock_upstream.calls[-1]
            assert last_call.headers["x-api-key"] == "client-header-api-key"
            assert "tryme_session=session-cookie-abc" in last_call.headers.get("cookie", "")
    finally:
        server.should_exit = True
        await task
        sock.close()
--- a/version.ini
+++ b/version.ini
@ -0,0 +1,2 @@
 [version]
 version = 0.1
		`@ -0,0 +1 @@`
							`"""Test suite for TryMe TPK FastMCP HTTP Server."""`