MCP-openMSX

MCP-openMSX

_"编排一场二进制歌剧：AI 担任指挥，MCP 负责诠释，而 openMSX 则是 8 位女主角。"

一个用于自动化 openMSX 模拟器实例的模型上下文协议（MCP）服务。

此服务通过标准化的 MCP 协议，为 MSX 软件开发、测试和自动化提供全面的工具。

🎁🎁 如果您觉得这个项目有用，请考虑通过 PAYPAL 链接或 GitHub Sponsors捐赠支持

---

目录

• 项目概览
• 架构
• 可用的 MCP 工具
• 可用的 MCP 资源
• ⚡ 快速开始
  • 使用 VSCode 快速安装
  • 使用 Claude Desktop 基本安装
  • 环境变量
• 高级手动用法
• 开发
• 许可证
• 支持
• 贡献
• 🌟 更多星标！ 🌟

项目概览

此项目通过以下功能，在现代 AI 辅助开发（例如 GitHub Copilot、Claude Desktop）与复古计算（MSX 系统）之间搭建桥梁：

• 模拟器控制：启动、配置和管理 openMSX 实例，并重放时间线。
• 媒体管理：处理 ROM 卡带、软盘和盒式磁带。
• BASIC 编程支持：提供便于使用 BASIC 语言编程和开发的工具。
• 调试工具：全面的 CPU 调试功能，包括断点、内存检查和单步执行。
• 视频控制：操作 VDP 寄存器并截取屏幕。
• 内存操作：读写 RAM、VRAM，并访问 I/O 端口。
• 自动化：模拟键盘输入并管理存档状态。
• 混合文档搜索：查询内嵌的 MSX 资源本地索引，结合语义搜索（多语言嵌入）和关键词搜索（BM25），完全离线运行。
• 混合模式：此 MCP 服务支持混合访问模式（STDIO 和 HTTP 传输）。

架构

flowchart TB
  %%{init: {'flowchart': {'curve':'monotoneX' }}}%%

  subgraph yourComputerGroup[" "]
    HOST["Your AI dev companion<br>(MCP Client support)"]
    EMU["openMSX emulator<br>(local instance)"]

    subgraph mcpGroup["**mcp-openmsx**"]
      MCP["MCP Server<br>stdio / http"]
      TOOLS["MCP Tools"]
      VECTORDB[("Embeddings RAG<br>(Vector Database)")]
      RESOURCES["MCP Resources"]
      LOCALDATA["Local data<br>(inner documentation)"]
    end
    EXTDATA["External data<br>(webpages)"]

    HOST <--"_MCP<br>&nbsp;protocol&nbsp;_"--> MCP
    MCP <--> TOOLS & RESOURCES
    TOOLS <--"_&nbsp;Query&nbsp;_"--> VECTORDB
    TOOLS <--"_&nbsp;Console commands&nbsp;_"---> EMU
    RESOURCES <--_&nbsp;http&nbsp;_---> EXTDATA
    RESOURCES <--> LOCALDATA
  end

  HOST@{ shape: rounded }
  MCP@{ shape: rounded }
  EMU@{ shape: rounded }
  LOCALDATA@{ shape: docs }
  EXTDATA@{ shape: docs }
  style yourComputerGroup color:#fff,fill:#4444,text-align:left
  style mcpGroup color:#fff,fill:#4444
  style HOST color:#000000,fill:#BBDEFB,stroke-width:4px,stroke-dasharray:0
  style MCP color:#000000,fill:#FFF9C4
  style EMU color:#FFFFFF,fill:#0000FF,stroke-width:4px,stroke-dasharray:0

MCP 服务会将 Copilot AI 发出的高级自然语言命令转换为 TCL 命令，以控制 openMSX，从而实现 MSX 软件的自动化测试和调试。

可用的 MCP 工具

模拟器控制工具

• emu_control：控制 openMSX 模拟器：launch、close、powerOn、powerOff、reset、getEmulatorSpeed、setEmulatorSpeed、machineList、extensionList、wait。
• emu_replay：控制仿真时间线：start、stop、status、goBack、absoluteGoto、advanceFrame、reverseFrame、truncate、saveReplay、loadReplay。
• emu_info：获取当前仿真机器的信息：getStatus、getSlotsMap、getIOPortsMap。
• emu_media：管理 ROM、磁盘和磁带媒体：tapeInsert、tapeRewind、tapeEject、romInsert、romEject、diskInsert、diskInsertFolder、diskEject。
• emu_vdp：管理 VDP（视频显示处理器）：getPalette、getRegisters、getRegisterValue、setRegisterValue、screenGetMode、screenGetFullText。

