Sudoku MCP Server

A Cloudflare Worker exposing a small remote MCP server at /mcp. It implements five gameplay tools: start_game, get_game, play_move, check_game, and reset_game.

Local development

npm install
npm run types
npm test
npm run build
npm run dev

The root endpoint is a health response; MCP clients should use http://localhost:8787/mcp.

Related MCP server: toolhive-mcp

Optional secret path

Set the Worker secret SECRET_PATH to a hard-to-guess path string to move the MCP endpoint to /<SECRET_PATH>/mcp. For example, a value of example-secret would make the endpoint /example-secret/mcp; /mcp then returns 404. When SECRET_PATH is unset or empty, the endpoint stays at /mcp.

Set the secret in the Cloudflare dashboard or with npx wrangler secret put SECRET_PATH. For local development, place it in a git-ignored .dev.vars file. When enabled, the root health response does not publish the secret path. Anyone who learns the complete URL can still access the MCP.

Automatic deployment

Cloudflare Workers Builds connects this repository's main branch to the existing sudoku-mcp Worker. Pushing to main deploys it after the tests and type-check pass. The Worker name and Durable Object binding are declared in wrangler.jsonc.

Production runtime variables and secrets are managed in the Cloudflare dashboard, which is the canonical source for them. wrangler.jsonc sets keep_vars: true and intentionally does not declare runtime variables or secrets, so dashboard-managed variables are preserved across deployments. For manual deployment, run npm ci, npm test, npm run build, and npm run deploy.

MCP tool annotations

HARMLESSLY_FAKE_ANNOTATIONS is an optional compatibility switch for MCP clients whose safety layer is overly sensitive to ordinary Sudoku state changes such as entering, erasing, or resetting cells. Set it as a production Worker variable in the Cloudflare dashboard when needed.

• HARMLESSLY_FAKE_ANNOTATIONS=1 makes every tool advertise readOnlyHint: true, destructiveHint: false, and openWorldHint: false.

• HARMLESSLY_FAKE_ANNOTATIONS=0, an unset variable, or any other value emits no tool annotations.

These annotations are intentionally compatibility metadata rather than a literal description of every tool's implementation. The server remains a closed Sudoku game: the affected operations only change reversible game state and do not modify files, accounts, services, or external systems.

Authentication

Wrangler uses Cloudflare OAuth for local CLI operations:

npx wrangler login
npx wrangler whoami

This Worker intentionally has no application-level auth or user-account layer, as specified by the development plan. Add access control at the deployment boundary before exposing a production endpoint.

Game behavior

Puzzles are normalized to one 81-character row-major grid. Whitespace is ignored, . and 0 mean empty, and digits 1-9 are givens. start_game accepts only uniquely solvable puzzles and stores the solution privately inside one SQLite-backed Durable Object per game ID. play_move enforces only visible row/column/box conflicts; check_game is the tool that evaluates entries against the hidden solution. Every state response includes the canonical initial/current grids and a labeled board rendering.