Skip to main content
Glama
deeneskozh
nataliapc

mcp-openmsx

by nataliapc
OverviewSchemaRelated ServersScoreDiscussions
Hybrid

MCP-openMSX

“编排一场二进制歌剧，AI 指挥，MCP 诠释，openMSX 担任 8 位元歌剧女主角。”

Built by NataliaPC License GitHub Repo stars NPM Version NPM Downloads

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

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

🎁🎁 如果您觉得本项目有用，请考虑捐赠：PAYPAL 链接

目录

Related MCP server: MCP Toolbox for Databases

项目概述

本项目通过提供以下功能，在现代 AI 辅助开发（如 GitHub Copilot、Claude Desktop）与复古计算（MSX 系统）之间架起了一座桥梁：

  • 模拟器控制：启动、配置、管理 openMSX 实例并重放时间轴。

  • 媒体管理：处理 ROM 卡带、软盘和盒式磁带。

  • BASIC 编程支持：促进 BASIC 语言编程和开发的工具。

  • 调试工具：完整的 CPU 调试，包括断点、内存检查和单步执行。

  • 视频控制：VDP 寄存器操作和屏幕截图。

  • 内存操作：读/写 RAM、VRAM 和 I/O 端口访问。

  • 自动化：键盘输入模拟和状态保存管理。

  • 向量数据库集成：查询包含 MSX 资源的嵌入式向量数据库以获取开发支持。

  • 混合模式：此 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> protocol _"--> MCP
    MCP <--> TOOLS & RESOURCES
    TOOLS <--"_ Query _"--> VECTORDB
    TOOLS <--"_ Console commands _"---> EMU
    RESOURCES <--_ http _---> 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（获取 I/O 端口映射）。

  • emu_media：管理 ROM、磁盘和磁带媒体：tapeInsert（插入磁带）、tapeRewind（磁带倒带）、tapeEject（弹出磁带）、romInsert（插入 ROM）、romEject（弹出 ROM）、diskInsert（插入磁盘）、diskInsertFolder（插入磁盘文件夹）、diskEject（弹出磁盘）。

  • emu_vdp：管理 VDP（视频显示处理器）：getPalette（获取调色板）、getRegisters（获取寄存器）、getRegisterValue（获取寄存器值）、setRegisterValue（设置寄存器值）、screenGetMode（获取屏幕模式）、screenGetFullText（获取完整屏幕文本）。

编程工具

  • basic_programming：BASIC 工具：isBasicAvailable（检查 BASIC 是否可用）、newProgram（新程序）、runProgram（运行程序）、setProgram（设置程序）、getFullProgram（获取完整程序）、getFullProgramAdvanced（高级获取完整程序）、listProgramLines（列出程序行）、deleteProgramLines（删除程序行）。

调试工具

  • debug_run：控制执行：break（中断）、isBreaked（是否中断）、continue（继续）、stepIn（单步进入）、stepOut（单步跳出）、stepOver（单步跳过）、stepBack（单步后退）、runTo（运行至）。

  • debug_cpu：读/写 CPU 寄存器、CPU 信息、堆栈和反汇编代码：getCpuRegisters（获取 CPU 寄存器）、getRegister（获取寄存器）、setRegister（设置寄存器）、getStackPile（获取堆栈）、disassemble（反汇编）、getActiveCpu（获取当前 CPU）。

  • debug_memory：RAM 内存操作：selectedSlots（选定插槽）、getBlock（获取块）、readByte（读取字节）、readWord（读取字）、writeByte（写入字节）、writeWord（写入字）、searchBytes（搜索字节）。

  • debug_vram：VRAM 操作：getBlock（获取块）、readByte（读取字节）、writeByte（写入字节）、searchBytes（搜索字节）。

  • debug_breakpoints：断点管理：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 系统、卡带和其他开发资源的信息。

  • msxdocs_resource_get：为不支持 MCP 资源的 MCP 客户端检索 MCP 资源。

可用的 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（MSX2 技术手册）

  • The MSX Red Book（MSX 红皮书）

  • SDCC Compiler（SDCC 编译器）

资源来源：

感谢这些资源的作者，他们以各种许可证发布了这些资源。此 MCP 服务器包含其中一些资源，以增强开发体验。

IMPORTANT

这些资源的权利属于其各自的作者，并根据他们定义的许可证进行分发。

快速入门

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

使用 VSCode 快速安装

Install in VS Code

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

  1. 安装 Github Copilot 扩展

  2. 安装 nodejs（npx 命令必须在您的 PATH 中可用）。

  3. 安装 MCP 服务器：

    • 使用上方的 Install MCP Server 按钮将 MCP 服务器安装到您的 VSCode 设置中。

    • 或者在您的 工作区文件夹 中添加一个名为 .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"
      }
    }
  }
}
NOTE

环境变量是可选的。您可以根据需要自定义它们。

流式 HTTP 模式（更高级）

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

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"
      }
    }
  }
}
NOTE

环境变量是可选的。您可以根据需要自定义它们。

环境变量

变量

描述

默认值

示例

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

MCP_TRANSPORT

传输模式 (stdio 或 http)

stdio

http

MCP_HTTP_PORT

HTTP 传输模式的端口号

3000

8080

MCP_ALLOWED_ORIGINS

HTTP 传输允许的来源列表（逗号分隔）

为空表示允许所有

http://localhost,http://mydomain.com

高级手动用法

IMPORTANT

使用 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 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

开发

IMPORTANT

使用 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 页面上提交问题，或查看项目讨论。

贡献

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

更多星标！

如果您喜欢这个项目，请在 [GitHub](https://github.com/nataliapc/mcp-open

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nataliapc/mcp-openmsx'

If you have feedback or need assistance with the MCP directory API, please join our Discord server