/ 目錄 / 演練場 / Gearsystem
● 社群 drhelius ⚡ 即開即用

Gearsystem

作者 drhelius · drhelius/Gearsystem

與 AI 配對除錯 Sega Master System / Game Gear ROM — 設定中斷點、檢查 VRAM,並以對話方式逐步分析反組譯程式碼。

Gearsystem 是 drhelius 長期維護、備受好評的 Sega Master System / Game Gear / SG-1000 模擬器。近期版本內嵌了 MCP 伺服器,可將除錯器(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 建置版本 — Clone drhelius/Gearsystem 並依照 MCP_README.md 進行建置
  • ROM 檔案及其 .sym 符號檔 — 由你的組譯器(WLA-DX、asm6 等)輸出
步驟
  1. 以無頭模式啟動並在當機點設定中斷點
    使用我的 ROM 啟動 Gearsystem MCP。在標籤 init_vdp 處設定 CPU 中斷點並執行。✓ 已複製
    → 執行在中斷點處暫停
  2. 檢查 CPU 與 VRAM 狀態
    顯示 Z80 暫存器以及 VRAM 的前 32 個位元組。在初始化的這個階段,有什麼看起來不對勁嗎?✓ 已複製
    → 暫存器傾印加上預期值與實際值的比較觀察
  3. 單步執行並監看特定記憶體區域
    在 $C000 加入記憶體存取中斷點,然後單步執行直到有東西寫入該位址。✓ 已複製
    → 在問題指令處停止

結果: 找出根本原因(例如在 VRAM 安全前就寫入 VDP 暫存器),並取得確切的指令位址。

注意事項
  • 符號未載入 — 位址不透明 — 確認 .sym 檔案與確切的 ROM 建置版本相符;如有需要,重新建置以對齊符號
  • 時序錯誤只在真實硬體上重現,模擬器無法重現 — 模擬器有其限制;對於匯流排時序邊界情況,請在真實 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
    將該腳本包裝成一個在每次推送到 main 時執行的 GitHub Actions 工作流程。✓ 已複製
    → 可運作的 CI 步驟

結果: 建立一個能在你手動載入 ROM 前就攔截迴歸問題的冒煙測試。

搭配使用: github

組合

與其他 MCP 搭配,撬動十倍槓桿

gearsystem + github

在單一流程中完成除錯並提交修復

重現我的 ROM 中的 issue #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 伺服器繫結至 stdio 或指定的 HTTP 連接埠

故障排查

常見錯誤與修復

MCP flags not recognized

你的建置版本在編譯時未啟用 MCP 支援。請依照 MCP_README.md 啟用對應旗標後重新建置。

驗證: gearsystem --help | grep mcp
Breakpoint never hits

可能是符號解析有誤;請改用原始位址而非標籤。確認 ROM 確實已載入。

驗證: Use get_registers to confirm PC is moving
HTTP transport refused connection

確認連接埠未被佔用,且模擬器是以 --mcp-http --mcp-http-port 7777 啟動的。

驗證: curl http://127.0.0.1:7777/

替代方案

Gearsystem 對比其他方案

替代方案何時用它替代權衡
Emulicious你需要一個完整 GUI 除錯器來處理 Game Boy/SMS 等平台不支援 MCP;僅限人工操作
BizHawk需要多系統 TAS/除錯功能以 Lua 腳本驅動,而非 MCP

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills