zensudoku
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
zensudoku
Sudoku with value, corner and center notes, six cell colors, undo and redo, hints and conflict marking. One code base, three ways to run it:
a PWA: static files, installable on desktop and Android, works offline;
a zenbot plugin: an entry in the Games tab, a
/sudokucommand, and a coaching skill;an MCP App: the board as an inline widget in any host that supports MCP Apps (Claude, ChatGPT and others), with tools the agent can call.
MIT licensed. No account, no score, no network, no telemetry: progress stays on your device.
The plugin asks zenbot for no permissions (kernel: []): it reads and writes no files.
Play
The board shows one puzzle, Example — classic, which this repository's own generator made. Click or tap a cell, then the pad, or use the keyboard:
Key | Does |
arrows | move |
1–9 | place a digit (or a note, in Corner or Center mode) |
Shift+1–9 | corner note |
v, c, m | Value, Corner, Center mode |
Delete, Backspace, 0 | erase: the value, then the notes, then the color |
Ctrl+Z, Ctrl+Shift+Z, Ctrl+Y | undo, redo |
Placing a digit clears that cell's notes. Givens are protected. A repeated digit, or a broken variant rule, marks the cells and says why. A finished board is locked. Hint points at one cell (a naked or hidden single) and explains it; it never places the digit.
Enter a puzzle takes 81 characters, row by row: digits 1–9, . or 0 for a blank. It is played
only if it has exactly one solution, and it stays in the puzzle list.
The rules engine knows thirteen variants (classic, diagonal, killer, sandwich, thermo,
consecutive, non-consecutive, arrow, renban, Kropki, Little Killer, jigsaw, Samurai); core/catalog.json
holds the puzzles and takes more entries (see parseCatalog in core/sudoku.ts). v0 ships the
one classic example and no puzzle collection.
Related MCP server: chess-mcp
Play it standalone (PWA)
npm ci
npm run build:pwa # the PWA is in shells/web/dist
npm run dev # or a development servershells/web/dist is plain static files (relative URLs), so GitHub Pages, Cloudflare Pages or any
file server hosts it. Open it in a browser and use "Install" (desktop Chrome/Edge, Android) or
"Add to Home Screen" (iOS); after the first visit it works offline.
Install it in zenbot
zen plugins add zensudokuor Settings → Marketplace → zensudoku in the zenbot web app. To try a release archive or a local
build: zen plugins add ./zensudoku-<version>.tgz (see Releasing).
zenbot reads plugin.json: a game (Sudoku, in the Games tab), a /sudoku command that calls
zensudoku_new (in the web chat, in Matrix and from the zen CLI), a coaching skill, and no
permissions. The board follows zenbot's theme.
Use it in Claude, ChatGPT or another MCP Apps host
Download zensudoku-<version>.tgz from the releases,
unpack it, and add a stdio server whose command is node and whose argument is the absolute path of
mcp/dist/server.js. It is one self-contained file: it needs no node_modules, no environment and
no network. From a clone, npm ci && npm run pack makes the same folder layout in dist/.
The tools:
Tool | Does |
| opens the example, or |
| the board as a text grid with conflicts |
| conflicts, solved or not, and how many entries are wrong (a count only) |
| one next logical step with its reason; never the solution |
| app only: the board tells the server what it shows |
The board reports each change to the server and to the chat (updateModelContext), so the agent
sees what you see. The view is ui://zensudoku/app. Hosts that only speak remote (HTTP) MCP need a
bridge: this server speaks stdio only.
Layout
core/ rules, game model, solver, hints: pure TypeScript, tested with vitest
ui/ the Svelte 5 app; host.ts is the MCP App entry, adapters.ts the storage seam
mcp/ the MCP server (bundled with all its dependencies into mcp/dist/server.js)
shells/web/ the PWA: manifest, icons, service worker, entry
skills/ the coaching skill
scripts/ generate-example.ts makes the bundled puzzle from a seed; pack.mjs makes the release archive
tests/ MCP smoke test, release-archive test, Playwright end-to-end testDevelopment
npm ci
npx playwright install chromium # once, for the browser test
npm run check # svelte-check, unit tests, build, pack, archive test, MCP smoke test, browser test
npm run generate # rewrite core/catalog.json (a test checks it is reproducible)Node 22.18 or newer (the scripts run TypeScript directly). The tests keep an independent reference
solver (core/__tests__/reference.ts) that shares no code with the rules, and compare the engine's
answers against it. tests/pack-test.mjs unpacks the release archive into a temporary folder
and runs the MCP smoke test against the extracted server.
Releasing
Set the same
versioninpackage.jsonandplugin.json, commit.npm run packbuilds and writesdist/zensudoku-<version>.tgzand prints its sha256. The archive holds exactlyplugin.json,mcp/dist/server.js,ui/dist/index.html,skills/,README.mdandLICENSE, with relative paths and no links, dot files ornode_modules.Tag
v<version>and push the tag. The release workflow runs the checks, verifies the tag equalsv<package version>andplugin.json's version, and publishes a GitHub release with the archive and its sha256 in the notes.To list a new version in the zenbot marketplace, open a pull request there with the new
version,archiveURL andsha256.
Puzzles and rights
The only bundled puzzle comes from scripts/generate-example.ts: a seeded random fill, then clues
removed while the solution stays unique. No puzzle in this repository comes from a book, a site or
another collection.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Workflow diagnostics, capability routing, and x402 settlement for MCP-compatible agents.
Real-time collaborative whiteboard — AI agents and humans edit the same board live over MCP.
Daily puzzle arena for AI agents over MCP, ranked by step-efficiency on a public leaderboard.
Public MCP for agent verification, work discovery and governed interoperability.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables agents to generate uniquely-solvable Sudoku puzzles, validate partial or complete grids, and solve puzzles using SMT solving with Z3, all through stateless MCP tools.424 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to play and analyze chess, validate moves, and view a live synchronized visual board in the browser through MCP tools.62 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to run autonomous game playtesting, evaluate the agent against seeded bugs, list bug flags, and interactively reset, step, and view game sessions.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible agents to play and manage chess games against Stockfish 16, with legal moves, analysis, hints, coaching feedback, PGN import/export, historical references, and 2D/3D board outputs.Apache 2.0