编程工具

• basic_programming：BASIC 工具：isBasicAvailable, newProgram, runProgram, setProgram, getFullProgram, getFullProgramAdvanced, listProgramLines, deleteProgramLines。

调试工具

• debug_run：控制执行：break, isBreaked, continue, stepIn, stepOut, stepOver, stepBack, runTo。
• debug_cpu：读取／写入 CPU 寄存器、CPU 信息、堆栈和反汇编代码：getCpuRegisters, getRegister, setRegister, getStackPile, disassemble, getActiveCpu。
• debug_memory：RAM 内存操作：selectedSlots, getBlock, readByte, readWord, writeByte, writeWord, writeBlock, searchBytes。
• debug_vram：VRAM 操作：getBlock, readByte, writeByte, searchBytes。
• debug_breakpoints：断点管理：create, remove, list。
• debug_log：调试日志：log, read。
• debug_conditions：条件管理（类似断点，但不绑定地址——CPU 运行时会持续求值的 Tcl 表达式）：create, remove, list。

自动化工具

• emu_keyboard：向模拟器发送文本或组合键：sendText, sendKeyCombo。
• emu_savestates：保存和恢复机器状态：load, save, list。
• screen_shot：截取模拟器屏幕：as_image, to_file。
• screen_dump：将屏幕数据导出为 BASIC BSAVE 指令。
• msxdocs_resource_get：为不支持 MCP 资源的 MCP 客户端检索 MCP 资源。

文档工具

• vector_db_query：在本地 MSX 文档索引中进行混合搜索（语义嵌入 + BM25），查找有关 MSX 系统、卡带、编程和其他开发资源的信息。
• msxdocs_resource_get：为不支持 MCP 资源的 MCP 客户端检索 MCP 资源。

可选高级工具

• openmsx_tcl_cmd：在已连接的 openMSX 实例中执行原生 Tcl 命令。默认情况下禁用，只有在用户设置 OPENMSX_ENABLE_RAW_TCL=true 时才会注册。现有的类型化工具仍可使用；对于它们支持的操作，优先使用这些工具。

可用的 MCP 资源

什么是 MCP 资源？

MCP 资源是结构化数据集、文档和辅助文件，可扩展 MCP 服务的能力。它们提供机器定义、扩展列表、媒体模板和编程示例等重要信息，使用户能够在 MCP-openMSX 环境中更强大地自动化、测试和开发 MSX 软件。

可用资源

目前有 60 多种资源，其中一些直接包含在 MCP 中，其他资源则可在查询时下载。它们分为以下类别：

• Processors（Z80、R800）
• Bios（Bios ROM、DOS ROM、SUBROM，……）
• System
• Audio
• Video
• Programming（ASM、BASIC，……）
• MSX-DOS
• MSX-UNAPI
• MSX BASIC

以及以下书籍和手册：

• MSX2 Technical Handbook
• The MSX Red Book
• SDCC Compiler

资源来源：

• Grauw MSX Assembly Page
• Z80 Heaven Wiki
• The MSX Red Book
• MSX2 Technical Handbook
• Konamiman MSX-UNAPI-specification
• BiFi MSX Net
• MRC Wiki
• MSX Banzai!
• SDCC

感谢这些资源的作者，他们以各种许可证提供了这些资源。本 MCP 服务包含其中一些资源，以提升开发体验。

重要

这些资源的权利归各自作者所有，并按照他们指定的许可证分发。

快速开始

你可以通过预编译的 NPM 包，以这种基本方式使用此 MCP 服务。

使用 VSCode 快速安装

在 VSCode 中安装 MCP 服务的步骤：

1. 安装 Github Copilot 扩展
2. 安装 nodejs（npx 命令必须可在你的 PATH 中使用）。
3. 安装 MCP 服务：
   • 使用上方的 Install MCP Server 按钮，在 VSCode 设置中安装 MCP 服务。
   • 或在你的 工作区文件夹 中添加一个名为 .vscode/mcp.json 的文件，并写入下方的 json 配置。

STDIO 模式（推荐）

