Geartowns MCP Server

Geartowns

Geartowns 是一款精度极高的跨平台 Fujitsu FM Towns 模拟器，使用 C++ 编写，可在 Windows、macOS、Linux、BSD 和 RetroArch 上运行，并内置 MCP 服务，支持 AI 调试与开发。

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

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

## 下载

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

功能

• 精度极高的 80386 核心，可通过 test386 和 SingleStepTests/80386 测试。
• 支持 FM Towns（Model 1/2）、1F/2F、10F/20F、FM Towns II CX、UX、UG、HG 和 HR，以及 FM Towns Marty 模拟。
• CD-ROM 驱动器模拟，支持 cue/bin、iso 和 chd 镜像、m3u 光盘播放列表和光盘切换，并可选择使用压缩镜像（zip）。
• 支持在 Windows、macOS 和 Linux 上使用实体 CD-ROM 光盘。
• 软盘模拟，支持两个驱动器，可使用 d77、d88、hdm、xdf、img 和 HxC mfm 镜像、m3u 播放列表、写保护，以及可选的磁盘更改持久化。
• 支持 ID 0-6 的 SCSI 硬盘，可使用原始镜像和 chd 镜像、创建空白磁盘并安装 Towns OS。
• 存档状态，支持 5 个存档槽和倒带。
• 支持提前运行，以降低输入延迟。
• 视频录制为 AVI 格式，并支持截图。
• 为 YM3438 和 RF5C68 声音芯片提供 VGM 录制器。
• 支持的平台（独立版）：Windows、Linux、BSD 和 macOS。
• 支持的平台（libretro）：Windows、Linux、macOS、Raspberry Pi、Android、iOS、tvOS、webOS、PlayStation 3、Nintendo GameCube、Nintendo WiiU、Nintendo Switch、Emscripten、Classic Mini systems（NES、SNES、C64 等）、OpenDingux、RetroFW 和 QNX。
• 完整的调试器：
  • 即时反汇编器、代码导航、调用栈、调试符号和自动标签。
  • 执行、数据、I/O 和中断断点。
  • 内存编辑器、跟踪日志记录器和性能分析器。
  • i386 寄存器、描述符表和分页检查器。
  • 查看器：CRTC、调色板、帧缓冲区、精灵、YM3438、RF5C68、CD-ROM、软盘控制器和磁盘、SCSI 控制器和磁盘、中断、计时器、DMA、RTC、键盘和游戏端口。
• MCP 服务，可通过 Claude Code、Codex 等进行 AI 辅助调试，提供执行控制、内存检查、硬件状态、倒带等工具。
• Windows、Linux 和 macOS 便携模式。
• 可编程着色器链。
• 通过在命令行参数中添加 CD-ROM、软盘或硬盘镜像路径来加载介质。
• 支持通过拖放加载介质。
• 支持通过 gamecontrollerdb.txt 文件使用现代游戏控制器；该文件位于与应用程序二进制文件相同的目录中。

使用提示

基本用法

• 固件：Geartowns 需要 FM Towns 系统 ROM 才能运行。使用 Machine → Firmware... 选择存放这些 ROM 的文件夹，每个套装需单独放在一个子文件夹或 MAME zip 文件中。请参阅 BIOS_README.md，了解各型号所需的套装、存放位置及校验和。
• 机器：Machine → Model、CPU Speed 和 Main RAM 默认设为 Auto，会自动选择：
  • 游戏数据库为该游戏指定的型号、CPU 速度和 RAM。
  • 用于 1.44 MB 软盘的 FM Towns II HG。
  • 用于其他内容的 FM Towns（Model 1/2）。
• CD-ROM 镜像：Geartowns 支持 chd、压缩和未压缩的 cue/bin 与 iso 镜像，以及多光盘游戏的 m3u 播放列表。CUE 音轨可使用原始 BIN、兼容的 WAV（44100 Hz、16 位、立体声）或 Ogg Vorbis 文件。通过 Geartowns → CD-ROM 切换光盘。
• 软盘镜像：通过 Geartowns → Floppies 插入软盘，或从命令行加载。支持的镜像格式有 d77、d88、hdm、xdf、img 和 mfm，也支持存放在 zip 文件中的镜像以及 m3u 播放列表。
• 便携模式：使用 --portable 运行，或在与应用程序二进制文件相同的目录中创建名为 portable.ini 的空文件。在 macOS 上，将该文件放在 .app 程序包旁边。

硬盘

最多可连接七个 SCSI 硬盘，ID 为 0-6：

• 1F/2F 及后续型号：内置 SCSI 接口。
• FM Towns（Model 1/2）：连接磁盘时需安装 SCSI 卡。
• FM Towns Marty：不支持 SCSI。

磁盘映像格式

• 原始映像（hdd、h0-h6，以及大于 8 MB 的 hdm）：每个扇区 512 字节。较小的 hdm 映像是软盘。
• MAME 硬盘 chd：只读。首次写入时，Geartowns 会在 Save Files 文件夹中创建原始工作副本，并从那时起使用该副本。

挂载磁盘

• 桌面端：使用 Geartowns → Hard Disks、拖放或命令行。使用拖放和命令行时，扩展程序会选择 ID：
  • h0-h6：对应的 SCSI ID。
  • 大于 8 MB 的 hdd 和 hdm：第一个空闲 ID。
