debuff — Claude Code MCP server: test and play your 2D game
Lets a coding agent attach to a live 2D game, step the simulation, read explained errors and replay a crash. Useful when you need evidence, not guesses.
claude mcp add debuff -- npx -y @debuffjp/mcpWhat debuff does
The server either hooks into the tab you already have open under debuff dev or spins up a private copy in a headless browser. In live mode the agent works on your session: every pause, step and parameter change lands in an activity log you can undo. Headless time moves only through game_step, so a scenario replays the same run exactly.
The tool list covers the whole loop. inspect_project and list_assets report dependencies, plugins, assets and warnings. typecheck runs the project's own tsc, which matters because Vite skips type checking — run it after edits. build produces the production bundle with a size report, run_tests executes the logic tests in tests/ inside Node with no browser, and fuzz throws random input at the game until it crashes or loops, handing back a scenario that reproduces the failure. For performance there is game_frames with percentiles and the three slowest frames; game_errors tells you whether the fault is yours, a rejected call or a debuff bug, and points at the source line.
Start it from the game folder, or pass --root <dir> or set DEBUFF_ROOT. Projects created with npm create debuff ship a .mcp.json, so Claude picks the server up on its own.
What it helps with
- read the current scene, tick and frame stats without opening a browser
- catch a crash or a back-and-forth loop with random input and get a replay
- find out whether a runtime error is your code or the engine
- type-check after edits that Vite never checks
- save a PNG of the current frame for thumbnails or store art
Example prompts for the agent
- Run
fuzzand tell me which tick the game got stuck on - Start the game headless and step the simulation ten times
- Run
typecheckandbuild, then show me the size report
How to install debuff
Platform CLI
claude mcp add debuff -- npx -y @debuffjp/mcpPlatform CLI
codex mcp add mcp -- npx -y @debuffjp/mcpConfig file
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@debuffjp/mcp"
]
}
}
}Config file
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@debuffjp/mcp"
]
}
}
}Platform CLI
gemini mcp add mcp npx -y @debuffjp/mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about debuff
How do I install debuff in Claude Code?
Run claude mcp add debuff -- npx -y @debuffjp/mcp. For the plugin route, add the marketplace with /plugin marketplace add debuffjp/debuff and then /plugin install debuff@debuff; the plugin also brings a skill that explains the workflow.
What does debuff do?
It hands an agent tools for a debuff 2D game: project and asset inspection, builds, logic tests, fuzzing, step-by-step runs and frame captures. Errors arrive explained, with the source line.
How is live mode different from headless?
Live attaches to your open tab, and the agent's pauses and steps show up in an activity log where you can undo them. Headless gives the agent a private copy where time advances only through game_step, which makes every run reproducible.