{
  "servers": {
    "mcp-openmsx": {
      "command": "npx",
      "args": ["@nataliapc/mcp-openmsx"],
      "env": {
        "OPENMSX_SHARE_DIR": "C:\\the\\location\\of\\your\\openmsx\\share\\folder"
      }
    }
  }
}

说明

在 Windows 中，如果遇到权限问题，可以将 command 字段改为 npx.cmd。

说明

环境变量为可选项。请根据需要自定义。

流式 HTTP 模式（更高级）

{
  "servers": {
    "mcp-openmsx": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { }
    }
  }
}

说明

MCP HTTP 服务必须在同一台计算机或另一台计算机上独立运行（make run_http）。

使用 Claude Desktop 基本安装

按照这些说明访问 Claude 的 claude_desktop_config.json 文件。

编辑该文件，加入以下 JSON 条目：

{
  "mcpServers": {
    "mcp-openmsx": {
      "command": "npx",
      "args": ["@nataliapc/mcp-openmsx"],
      "env": {
        "OPENMSX_SHARE_DIR": "C:\\the\\location\\of\\your\\openmsx\\share\\folder"
      }
    }
  }
}

说明

环境变量为可选项。请根据需要自定义。

环境变量

变量	描述	默认值	示例
OPENMSX_EXECUTABLE	openMSX 可执行文件的路径或命令	自动检测：openmsx（Linux）、/Applications/openMSX.app/Contents/MacOS/openmsx（macOS）、openmsx.exe（Windows）	/usr/local/bin/openmsx 或 C:\Program Files\openMSX\openmsx.exe
OPENMSX_SHARE_DIR	包含 openMSX 数据文件（机器、扩展等）的目录	取决于系统	/home/myuser/.openmsx/share
OPENMSX_SCREENSHOT_DIR	保存屏幕截图的目录	openmsx 的默认目录	/myproject/screenshots
OPENMSX_SCREENDUMP_DIR	保存屏幕转储的目录	openmsx 的默认目录	/myproject/screendumps
OPENMSX_REPLAYS_DIR	保存回放文件的目录	openmsx 的默认目录	/myproject/replays
OPENMSX_ENABLE_RAW_TCL	注册可选的 openmsx_tcl_cmd 原生 Tcl 工具。此工具会授予 MCP 客户端对 openMSX 的强大访问权限，并可能访问主机文件系统；仅在明确需要时启用。	false	true
OPENMSX_LAUNCH_HEADLESS	无渲染器窗口启动 openMSX（无头模式）。启动时将 renderer 设为 none，而不是默认的 SDLGL-PP。适用于 CI、测试和服务器端环境。	false	true
MCP_TRANSPORT	传输模式（stdio 或 http）	stdio	http
MCP_HTTP_PORT	HTTP 传输模式的端口号	3000	8080
MCP_ALLOWED_ORIGINS	HTTP 传输允许的源列表，以逗号分隔	留空表示允许所有源	http://localhost,http://mydomain.com
OPENMSX_WINDOWS_CONTROL	仅限 Windows。 服务与 openMSX 控制套接字通信的方式（见下文）	stdio-proxy	direct-sspi
OPENMSX_WINDOWS_PROXY_EXECUTABLE	仅限 Windows。 覆盖 SSPI 代理辅助程序的路径（开发用途）	内置的 bin/win-x64/mcp-openmsx-sspi-proxy.exe	C:\path\to\mcp-openmsx-sspi-proxy.exe
OPENMSX_MODELS_CACHE	缓存嵌入模型的目录（也支持 HF_HOME / TRANSFORMERS_CACHE）	~/.cache/mcp-openmsx	/opt/models
OPENMSX_EMBED_PROVIDER	仅限索引生成器。 使用 cuda 时，将通过 GPU（fp32 模型）重新生成索引；如果 CUDA 不可用，则回退到 CPU。MCP 服务本身始终使用 CPU/int8，并忽略此变量。	（生成器：cpu）	cuda

原生 Tcl 命令工具（OPENMSX_ENABLE_RAW_TCL）

可选的 openmsx_tcl_cmd 工具可直接访问 openMSX 的原生 Tcl 控制台，以使用类型化工具未涵盖的高级功能或特定版本功能。执行不熟悉的命令前，可以使用运行时自我文档命令 help、about、openmsx_info 和 machine_info。

