Enables AI agents to inspect, build, test, and play 2D web games using real-time state, frame data, and automated fuzzing.
Also known as debuffjp/debuff, @debuffjp/mcp
- Stars
- 12
- Tools
- 22
- Downloads, 30 days
- 11,216
- Latest version
- 0.35.0
- Last commit
- Nov 14, 2026
- License
- MIT
What is debuff MCP?
debuff enables AI agents to inspect, build, test, and play 2D web games using real-time state, frame data, and automated fuzzing. It exposes 22 tools, such as inspect_project, list_assets, typecheck.
Summary generated from the project's README
About debuff MCP server
Building and testing 2D web games through an AI agent is what this server enables. It provides developers with a way to inspect project dependencies, run type-checks using the project's own configuration, and execute production builds with size reports. The server works both locally by attaching to a live game tab or by running a private headless browser instance for reproducible testing.
Agents can interact with the game engine using tools like game_step to advance simulation steps, game_input to simulate keyboard or touch interactions, and game_params to tune validated game variables. For debugging, the server offers game_frames to analyze render times and game_errors to identify the source line of runtime issues. It also includes a fuzzing tool that plays with random inputs to find crashes or infinite loops, automatically generating scenarios to replay those specific failures.
Written from the project's README. Every use case is checked against a quote from it.
How to install debuff MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall debuff MCP in Claude Code
$ claude mcp add debuff -- npx -y @debuffjp/mcpInstall debuff MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"debuff": {
"command": "npx",
"args": [
"-y",
"@debuffjp/mcp"
]
}
}
}Install debuff MCP in VS Code
.vscode/mcp.json
{
"servers": {
"debuff": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@debuffjp/mcp"
]
}
}
}Install debuff MCP in VS Code CLI
$ code --add-mcp '{"name":"debuff","type":"stdio","command":"npx","args":["-y","@debuffjp/mcp"]}'Install debuff MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"debuff": {
"command": "npx",
"args": [
"-y",
"@debuffjp/mcp"
]
}
}
}Install debuff MCP in Codex
$ codex mcp add debuff -- npx -y @debuffjp/mcpInstall debuff MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.debuff] command = "npx" args = ["-y", "@debuffjp/mcp"]
Install debuff MCP in Gemini CLI
$ gemini mcp add -s user debuff npx -- -y @debuffjp/mcpInstall debuff MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"debuff": {
"command": "npx",
"args": [
"-y",
"@debuffjp/mcp"
]
}
}
}debuff MCP tools 22
Detected from the READMEinspect_projectlist_assetstypecheckbuildrun_testsrun_scenariosfuzzgame_startgame_stepgame_pausegame_framesgame_notes
| inspect_project | — | |
| list_assets | — | |
| typecheck | — | |
| build | — | |
| run_tests | — | |
| run_scenarios | — | |
| fuzz | — | |
| game_start | — | |
| game_step | — | |
| game_pause | — | |
| game_frames | — | |
| game_notes | — |
Show all 22 toolsShow fewer tools
game_rewindgame_replaygame_inputgame_stategame_commandgame_capturegame_clipgame_errorsgame_stopreport_papercut
| game_rewind | — | |
| game_replay | — | |
| game_input | — | |
| game_state | — | |
| game_command | — | |
| game_capture | — | |
| game_clip | — | |
| game_errors | — | |
| game_stop | — | |
| report_papercut | — |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub@debuffjp/mcp
An MCP server that lets AI agents inspect, build, test and play a debuff game. It uses the same evidence a human would want: real state, real frames, real test results.
Setup
New projects from npm create debuff include a .mcp.json, so MCP clients that read it (such as Claude Code) pick the server up automatically. For other clients:
claude mcp add debuff -- npx -y @debuffjp/mcp # Claude Code
{
"mcpServers": {
"debuff": { "command": "npx", "args": ["-y", "@debuffjp/mcp"] }
}
}
Run it from the game's folder, or pass --root <dir> (or set DEBUFF_ROOT).
As a Claude Code plugin, which also adds a skill that teaches Claude the workflow:
/plugin marketplace add debuffjp/debuff
/plugin install debuff@debuff
As a Codex plugin: codex plugin marketplace add debuffjp/debuff, then codex plugin add debuff@debuff.
For Claude Desktop, mcpb/manifest.json describes a desktop extension that asks for the game folder. Pack it from that folder with npx @anthropic-ai/mcpb pack.
Tools
| Tool | What it does |
|---|---|
inspect_project |
Dependencies, plugins and their contributions, assets, last build size |
list_assets |
Every asset with its type, size and importer, plus warnings and possibly unused ids |
typecheck |
Type-check with the project's own tsc; no browser needed. Vite doesn't type-check, so run it after edits |
build |
Production build plus size report; leaks must be empty |
run_tests |
Run the logic tests in tests/ (keiko): the real game in Node, no browser; failures carry the tick, scene and state |
run_scenarios |
Run scenarios/*.json headless; per-step results, errors, captures |
fuzz |
Play with random input; each crash, stuck state or back-and-forth loop comes with an explained error and a scenario that replays it |
game_start |
Attach to the live game, or open a private headless copy, paused (see below). Headless takes a viewport: [w, h]; reducedMotion forces it on or off |
game_step |
Advance fixed simulation steps (pausing first); returns state (quiet leaves out your inspect() data) |
game_pause |
Pause or resume a live game |
game_frames |
Recent frame breakdown: update/render ms, catch-up steps, quads, draw calls, long tasks; summary gives percentiles and the 3 slowest |
game_notes |
Moments the human flagged in the overlay, with the state at that tick |
game_rewind |
Live mode: take the human's game back (or forward) to a tick, paused, with its exact state then |
game_replay |
Save the live session up to a tick (for example a note's) as a scenario in .debuff/replays/ that reproduces it. From 0.31 it holds state checkpoints, so run_scenarios warns at the tick where the replay stops matching |
game_input |
press / release keys (and PointerRight / PointerMiddle); tap, pointer_down (with an optional kind: mouse, touch or pen), pointer_move, pointer_up; wheel (dy, dx); touch_down, touch_move, touch_up by contact id |
game_state |
Scene, tick, logical width/height, renderer, frame stats, reducedMotion, your inspect() data |
game_command |
Run a command the game registered with devTools({ commands }), with JSON args |
game_params / game_set_param |
Read and tune typed params (validated) |
game_capture |
The current frame as a PNG image; path also saves it in the project (thumbnails, store art). social: true letterboxes it into 1200×675 for X and Bluesky posts (added in 0.26) |
game_clip |
Live mode: start a rolling recording, save the last 15 s as a video in .debuff/captures/, stop. For devlogs and press kits; the human posts. Added in 0.26 |
game_errors |
Runtime errors, explained: whose problem (your code, a rejected call, a debuff bug), the source line, a hint |
game_stop |
Close the game. From 0.28, a headless game also closes after 15 idle minutes, and a call that takes over 60 s fails with game_hung |
report_papercut |
Report tooling friction in debuff, keiko, myaku, spryte or debuff.jp to papercuts.debuff.jp. Returns close matches instead of filing a duplicate; call again with hit: <id> or force: true. With hit, workaround fills the papercut's workaround when it has none (from 0.24.1). Added in 0.24 |
Tool calls that fail on setup twice in a week, or run far too long, are reported to papercuts.debuff.jp on their own, and the result says so (see debuff papercuts in the CLI README to turn it off). From 0.24.
Prompts
Workflows clients can offer as slash commands: playtest, fix-errors, tune-feel, add-mechanic, devlog-post (added in 0.26: capture a still and a clip, then draft short posts for the human to send) and explain-stutter.
Live and headless
If you have the game open under debuff dev, game_start attaches to that tab (mode live). The overlay shows an agent badge, and every pause, step and param change the agent makes appears in its activity log, where you can undo it. Type a note in the overlay ("jump feels floaty here") to flag a moment; the agent reads it, along with the game state at that tick, through game_notes. game_stop resumes your game and disconnects.
Otherwise, or with mode: "headless", the agent gets a private copy in a headless browser. Time only advances through game_step, so what it sees is reproducible, and a scenario can replay it exactly.
debuff MCP questions
How do I add debuff MCP to Claude Code?
Run claude mcp add debuff -- npx -y @debuffjp/mcp in your terminal. Add --scope user to make it available in every project.
How do I add debuff MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does debuff MCP provide?
It exposes 22 tools, including inspect_project, list_assets, typecheck, build, run_tests.
How can I run the server with Claude Code?
You can add the server to Claude Code using the command: claude mcp add debuff -- npx -y @debuffjp/mcp.
Can the AI agent play the game in a browser?
Yes, the agent can attach to a live game running in a browser tab or run a private copy in a headless browser.
What happens during a fuzz test?
The fuzz tool plays with random input, and any crashes, stuck states, or loops are provided with an explained error and a replayable scenario.
How does the agent handle runtime errors?
The game_errors tool provides explained runtime errors, identifying the source line and whether the issue lies in your code, a rejected call, or a debuff bug.