trymemcp/SETUP.md

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