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

Automatic deployment

.github/workflows/deploy.yml runs the tests and type-check on pull requests. After a change reaches main, it deploys the Worker automatically. Configure these GitHub Actions secrets before the first production deployment:

• CLOUDFLARE_API_TOKEN: a Cloudflare API token permitted to deploy this Worker.

• CLOUDFLARE_ACCOUNT_ID: the Cloudflare account identifier for this Worker.

The token must be stored as a GitHub secret, never committed to the repository.

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.

• 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.