debuff

@debuffjp/mcp

一个 MCP 服务，让 AI Agent 能够检查、构建、测试并游玩 debuff 游戏。它使用人类也会看重的真实证据：实际状态、实际帧和实际测试结果。

设置

通过 npm create debuff 创建的新项目会包含 .mcp.json，因此会自动被读取该文件的 MCP 客户端（例如 Claude Code）发现。对于其他客户端：

claude mcp add debuff -- npx -y @debuffjp/mcp        # Claude Code

{
  "mcpServers": {
    "debuff": { "command": "npx", "args": ["-y", "@debuffjp/mcp"] }
  }
}

在游戏文件夹中运行，或传入 --root <dir>（或设置 DEBUFF_ROOT）。

作为 Claude Code 插件使用时，还会添加一个技能，教会 Claude 工作流：

/plugin marketplace add debuffjp/debuff
/plugin install debuff@debuff

作为 Codex 插件使用：codex plugin marketplace add debuffjp/debuff，然后运行 codex plugin add debuff@debuff。

对于 Claude Desktop，mcpb/manifest.json 描述了一个会要求选择游戏文件夹的桌面扩展。在该文件夹中运行 npx @anthropic-ai/mcpb pack 进行打包。

工具

工具	功能
inspect_project	依赖项、插件及其贡献、资源、上次构建的大小
list_assets	每个资源的类型、大小和导入器，以及警告和可能未使用的 ID
typecheck	使用项目自己的 tsc 进行类型检查；无需浏览器。Vite 不会进行类型检查，因此编辑后请运行此工具
build	生产构建及大小报告；leaks 必须为空
run_tests	运行 tests/ 中的逻辑测试（keiko）：在 Node 中运行真实游戏，无需浏览器；失败信息包含 tick、场景和状态
run_scenarios	无头运行 scenarios/*.json；提供每一步的结果、错误和截图
fuzz	使用随机输入游玩；每次崩溃、卡死状态或来回循环都会附带说明性错误和可重现该问题的场景
game_start	连接到正在运行的游戏，或打开一个暂停的私有无头副本（见下文）。无头模式需要 viewport: [w, h]；reducedMotion 可强制开启或关闭
game_step	推进固定的模拟步数（需先暂停）；返回状态（quiet 会省略你的 inspect() 数据）
game_pause	暂停或恢复正在运行的游戏
game_frames	最近的帧分析：更新／渲染耗时（毫秒）、追赶步数、四边形数量、绘制调用、长任务；summary 提供百分位数和最慢的 3 项
game_notes	人类在覆盖层中标记的时刻，以及该 tick 的状态
game_rewind	实时模式：将人类的游戏回退（或前进）到某个 tick，并暂停，同时提供该时刻的精确状态
game_replay	将某个 tick 之前的实时会话（例如某条笔记对应的会话）保存为 .debuff/replays/ 中可重现该过程的场景
game_input	按下／释放按键；tap、pointer_down、pointer_move、pointer_up
game_state	场景、tick、逻辑宽度／高度、渲染器、帧统计信息、reducedMotion、你的 inspect() 数据
game_command	使用 JSON 参数运行游戏通过 devTools({ commands }) 注册的命令
game_params / game_set_param	读取和调整类型化参数（经过验证）
game_capture	当前帧的 PNG 图像；path 还会将其保存到项目中（缩略图、商店美术图）
game_errors	运行时错误及说明：问题归属（你的代码、被拒绝的调用、debuff bug）、源代码行和提示
game_stop	关闭游戏

提示词

客户端可提供为斜杠命令的工作流：playtest、fix-errors、tune-feel、add-mechanic 和 explain-stutter。

实时模式与无头模式

如果你已在 debuff dev 中打开游戏，game_start 会连接到该标签页（模式为 live）。叠加层会显示 agent 标记，而 Agent 执行的每次暂停、步进和参数更改都会显示在活动日志中，你可以撤销这些操作。在叠加层中输入备注（“这里的跳跃感觉有点飘”）来标记某个时刻；Agent 会通过 game_notes 读取备注以及该时刻的游戏状态。game_stop 会恢复游戏并断开连接。

否则，或者使用 mode: "headless" 时，Agent 会在无头浏览器中获得一个私有副本。时间只会通过 game_step 推进，因此它看到的内容可重现，场景也可以精确回放。