trymemcp/README.md

# 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