Geargrafx MCP Server

Geargrafx

Geargrafx 是一款精度极高的跨平台 TurboGrafx-16 / PC Engine / SuperGrafx / CD-ROM² / LD-ROM² 模拟器，使用 C++ 编写，可在 Windows、macOS、Linux、BSD 和 RetroArch 上运行，并内置用于 AI 调试和开发的 MCP 服务。

这是一个开源项目，其持续开发得以实现，离不开这些出色的支持者。如果你觉得它有用，请考虑赞助。

如有错误报告或新功能建议，欢迎提交 issue。

## 下载

平台	架构	下载链接
Windows	桌面版 x64	Geargrafx-1.8.5-desktop-windows-x64.zip
	桌面版 ARM64	Geargrafx-1.8.5-desktop-windows-arm64.zip
macOS	Homebrew	brew install --cask drhelius/geardome/geargrafx
	桌面版 Apple Silicon	Geargrafx-1.8.5-desktop-macos-arm64.zip
	桌面版 Intel	Geargrafx-1.8.5-desktop-macos-intel.zip
Linux	Ubuntu PPA	drhelius/ppa-geardome
	Fedora RPM	drhelius/rpm-geardome
	桌面版 Ubuntu 26.04 x64	Geargrafx-1.8.5-desktop-ubuntu26.04-x64.zip
	桌面版 Ubuntu 26.04 ARM64	Geargrafx-1.8.5-desktop-ubuntu26.04-arm64.zip
	桌面版 Ubuntu 24.04 x64	Geargrafx-1.8.5-desktop-ubuntu24.04-x64.zip
	桌面版 Ubuntu 24.04 ARM64	Geargrafx-1.8.5-desktop-ubuntu24.04-arm64.zip
MCPB	所有平台	MCP 说明文档
RetroArch	所有平台	Libretro 核心文档
开发版本	所有平台	GitHub Actions

注意：

• Windows：可能需要 Visual C++ Redistributable 和 OpenGL Compatibility Pack
• Homebrew：如果 Homebrew 要求你信任第三方 tap，请运行 brew trust --tap drhelius/geardome
• Linux：可能需要 libsdl3

功能

• 精准模拟，支持完整的 HuCard PCE / SGX 游戏目录。
• 支持 CD-ROM²、Super CD-ROM² 和 Arcade CD-ROM² 系统。
• 通过 MMI 映像支持 NEC LaserActive LD-ROM²。
• 支持带预览的即时存档和倒带。
• 支持预运行，以降低输入延迟。
• 支持 Backup RAM 和 Memory Base 128。
• 支持 AAAAAA:VV 格式的金手指代码，并支持导入 RetroArch .cht 文件。
• 支持在同一台机器上的两个模拟器实例之间进行 TurboLink 多人游戏。
• Multi Tap（最多 5 名玩家）。
• 标准手柄（2 个按键）、Avenue Pad 3（3 个按键，根据游戏自动配置）、Avenue Pad 6（6 个按键）和鼠标。
• 可调扫描线数量（224p、240p 或手动设置）。
• 支持 RGB 或 Composite 色彩输出，并可选 LPF 滤镜。
• 支持压缩 ROM 和 CD 映像（pce、sgx、cue、zip、chd 和 mmi）。
• 支持播放实体 CD-ROM 光盘。
• 支持音乐 ROM：HES。
• VGM 录制器。
• 内置数据库，选择 Auto 选项时可自动识别 ROM 并选择硬件。
• 支持的平台（独立版）：Windows、Linux、BSD 和 macOS。
• 支持的平台（libretro）：Windows、Linux、macOS、Raspberry Pi、Android、iOS、tvOS、webOS、PlayStation Vita、PlayStation 3、Nintendo 3DS、Nintendo GameCube、Nintendo Wii、Nintendo WiiU、Nintendo Switch、Emscripten、Classic Mini 系统（NES、SNES、C64 等）、OpenDingux、RetroFW 和 QNX。
• 完整的调试器，包含即时反汇编器、CPU 断点、内存访问断点、代码导航（跳转到地址、双击 JP JR 和 JSR）、调试符号、自动标签、内存编辑器、PSG 检视器，以及视频查看器；后者包含寄存器、图块、精灵、背景、CD-ROM 子系统，以及 SuperGrafx 模式下的两个 VDC。
• MCP 服务，可通过 Claude Code、Codex 等进行 AI 辅助调试，提供执行控制、内存检查、硬件状态、倒带等工具。
• Windows、Linux 和 macOS 便携模式。
• 可编程着色器链。
• 通过将 ROM 路径作为参数添加到命令行来加载 ROM。
• 支持通过拖放加载 ROM。
• 支持现代游戏控制器，需使用与应用程序二进制文件位于同一目录中的 gamecontrollerdb.txt 文件。

提示

基本用法

• BIOS：Geargrafx 需要 BIOS 才能运行 CD-ROM 游戏。可加载任意 BIOS，但推荐使用 md5 为 38179df8f4ac870017db21ebcbf53114 的 System Card 3.0。
• CD-ROM 映像：Geargrafx 支持 chd、压缩和未压缩的 cue/bin、cue/img 及 cue/iso 映像。CUE 音轨可使用原始 BIN、兼容的 WAV（44100 Hz、16 位、立体声）或 Ogg Vorbis（44100 Hz、立体声）文件。不支持 MP3 音轨。
• LaserActive 映像：Geargrafx 支持 NEC LD-ROM² .mmi 映像。需要日版 PAC-N1/PCE-LP1 或美版 PAC-N10 BIOS。可通过 Geargrafx → MMI Media 或 libretro 光盘控制功能切换光盘面。LaserActive 下，桌面版的倒带和预运行功能不可用。
• 鼠标光标：将鼠标悬停在主输出窗口上或禁用主菜单时，光标会自动隐藏。
• 便携模式：使用 --portable 运行，或在应用程序二进制文件所在目录中创建一个名为 portable.ini 的空文件。在 macOS 上，将文件放在 .app 捆绑包旁边。
• 金手指：打开 Emulator → Cheats... 输入代码或导入 RetroArch .cht 文件。代码采用 AAAAAA:VV 格式，使用物理地址；例如，1F0DB1:09 会将 $09 写入工作 RAM $0DB1。使用 + 连接多条代码。

调试功能

• 停靠窗口：在调试模式下，按住 SHIFT 并将一个窗口拖到另一个窗口上，即可将窗口停靠在一起。
• 多视口：在 Windows 或 macOS 上，可以在调试菜单中启用“多视口”。必须重启模拟器，更改才会生效。启用后，可以将调试器窗口拖到主窗口之外。
• 单实例：可以在 Emulator 菜单中启用“单实例”。启用后，如果已有一个实例在运行时打开 ROM，该 ROM 会发送到正在运行的实例，而不会启动新实例。
• 调试符号：加载 ROM 时，模拟器会自动尝试加载符号文件（.sym、.lbl、.noi）。例如，对于 path_to_rom_file.rom，它会尝试加载 path_to_rom_file.sym。也可以通过 GUI 或 CLI 加载符号文件。支持 PCEAS（新旧格式）、wla-dx 和 vasm 文件格式。

命令行用法

geargrafx [options] [game_file] [symbol_file]

Arguments:
  [game_file]                 Accepts ROMs (.pce, .sgx, .hes), CUE (.cue), CHD (.chd), MMI (.mmi) or ZIP (.zip)
  [symbol_file]               Optional symbol file for debugging

Options:
    -f, --fullscreen          Start in fullscreen mode
    -w, --windowed            Start in windowed mode with menu visible
      --load-state SLOT       Load save state slot 1-5, or a state file, once the media is loaded
      --mcp-stdio             Auto-start MCP server with stdio transport
      --mcp-http              Auto-start MCP server with HTTP transport
      --mcp-router            Enable compact MCP tool routing
      --mcp-http-address A    HTTP bind address (default: 127.0.0.1)
      --mcp-http-port N       HTTP port for MCP server (default: 7777)
      --turbolink-join N      Join local TurboLink shared session 1-255
      --headless              Run without GUI (requires MCP or TurboLink)
      --portable              Store configuration and user data beside the application
    -v, --version             Display version information
    -h, --help                Display this help message

MCP 服务

Geargrafx 包含一个 Model Context Protocol（MCP）服务，可通过 Claude Code、Codex 等 AI Agent 实现 AI 辅助调试。该服务提供执行控制、内存检查、断点、反汇编、硬件状态、回退等工具。支持 STDIO 和 HTTP 传输，推荐使用 STDIO。

完整的设置说明和工具文档，请参阅 MCP_README.md。

TurboLink 多人游戏

在两个实例的 TurboLink 菜单中选择相同的会话编号并选择 Connect，或者使用 --turbolink-join N 启动每个进程。会话使用本地共享内存，并且仅支持同一台计算机上的两个对等端。独立实例应使用单独的应用副本或 --portable 数据目录，以避免配置、存档和单实例处理相互冲突。

Agent Skills

Geargrafx 提供 Agent Skills，指导 AI 助手如何有效地将模拟器用于特定任务：

• geargrafx-debugging — 游戏调试、代码追踪、断点管理、硬件检查和逆向工程。
• geargrafx-romhacking — 金手指创建、内存搜索、ROM 数据修改、文本翻译和游戏补丁。

使用 npx skills add drhelius/geargrafx 安装。详情请参阅 skills README。

构建说明

Windows

• 安装 Microsoft Visual Studio Community 2026 或更高版本。
• 从 SDL3 Releases 下载最新的 SDL3 VC 开发库（文件名为 SDL3-devel-x.y.z-VC.zip）。
• 解压缩归档，并将生成的文件夹（例如 SDL3-x.y.z）重命名为 SDL3。
• 将 SDL3 文件夹放入 platforms/windows/dependencies/，使包含路径为 platforms/windows/dependencies/SDL3/include/SDL3/。
• 打开 Geargrafx Visual Studio 解决方案 platforms/windows/Geargrafx.sln 并进行构建。

macOS

• 安装 Xcode，并在终端中运行 xcode-select --install，以便在命令行中使用编译器。
• 运行以下命令以生成 Mac app 捆绑包：

brew install sdl3
cd platforms/macos
make dist

Linux

• Ubuntu / Debian / Raspberry Pi（Raspbian）：

如果使用 Ubuntu 26.04，可以直接安装 SDL3。使用以下命令进行构建：

sudo apt install build-essential pkg-config libsdl3-dev libgl-dev
cd platforms/linux
make

对于 Ubuntu 24.04，需要先从源代码构建 SDL3。使用以下命令构建 SDL3 和 Geargrafx：

sudo apt install build-essential cmake git curl jq pkg-config \
  libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxfixes-dev \
  libxi-dev libxss-dev libxkbcommon-dev libwayland-dev libdecor-0-dev \
  libdrm-dev libgbm-dev libgl1-mesa-dev libegl1-mesa-dev libdbus-1-dev libudev-dev libxtst-dev
SDL3_TAG=$(curl -s https://api.github.com/repos/libsdl-org/SDL/releases/latest | jq -r '.tag_name')
git clone --depth 1 --branch "$SDL3_TAG" https://github.com/libsdl-org/SDL.git /tmp/SDL3
cmake -S /tmp/SDL3 -B /tmp/SDL3/build -DCMAKE_INSTALL_PREFIX=/usr -DSDL_TESTS=OFF -DSDL_EXAMPLES=OFF
cmake --build /tmp/SDL3/build -j$(nproc)
sudo cmake --install /tmp/SDL3/build
cd platforms/linux
make

• Fedora：

sudo dnf install @development-tools gcc-c++ SDL3-devel
cd platforms/linux
make

• Arch Linux：

sudo pacman -S base-devel sdl3
cd platforms/linux
make

BSD

• FreeBSD：

su root -c "pkg install -y git gmake pkgconf sdl3"
cd platforms/bsd
USE_CLANG=1 gmake

• NetBSD：

su root -c "pkgin install gmake pkgconf SDL3"
cd platforms/bsd
gmake

• OpenBSD

doas pkg_add gmake sdl3
cd platforms/bsd
LDFLAGS=-L/usr/X11R6/lib/ USE_CLANG=1 gmake

Libretro

• Ubuntu / Debian / Raspberry Pi（Raspbian）：

sudo apt install build-essential
cd platforms/libretro
make

• Fedora：

sudo dnf install @development-tools gcc-c++
cd platforms/libretro
make

贡献者

感谢所有为 Geargrafx 做出贡献的人！

许可证

Geargrafx 基于 GNU 通用公共许可证 v3.0 许可，详情请参阅 LICENSE。