MCP Openmsx

🚀 MCP-openMSX

本项目借助标准化的MCP协议，为MSX软件开发、测试和自动化提供了全面的工具，是现代AI辅助开发与复古计算（MSX系统）之间的桥梁。

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

🚀 快速开始

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

使用VSCode快速安装

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

1. 安装 Github Copilot扩展
2. 安装nodejs（您的PATH中必须有npx命令）。
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"
      }
    }
  }
}

⚠️ 重要提示

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

流式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"
      }
    }
  }
}

⚠️ 重要提示

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

环境变量

✨ 主要特性

本项目在现代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["您的AI开发伙伴<br>(支持MCP客户端)"]
    EMU["openMSX模拟器<br>(本地实例)"]

    subgraph mcpGroup["**mcp-openmsx**"]
      MCP["MCP服务器<br>stdio / http"]
      TOOLS["MCP工具"]
      VECTORDB[("嵌入式RAG<br>(向量数据库)")]
      RESOURCES["MCP资源"]
      LOCALDATA["本地数据<br>(内部文档)"]
    end
    EXTDATA["外部数据<br>(网页)"]

    HOST <--"_MCP<br>&nbsp;协议&nbsp;_"--> MCP
    MCP <--> TOOLS & RESOURCES
    TOOLS <--"_&nbsp;查询&nbsp;_"--> VECTORDB
    TOOLS <--"_&nbsp;控制台命令&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、advanced_basic_listing。
• debug_vram：VRAM操作：getBlock、readByte、writeByte。
• debug_breakpoints：断点管理：create、remove、list。

自动化工具

• emu_keyboard：向模拟器发送文本输入：sendText。
• 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中，另一些在查询时可通过下载访问。它们分为以下几类：

• 处理器（Z80、R800）
• BIOS（BIOS ROM、DOS ROM、SUBROM等）
• 系统
• 音频
• 视频
• 编程（ASM、BASIC等）
• MSX-DOS
• MSX-UNAPI
• MSX BASIC

还有书籍和手册：

• MSX2技术手册
• MSX红宝书
• SDCC编译器

资源来源：

• Grauw MSX汇编页面
• Z80 Heaven维基
• MSX红宝书
• MSX2技术手册
• Konamiman MSX-UNAPI规范
• BiFi MSX网络
• MRC维基
• MSX Banzai!
• SDCC

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

⚠️ 重要提示

这些资源的版权归各自的作者所有，并根据他们定义的许可证进行分发。

💻 高级手动使用

⚠️ 重要提示

使用MCP服务器不需要此步骤，但如果您想手动安装，请按照以下步骤操作。

目前，MCP服务器需要在Linux上编译。虽然它可能也适用于macOS，但尚未在Windows或macOS上进行测试。

手动安装

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

作为MCP服务器（stdio）

mcp-openmsx

作为HTTP服务器

MCP_TRANSPORT=http mcp-openmsx
# 或者
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 页面上打开一个问题，或查看项目讨论。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。