mcp-bridge

apps/mcp-bridge lets external Model Context Protocol clients (Claude, IDE agents, custom agents) play games against the bot ladder, request hints, and read KataGo reviews without going through the React UI. It is a thin layer on top of weiqi-server: it does not own game state and does not call KataGo directly.

Tools

Defined in src/tools/:

Tool	Purpose
`list-levels`	Return the ten bot levels with rating + persona metadata.
`start-bot-game`	Start a new game. Input: `{ level, boardSize? }`. Returns `{ gameId }`.
`get-game-state`	Snapshot of a game (board, players, last move, status).
`play-move`	Apply a move; bot replies. Input: `{ gameId, x, y }`.
`request-hint`	One-move hint. Input: `{ gameId }`. Entitlement-gated.
`get-review`	Full KataGo review. Input: `{ gameId }`.

Schemas are declared in src/mcp-server.ts:44-64 with Zod. The Zod schema is also exported as JSON Schema for the MCP tool descriptor.

Transports

Two transports, selected by MCP_TRANSPORT:

http (default) — Express + StreamableHTTPServerTransport on MCP_PORT (default 3003). Bearer-key auth.
stdio — StdioServerTransport. No auth needed; the OS process boundary is the trust boundary. Used when an agent CLI spawns the bridge per session.

Switch via env or CLI:

MCP_TRANSPORT=http pnpm --dir apps/mcp-bridge dev
# or
pnpm --dir apps/mcp-bridge dev -- --transport=stdio --port=3003

Auth gate (HTTP only)

When MCP_TRANSPORT=http, the listener refuses every request unless MCP_API_KEY is set. Clients pass it as Authorization: Bearer <key>. If the key is unset, the HTTP listener exits cleanly (it does not bind).

stdio does not use this gate — the spawner is already trusted.

Bootstrap admin

On startup, the bridge calls auth-app to ensure a stable admin user exists:

AUTH_APP_URL=http://localhost:3004
ADMIN_EMAIL=admin@admin.local
ADMIN_PASSWORD=admin
ADMIN_NAME=AI Bridge Test User

It signs the admin in and uses the resulting userId for all subsequent weiqi-server calls. This avoids juggling user tokens at the agent level.

Feature flag

MCP_ENABLED=false exits the process with code 0 without binding any port. This lets the bridge ship to production alongside the rest of the stack without affecting anyone. Deploy the disabled variant by default and flip the flag on staging only after smoke-testing.

Tier

WEIQI_TIER=pro tells weiqi-server to treat the bridge’s calls as PRO tier (full energy grant, no daily-cap enforcement). This is the right default for automated testing and agent use. Switch to free only when profiling free-tier behaviour.

Environment

MCP_ENABLED=true
MCP_TRANSPORT=http
MCP_PORT=3003
MCP_API_KEY=                       # required for HTTP; unset refuses requests
WEIQI_URL=http://localhost:3002
WEIQI_TIER=pro
AUTH_APP_URL=http://localhost:3004
ADMIN_EMAIL=admin@admin.local
ADMIN_PASSWORD=admin
ADMIN_NAME=AI Bridge Test User

Local dev

cp apps/mcp-bridge/.env.example apps/mcp-bridge/.env
pnpm --dir apps/mcp-bridge dev
# in another shell, register the bridge with an MCP client:
claude mcp add weiqi --transport http http://localhost:3003/mcp \
  --header "Authorization: Bearer $MCP_API_KEY"

Tests

pnpm --dir apps/mcp-bridge test

Suite uses MockKataGoClient on the weiqi-server side and a fake StreamableHTTPServerTransport to round-trip MCP messages without binding real ports.