Skip to main content
Glama
sudokupad-replay-tools MCP server

sudokupad-replay-tools MCP server

by Mikochi-Gake

sudokupad-replay-tools

An unofficial, local-only parser for SudokuPad .replay files, with a drag-and-drop review desk, a small command-line interface, and a read-only MCP server.

It turns SudokuPad's compact replay_v1.0 + clzw action stream into deterministic events: timestamps, selected cells, before/after cell state, solution mismatches, and undo/redo links. Pure selection events are hidden from normal queries unless requested, so an agent does not have to ingest hundreds of low-value clicks.

Status: experimental v0.1.0. Tested against the included synthetic fixtures and one private 1,185-action SudokuPad replay. This project is not affiliated with or endorsed by SudokuPad.

What it does

  • Validates and decodes local replay_v1.0 / clzw files.

  • Reconstructs values, centre marks, corner marks, colours, pen marks, selection, undo, and redo.

  • Preserves every decoded action and its timing; it does not silently discard unknown action codes.

  • Queries a concise, paginated event timeline; selection-only events are off by default.

  • Reconstructs the complete grid after an action or at a replay time.

  • Compares entered values with the embedded solution when one exists.

It intentionally does not provide a replay player, hosted service, AI inference, technique grading, or .progress/zip import in v0.1.0. The review desk reports deterministic timing clues; it does not claim to know what the solver was thinking.

Related MCP server: continuum

Local review desk

On Windows, double-click start-ui.cmd. It builds the project, opens the review desk in your browser, and keeps all processing on this computer. Close the command window to stop it.

You can also start it from a terminal:

npm run ui

Drop a .replay file onto the page and choose one of four views:

  • Errors and rollbacks separates original wrong entries from states restored by undo/redo.

  • Quick check shows puzzle metadata, duration, action count, warnings, and final correctness.

  • Speed clues shows long gaps between meaningful state changes, candidate/value activity, and selection share.

  • Export for Chat downloads a compact .review.json without pure selection events.

The server binds only to 127.0.0.1, makes no remote requests, accepts uploaded file bytes rather than arbitrary server-side paths, and processes them in memory. The existing 8 MiB file limit and decompression limits still apply.

SCL/Penpa embedded puzzle encoding is not supported yet. The page identifies that limitation explicitly instead of pretending it can reconstruct the grid.

Requirements and setup

  • Node.js 20 or newer

  • npm

npm install
npm run check

The build output is written to dist/.

Command line

node dist/src/cli.js inspect /path/to/puzzle.replay
node dist/src/cli.js events /path/to/puzzle.replay --type vl,ud,rd --limit 50
node dist/src/cli.js events /path/to/puzzle.replay --cell r8c8 --include-selection
node dist/src/cli.js events /path/to/puzzle.replay --mismatch-only
node dist/src/cli.js state /path/to/puzzle.replay --action 364
node dist/src/cli.js state /path/to/puzzle.replay --time-ms 600000

All output is JSON. Errors are also JSON and include a stable error code. --action N means the state after action N; action 0 is the initial state.

MCP server

Start the stdio server with:

npm run start:mcp

Or configure any MCP client to launch Node with the absolute path to dist/src/mcp.js. A typical stdio entry looks like this (the surrounding configuration format varies by client):

{
  "command": "node",
  "args": ["C:/absolute/path/to/sudokupad-replay-tools/dist/src/mcp.js"]
}

The server exposes three read-only tools:

  • inspect_replay: metadata, warnings, counts, duration, and final solution check.

  • query_events: filtered, paginated events with state changes and undo/redo links. It hides hl, sl, and ds selection actions by default.

  • get_state: full state after a given action index or at a replay time.

Example agent request: “Inspect this replay, then show value entries and undo/redo events around the first solution mismatch.”

Compatibility and failure policy

The format contract is the container's replay_v1.0 plus replay compression type clzw; the SudokuPad application version is not a strict allow-list. An untested app version produces a warning. Unknown container formats, compression methods, malformed coordinates, or unknown action codes fail explicitly with diagnostics and the last reliable action position where applicable.

Current and legacy action-code tables observed in SudokuPad are supported. Because .replay is not presented here as a stable public specification, new SudokuPad releases may require updates.

Input limits protect machine-facing use: regular files only, 8 MiB compressed file size, 32 MiB per decompressed payload, 250,000 actions, bounded JSON depth, and grid/coordinate checks. Limits are defined in src/limits.ts.

Privacy

Replay files can reveal puzzle titles, solving behaviour, timings, mistakes, and pauses. The parser and MCP server read only the local path explicitly supplied to a command/tool and do not make network requests or modify the replay. They return decoded content to the calling terminal or MCP client, so that client's own privacy rules still apply.

Real user replays are ignored by Git. The committed fixtures under test/fixtures/ are synthetic and contain no user replay data.

Private golden test

The public test suite uses synthetic fixtures. Maintainers can additionally validate a private replay without copying it into the repository:

SUDOKUPAD_GOLDEN_REPLAY=/absolute/path/to/private.replay npm test

PowerShell:

$env:SUDOKUPAD_GOLDEN_REPLAY = 'C:\absolute\path\to\private.replay'
npm test

License and attribution

Project code is licensed under the MIT License. The bounded LZ-String-compatible decompressor in src/lz-string-compat.ts is adapted from LZ-String; see THIRD_PARTY_NOTICES.md.

Acknowledgements

Initial implementation was designed and written with OpenAI Codex using GPT-5.6 Sol, under the project owner's direction and review.

中文速览

这是一个非官方、本地运行的 SudokuPad .replay 解析工具。命令行适合直接检查,MCP 适合让模型按需查询。底层仍保留全部动作;默认查询只隐藏纯选格/取消选格,随时可以用 includeSelection 或 --include-selection 取回。真实回放不会自动上传,也不会作为测试样例提交到 Git。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for searching your local Retrace screen-history database, with tools for full-text search, segment listing, frame details, app usage, and tags.
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Lets an assistant read recorded production AI agent runs — steps, model and tool calls with arguments, and outcomes — along with the findings of comparison runs that checked a prompt or model change against those recordings, and verify a signed evidence bundle offline with no account or network. It is strictly read-only: no tool starts a replay or comparison, so nothing can spend money or act without a person deciding.
      5
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to read a replay link or a gn-tracing-*.zip package, surfacing console errors with source-mapped stacks, failed requests, and the user timeline.
      GPL 3.0