debuff MCP server

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