• Libretro：将映像作为内容加载，可单独加载，也可与 CD 一起放入 m3u 播放列表中。更改会写入保存目录中的工作副本，原文件绝不会被写入。
• 正在运行的机器：挂载或卸载磁盘会在下次重置时生效。

磁盘写入与存档状态

• 机器停止写入几秒后，写入内容会保存。
• 存档状态、倒带和预运行不包含磁盘数据。加载存档状态会撤销此后进行的磁盘写入（每个磁盘最多撤销最近的 32 MB 写入），无法撤销时会发出警告。

安装游戏

勾选 Formatted 后，New Blank Disk... 会创建一个分区并格式化的磁盘，其格式与 Towns OS 创建的磁盘相同；每 127 MB 包含一个空驱动器（最多十个）。从 CD 启动的游戏可以安装到该磁盘。该磁盘不包含系统，也无法启动。

安装 Towns OS

1. 创建磁盘，使用 New Blank Disk...，并取消勾选 Formatted。
2. 启动 Towns OS V2.1 CD，然后从 TownsMENU V2.1 的 Tools 文件夹运行 HD Install。
3. 弹出 CD 并重置。

从硬盘启动 Towns OS V2.1 需要 4 MB RAM。连接磁盘时，Main RAM 设为 Auto 至少会提供所需内存。

从硬盘启动

• 可启动 CD 会优先于磁盘启动。
• 插入 CD 时若要从磁盘启动，请在 Geartowns → Reset and Boot From 中选择磁盘。此操作会在重置期间按住系统 ROM 的启动按键（H 和 SCSI ID）。
• Model 1/2 和 Marty ROM 不会读取这些按键。

驱动器号

Towns OS 将硬盘驱动器号保存在机型的 CMOS 中，而非磁盘上，并且只使用已分配驱动器号的分区。

• Assign Drive Letters 开启时（Geartowns → Hard Disks，默认设置）：每次重置时，都会将 D: 起的空闲驱动器号分配给已连接磁盘中尚未分配驱动器号的分区。已设置的驱动器号会保留。这使得在其他机型或模拟器中安装的磁盘也能启动。
• Assign Drive Letters 关闭时：在 Towns OS 中手动分配驱动器号：
  1. 启动 Towns OS V2.1 CD。
  2. 打开 Settings → Drive Configuration。
  3. 点击磁盘的 SCSI ID，然后点击 Add Drive 和 Execute。
  4. 弹出 CD 并重置。

调试功能

• 停靠窗口：在调试模式下，按住 SHIFT 并将一个窗口拖到另一个窗口上，即可将它们停靠在一起。
• 多视口：在 Windows 或 macOS 上，可在调试菜单中启用“multi-viewport”。必须重启模拟器，更改才会生效。启用后，可将调试器窗口拖到主窗口之外。
• 单实例：可在 Emulator 菜单中启用“Single Instance”。启用后，如果另一个实例正在运行，打开文件时会将文件发送给该实例，而不是启动新实例。
• 调试符号：加载 CD-ROM 或软盘映像时，模拟器会自动尝试加载符号文件。例如，对于 path_to_image.cue，它会尝试加载 path_to_image.sym。也可以通过 GUI 或 CLI 加载符号文件。
  • 每行定义一个符号，格式为 address name、name = address、name EQU address 或 address type name。最后一种格式是 GNU nm 输出，例如 nm -n program.elf > program.sym。
  • 地址可以是线性地址，也可以是 selector:offset。
  • 注释以 ; 或 # 开头。
  • 也可以加载 GNU ld 和 NASM 映射文件。

命令行用法

geartowns [options] [media_file] [symbol_file]

Arguments:
  media_file                CD-ROM (.cue .chd .iso), floppy (.d77 .d88 .hdm
                            .xdf .img .mfm), .m3u playlist, .zip, or hard disk
                            (.hdd .h0-.h6, hard disk .chd, .hdm over 8 MB)
  symbol_file               Symbol file for debugging

Media:
      --cd FILE             CD-ROM image or .m3u playlist
      --fd1 FILE            Floppy image in drive 1
      --fd2 FILE            Floppy image in drive 2
      --load-state SLOT     Load save state slot 1-5, or a state file, once the
                            media is loaded

Machine (for this run only, the saved settings stay):
      --model MODEL         auto, model1_2, 1f_2f, 10f_20f, cx, ux, ug, hg, hr,
                            marty
      --cpu-mhz MHZ         auto, 16, 20, 25, 33, 40, 50, 66, 100
      --ram MB              auto, 1, 2, 4, 6, 8, 10, 12, 16, 20, 24, 26, 28
      --fpu FPU             auto, none, 80387 (a 487SX on the HR)

Options:
  -f, --fullscreen          Start in fullscreen mode
  -w, --windowed            Start in windowed mode with menu visible
      --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)
      --portable            Store configuration and user data beside the
                            application
  -v, --version             Display version information
  -h, --help                Display this help message

MCP 服务

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

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

Agent 技能

Geartowns 提供 Agent 技能，指导 AI 助手如何有效地使用模拟器完成特定任务：

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

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

硬件准确性

Geartowns 正在根据 FM Towns 硬件测试的结果进行开发。

构建说明

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/。
• 打开 Geartowns Visual Studio 解决方案 platforms/windows/Geartowns.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 和 Geartowns：

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

贡献者

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

许可证

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