trymemcp/README.md

TryMe TPK MCP Server (trymemcp)

A Python FastMCP 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 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

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:

venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000

Run with Docker / Docker Compose

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

{
  "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

venv/bin/pytest

Documentation

• SETUP.md — End-to-end setup, authentication configuration, MCP client setup, Docker/Helm deployment, and Gitea CI/CD guide
• INSTALL.md — Environment installation & operator reference
• SYSTEM.md — System architecture & Mermaid diagrams