5.4 KiB

Raw Permalink Blame History

Setup Guide (`SETUP.md`)

This guide walks through configuring, running, authenticating, and deploying the TryMe TPK FastMCP HTTP Server (trymemcp).

1. Local Development Setup

Clone the repository and enter the workspace:

git clone <your-gitea-repo-url> trymemcp
cd trymemcp

Create an isolated Python virtual environment and install dependencies:

python3 -m venv venv
venv/bin/pip install --upgrade pip
venv/bin/pip install -e ".[dev]"

Verify the test suite:
```
venv/bin/pytest
```
Start the HTTP MCP server on all interfaces (0.0.0.0:8000):
```
venv/bin/python -m app.main
```
You can also invoke the installed CLI script:
```
venv/bin/trymemcp
```
Or run with Uvicorn directly:
```
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:

Per-Tool Arguments (highest priority): Pass api_key, authorization, or tryme_session directly in any authenticated MCP tool call.
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.
Server Environment Variables (convenient for single-user containers): Set TRYME_API_KEY, TRYME_BEARER_TOKEN, or TRYME_SESSION_COOKIE in the server environment.

Call the get_auth_config tool to check dev_auth_enabled.
Call dev_login(nickname="my_agent") to obtain an access_token.
Call create_api_key(name="mcp-client", expires_in_days=90, authorization="<access_token>") to generate a persistent raw_key.
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`)

{
  "mcpServers": {
    "trymemcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "YOUR_TRYME_API_KEY"
      }
    }
  }
}

Python FastMCP Client

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

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:

curl http://localhost:8000/health

Run with Docker Compose

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 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 triggers automatically on pushes to main and performs:

Version extraction from version.ini (0.1).
Multi-stage Docker image build tagged from the final line of Dockerfile (#harbor.freshbrewed.science/library/trymemcp).
Image push to Harbor (harbor.freshbrewed.science/library/trymemcp:<version>) and DockerHub (<DHUSER>/trymemcp:<version>).
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

5.4 KiB Raw Permalink Blame History

Setup Guide (SETUP.md)