/ 目录 / 演练场 / Gearsystem
● 社区 drhelius ⚡ 即开即用

Gearsystem

作者 drhelius · drhelius/Gearsystem

与 AI 搭档一起调试 Sega Master System / Game Gear ROM——设置断点、检查 VRAM、以对话方式浏览反汇编代码。

Gearsystem 是 drhelius 长期维护且广受好评的 Sega Master System / Game Gear / SG-1000 模拟器。最新版本内置了 MCP server,将调试器(CPU 断点、内存检查、反汇编、VRAM/调色板查看)功能暴露给 AI 代理。适用于复古自制软件开发,以及对你拥有的 ROM 代码的逆向工程。

为什么要用

核心特性

实时演示

实际使用效果

gearsystem.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "gearsystem",
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "gearsystem": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/drhelius/Gearsystem"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add gearsystem -- TODO 'See README: https://github.com/drhelius/Gearsystem'

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Gearsystem

调试在标题屏幕崩溃的自制 Master System ROM

👤 复古自制软件开发者 ⏱ ~30 min advanced

何时使用: 你的 WLA-DX 构建在纸面上运行良好,但 Gearsystem 在标题屏幕冻结了。

前置条件
  • 启用 MCP 构建的 Gearsystem — 克隆 drhelius/Gearsystem 并按 MCP_README.md 构建
  • ROM 及其 .sym 符号文件 — 汇编器的输出(WLA-DX、asm6 等)
步骤
  1. 以无头模式启动并在崩溃点设置断点
    用我的 ROM 启动 Gearsystem MCP。在标签 init_vdp 处设置 CPU 断点并运行。✓ 已复制
    → 执行在断点处停止
  2. 检查 CPU 和 VRAM 状态
    给我看 Z80 寄存器和 VRAM 的前 32 个字节。在 init 的这个点有什么不对劲吗?✓ 已复制
    → 寄存器转储 + 关于预期值与实际值的观察
  3. 单步执行并监视特定的内存区域
    在 $C000 处添加内存访问断点,单步直到有东西写入那里。✓ 已复制
    → 在有问题的指令处停止

结果: 问题根源(例如在 VRAM 安全前写入了 VDP 寄存器)及其确切的指令地址。

注意事项
  • 符号未加载——地址无法识别 — 确保 .sym 文件与你的 ROM 版本一致;如有不符,请重新构建以保持同步
  • 时序 bug 只在真实硬件上重现,模拟器上不会 — 模拟器有其局限;对于总线时序的边界情况,请在真实 SMS 上测试
搭配使用: filesystem

逆向工程你拥有的 ROM 来记录其内存映射

👤 正在记录自己或公开域 ROM 的保护者和开发者 ⏱ ~60 min advanced

何时使用: 你在写技术分析文章或反汇编资料,需要一份内存映射。

步骤
  1. 运行 ROM 并在关键时刻检查
    启动 ROM,在 VBlank 处中断,转储 $C000-$DFFF 处的 WRAM。然后运行一帧并再次转储。✓ 已复制
    → 两个 WRAM 快照用于对比
  2. 通过对比识别可能的变量
    比较两个快照。哪些地址改变了?它们可能是什么(计数器、指针、精灵位置)?✓ 已复制
    → 假设的变量映射及其理由

结果: 一个初步的内存映射,你可以手动细化。

注意事项
  • 对你不拥有的商业版权 ROM 进行逆向工程处于法律灰色地带 — 仅在你拥有或公开域的 ROM 上使用此方法。不要在未考虑你管辖区公平使用规则的情况下发布商业 ROM 的 RAM 映射

自动化你的 ROM 的烟雾测试,在每次提交时运行

👤 拥有 CI 管道的自制软件开发者 ⏱ ~25 min intermediate

何时使用: 你想要'启动到标题屏幕不崩溃'作为 CI 门控。

步骤
  1. 编写 MCP 会话脚本
    编写一个脚本,以无头模式启动 Gearsystem MCP,运行我的 ROM 600 帧,如果 CPU 在无效操作码处停止则返回非零。✓ 已复制
    → 具有清晰退出代码的 shell 脚本
  2. 接入 CI
    将其包装在一个 GitHub Actions 工作流中,在每次推送到 main 时运行。✓ 已复制
    → 工作的 CI 步骤

结果: 一个烟雾测试,在你手动加载 ROM 之前捕获回归。

搭配使用: github

组合

与其他 MCP 搭配,撬动十倍杠杆

gearsystem + github

在一个流程中调试并提交修复

重现我的 ROM 中的问题 #12,找到故障地址,在 src/vdp.asm 中打开一个单行修复的 PR。✓ 已复制
gearsystem + filesystem

在调试器旁读取 .sym 文件以将地址转换为标签

加载 ./build/game.sym 并告诉我地址 $03A7 处的标签。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
run (none) 在中断后恢复执行 free (local)
pause (none) 暂停以检查 free
step n?: int 单步执行指令 free
set_breakpoint address: hex, kind: cpu|read|write 监视 PC 命中或内存访问 free
read_memory address: hex, length: int 检查 WRAM / VRAM / 卡带区域 free
disassemble address: hex, instructions: int 读取 PC 周围的代码 free
get_registers (none) 任何检查时刻 free
dump_vram start?: hex, length?: int 图形调试 free

成本与限制

运行它的成本

API 配额
无——完全本地过程
每次调用 Token 数
内存转储可能很大;缩小范围可保持响应较小
费用
免费,GPL-3.0 许可
提示
除非你确实需要完整页面,否则请要求较小的内存窗口(16-64 字节)。

安全

权限、密钥、影响范围

凭据存储: 无需凭据
数据出站: 在本地运行;MCP server 绑定到 stdio 或选定的 HTTP 端口

故障排查

常见错误与修复

MCP 标志无法识别

你的构建在没有 MCP 支持的情况下编译。按 MCP_README.md 启用标志重新构建。

验证: gearsystem --help | grep mcp
断点永不命中

符号解析可能关闭;尝试使用原始地址而不是标签。确认 ROM 实际上已加载。

验证: Use get_registers to confirm PC is moving
HTTP 传输拒绝连接

检查端口是否未被使用,以及模拟器是否以 --mcp-http --mcp-http-port 7777 启动。

验证: curl http://127.0.0.1:7777/

替代方案

Gearsystem 对比其他方案

替代方案何时用它替代权衡
Emulicious如果你想要一个用于 Game Boy/SMS 等的完整 GUI 调试器无 MCP;仅人工驱动
BizHawk需要多系统 TAS/调试支持Lua 脚本而不是 MCP

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills