Gearcoleco MCP Server

Gearcoleco

Gearcoleco 是一款使用 C++ 编写的 ColecoVision 和 Coleco ADAM 模拟器，精确度极高且支持跨平台，可在 Windows、macOS、Linux、BSD 和 RetroArch 上运行，并内置 MCP 服务，用于 AI 调试和开发。

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

欢迎通过提交问题来报告错误或提出新功能需求。

## 下载

平台	架构	下载链接
Windows	桌面版 x64	Gearcoleco-1.7.4-desktop-windows-x64.zip
	桌面版 ARM64	Gearcoleco-1.7.4-desktop-windows-arm64.zip
macOS	Homebrew	brew install --cask drhelius/geardome/gearcoleco
	桌面版 Apple Silicon	Gearcoleco-1.7.4-desktop-macos-arm64.zip
	桌面版 Intel	Gearcoleco-1.7.4-desktop-macos-intel.zip
Linux	Ubuntu PPA	drhelius/ppa-geardome
	Fedora RPM	drhelius/rpm-geardome
	桌面版 Ubuntu 26.04 x64	Gearcoleco-1.7.4-desktop-ubuntu26.04-x64.zip
	桌面版 Ubuntu 26.04 ARM64	Gearcoleco-1.7.4-desktop-ubuntu26.04-arm64.zip
	桌面版 Ubuntu 24.04 x64	Gearcoleco-1.7.4-desktop-ubuntu24.04-x64.zip
	桌面版 Ubuntu 24.04 ARM64	Gearcoleco-1.7.4-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

功能

• 非常精准地模拟 Z80 核心、TMS9918A VDP、SN76489 PSG 和 AY-3-8910 SGM。
• 支持 ColecoVision Super Game Module（SGM）和 MegaCart ROM。
• 支持 Coleco ADAM 计算机和卡带启动模式、完整键盘、ADAMnet、打印机、Digital Data Pack 和软盘。
• 可选的 F18A v1.9 模拟。
• 支持 Super Action Controller（SAC）、Wheel Controller 和 Roller Controller。
• 支持带预览的即时存档和倒带。
• 支持预运行，以降低输入延迟。
• 支持压缩 ROM（ZIP）。
• VGM 录制器。
• 支持的平台（独立版）：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 和 CALL）、调试符号、自动标签、内存编辑器、跟踪日志记录器、IO 检查器和 VRAM 查看器（含寄存器、图块、精灵和背景）。
• MCP 服务支持使用 Claude Code、Codex 等进行 AI 辅助调试，并提供执行控制、内存检查、硬件状态、倒带等工具。
• Windows、Linux 和 macOS 便携模式。
• 可编程着色器链。
• 从命令行加载内容：将卡带、ADAM 媒体或播放列表路径作为参数添加。
• 支持通过拖放加载内容。
• 支持通过与应用程序二进制文件位于同一目录中的 gamecontrollerdb.txt 文件使用现代游戏控制器。

提示

基本用法

• BIOS 和 ADAM 固件：不附带固件。在 Emulator > BIOS 下选择 ColecoVision BIOS（OS-7）；建议使用原版 BIOS（CRC32 3aa93ef3；文件名为 colecovision.rom、coleco.rom 或 os7.u2）。ADAM 还需要 ADAM > EOS ROM（eos.rom，8192 字节，常见 CRC32 为 05a37a34）和 ADAM > SmartWriter ROM（writer.rom、wp.rom 或 wp_r80.rom，32768 字节，常见 CRC32 为 58d86a2a）。
• ADAM 启动和媒体：通过 ADAM 菜单中的磁盘或数据包子菜单插入映像，然后选择 Power On。支持的格式包括 256 KiB .ddp、160/320 KiB .dsk、包含一个有效 ADAM 映像的 ZIP 压缩包，以及包含同类型映像的 .m3u 播放列表。每个驱动器都有各自的最近使用映像、播放列表和写保护控制。插入/弹出操作只影响对应驱动器；拖入映像时会使用可用的匹配驱动器，或提示选择目标驱动器。Gearcoleco > Open ROM... 可启动 ColecoVision 卡带。
• ADAM 电源和存档：Power Off 会保存已修改的媒体并使其保持插入状态。固件更改将在下次 Power On 时生效；Computer Reset 会保留当前固件和已挂载媒体。更改会作为完整映像存储在 Save Files 下，源文件保持不变。驱动器菜单还提供 Save Changes 和 Save As；如果保存失败，修改后的映像仍会保持挂载状态。
• ADAM 输入：直接在 ADAM 中输入；在调试模式下，聚焦 Output 可输入，聚焦调试器工具可使用其快捷键。在 ADAM > Keyboard 下配置特殊按键（参见下方默认设置）；F12 可切换全屏。ADAM > Controller 1 / Controller 2 可为每个端口选择游戏手柄（默认）、键盘或不使用手柄。按键绑定来自 Input > Gamepads 或 Input > Keyboard Configuration；映射到手柄的按键不会输入到 ADAM 中。ADAM 控制器选项与 ColecoVision 设置分开保存。
• 旋钮控制器：使用 Input > Spinners > Capture Mouse 或已配置的 Capture Mouse 快捷键。对于不使用旋钮控制器的软件，请禁用旋钮控制器。
• 倒带：按住已配置的倒带热键（默认为 Backspace）或映射的游戏手柄快捷键，即可向后回溯最近的游戏过程。
• 过扫描：要精确呈现原始画面，请在 Video 菜单中将 Overscan 设为 Top+Bottom，并将 Aspect Ratio 设为 Standard (4:3 DAR)。
• 鼠标光标：将鼠标悬停在主输出窗口上或禁用 Main Menu 时，光标会自动隐藏。
• 便携模式：使用 --portable 运行，或在应用程序二进制文件所在目录中创建一个名为 portable.ini 的空文件。在 macOS 上，将该文件放在 .app 程序包旁边。

桌面 ADAM 键盘

普通字母、数字、标点、Return、Escape、Backspace、Tab、Shift、Control、Caps Lock 和方向键均直接映射。专用 ADAM 按键的默认映射如下：

主机按键	ADAM 按键
F1-F6	SmartKey I-VI
F7 / F8	Undo / Wild Card
Home / Insert / Delete	ADAM Home / Insert / Delete
Page Up / Page Down	Move-Copy / Store-Fetch
End	Clear
Print Screen	Print

已保存的键盘映射会予以保留。要在现有配置中应用此布局，请使用 ADAM > Keyboard > Restore Defaults。

当 ADAM 获得键盘焦点时，可从菜单使用与模拟器快捷键冲突的按键，以便将 SmartKeys 和编辑按键传递给模拟键盘。离开窗口后，所有按住的 ADAM 按键都会释放。

ADAM 键盘输入会自动跟随焦点。正常使用时，直接输入即可；在调试模式下，聚焦 Output 可向 ADAM 输入，聚焦调试器工具则可使用其快捷键。F12 仍是默认的全屏快捷键。

Libretro 中的 ADAM

• 启动：使用上文中的固件名称，将 OS-7、EOS 和 SmartWriter 放入前端系统目录或其 gearcoleco 子目录。加载 .ddp、.dsk、ADAM .zip、.m3u 或未加载内容时，ADAM 会自动启动；如果没有可启动介质，则会打开 SmartWriter。除非将 Cartridge Hardware 设置为 ADAM，否则卡带会使用 ColecoVision。
• 介质和存档：介质默认处于写保护状态。启用 Save-directory working copy 后，可在前端存档目录中保存完整的修改后镜像，同时保留源文件不变。ADAM Disk Control Drive 用于选择 Disk 1/2 或 Data Pack 1/2；Loaded media（默认）则以主要内容驱动器为目标。每个驱动器都有自己的镜像列表。通过前端的弹出、选择和关闭流程切换介质；其他驱动器会保持挂载状态。
• 多个镜像：可选的 ADAM 子系统（adam）可在启动前加载最多五个插槽，顺序为：Cartridge、Disk 1、Disk 2、Data Pack 1、Data Pack 2。所有插槽均为可选项，且每个驱动器都支持播放列表。请将旧版三插槽配置更新为此布局；加载单个镜像或播放列表时，请使用常规内容加载方式。
• 键盘：按键绑定固定为桌面默认设置，包括用于 Escape/WP 的 Escape 键，以及作为修饰键的 Shift/Control。在 RetroArch 中，将 Settings > Input > Auto Enable 'Game Focus' Mode 设为 Detect，或在输入文字前按 Scroll Lock 切换 Game Focus。关闭该模式即可使用 RetroArch 快捷键。如果不使用 Scroll Lock，请将 Game Focus Toggle 绑定到 F10；F9-F12 和 Scroll Lock 在 ADAM 中未映射。
• 重置：前端的 Reset 会保留当前启动模式。ADAM Computer Reset 会从已挂载介质启动，不会将其弹出；如果该选项未自动返回 Idle，请先选择 Idle，再请求另一次重置。

调试功能

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

命令行用法

gearcoleco [options] [content_file] [symbol_file]

Arguments:
  [content_file]              Cartridge or ADAM media (.col, .cv, .rom, .bin, .ddp, .dsk, .zip, .m3u)
  [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)
      --headless              Run without GUI (requires --mcp-stdio or --mcp-http)
      --portable              Store configuration and user data beside the application
  -v, --version               Display version information
  -h, --help                  Display this help message

MCP 服务

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

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

Agent 技能

Gearcoleco 提供 Agent Skills，指导 AI 助手如何针对特定任务有效使用模拟器：

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

使用 npx skills add drhelius/gearcoleco 安装。详情请参阅 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/。
• 打开 Gearcoleco Visual Studio 解决方案 platforms/windows/Gearcoleco.sln 并进行构建。

macOS

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

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 和 Gearcoleco：

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

屏幕截图

贡献者

感谢所有已经为 Gearcoleco 做出贡献的人！

许可证

Gearcoleco 根据 GNU General Public License v3.0 License 授权，详情请参阅 LICENSE。