此工具默认不注册。只有用户应在 MCP 服务配置中启用它：

{
  "env": {
    "OPENMSX_ENABLE_RAW_TCL": "true"
  }
}

直接 Tcl 不受限制，可能会修改模拟器状态、访问文件、加载脚本或终止 openMSX。请将其视为授予 MCP 客户端本地命令执行权限。更改此设置后，请重启 MCP 服务。

文档搜索模型

vector_db_query 工具会运行本地混合搜索（语义嵌入 + BM25）。嵌入模型 （multilingual-e5-small，ONNX 量化版，约 118 MB，512 个词元的上下文，多语言）会在首次查询时从 HuggingFace Hub 下载一次 并缓存到磁盘（参见上文的 OPENMSX_MODELS_CACHE）。之后即可完全离线运行。无需 API 密钥。要为隔离网络环境预先填充缓存，请在联网的机器上运行一次 查询，然后复制缓存目录。

重新生成索引（较少发生）时会对整个语料库进行嵌入。在 CPU 上速度较慢；在 NVIDIA GPU 上设置 OPENMSX_EMBED_PROVIDER=cuda，让生成器使用 GPU（需要 CUDA 13 运行时库 + cuDNN 9）， 速度约快 50 倍。GPU 路径使用更大的 fp32 模型；服务仍使用 int8 模型，两者可互换用于搜索（排序结果相同）。最终用户不会下载 fp32 模型。

Windows 控制模式（OPENMSX_WINDOWS_CONTROL）

在 Windows 上，openMSX 是 GUI 应用，其 TCP 控制套接字需要 SSPI（Negotiate/NTLM）身份验证。该服务支持多种传输方式：

值	说明
stdio-proxy	默认。 启动一个独立的 .NET 帮助程序来执行 SSPI，并提供简洁的 XML stdio 通道——这是最稳健的方式。
direct-sspi	通过可选的 node-expose-sspi 软件包从 Node 进行身份验证。回退方案／调试方式。
socket	direct-sspi 的旧别名。

Linux 和 macOS 不受影响（openmsx -control stdio）。

捆绑的代理由 helpers/openmsx-sspi-proxy 构建，可在 Linux 上使用 Docker 可复现地重新构建（无需本地安装 .NET）：

cd mcp-server
pnpm build:proxy:win-x64:docker   # → bin/win-x64/mcp-openmsx-sspi-proxy.exe

高级手动用法

重要

使用 MCP 服务无需执行此操作；但如果要手动安装，请按照以下步骤操作。

MCP 服务可在 Linux、macOS 和 Windows 上运行。从源代码构建需要 Node.js >= 18 和 TypeScript。

手动安装

npm install -g @nataliapc/mcp-openmsx

手动设置环境变量

设置可选环境变量以自定义服务：

export OPENMSX_EXECUTABLE="openmsx"
export OPENMSX_SHARE_DIR="/usr/share/openmsx"
export OPENMSX_SCREENSHOT_DIR="/my_project/screenshots"
export OPENMSX_SCREENDUMP_DIR="/my_project/screendumps"
export OPENMSX_REPLAYS_DIR="/my_project/replays"
export OPENMSX_ENABLE_RAW_TCL="true"
export OPENMSX_LAUNCH_HEADLESS="true"
export MCP_HTTP_PORT=3000
export MCP_ALLOWED_ORIGINS="http://localhost,http://mydomain.com"

作为 MCP 服务（stdio）运行

mcp-openmsx

作为 HTTP 服务运行

MCP_TRANSPORT=http mcp-openmsx
# or
mcp-openmsx http

开发

重要

使用 MCP 服务无需执行此操作；但如果要参与贡献或修改代码，请按照以下步骤操作。

构建前提条件

• Node.js >= 18.0.0
• TypeScript
• 已安装 openMSX 模拟器

构建

git clone https://github.com/nataliapc/mcp-openmsx.git
cd mcp-openmsx/mcp-server
npm install
npm run build

在开发模式下运行

npm run dev

许可证

GPL2 许可证 - 详情请参阅 LICENSE 文件。

支持

如果需要帮助，或有任何问题或建议，请在 GitHub Issues 页面提交 issue，或查看项目讨论区。

参与贡献

欢迎贡献！请随时提交 Pull Request。

更多星标！

如果你喜欢这个项目，请在 GitHub 上给我们点个星标。

星标历史

---