星战科技xingzhan.cloud
返回市场
MCP开源MSX服务器

MCP开源MSX服务器

作者：nataliapc42 星标更新：2025-08-25
安装使用来源：spider==github.com

项目介绍

MCP-openMSX

"在AI指挥、MCP诠释、openMSX扮演8位女神的二进制歌剧中进行编排。"

由NataliaPC构建 许可证 GitHub仓库星标数
NPM版本 NPM下载量

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

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

🎁🎁 如果您发现这个项目有用，请考虑捐款：PAYPAL链接

目录

项目概述

该项目通过提供以下内容，在现代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:2px,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服务器能力的结构化数据集、文档和辅助文件。它们提供了诸如机器定义、扩展列表、媒体模板和编程示例等重要信息，使MSX软件在MCP-openMSX环境中能够进行更强大的自动化、测试和开发工作流程。

可用资源

有超过60种资源可供使用，有些直接包含在MCP中，而其他则可以通过查询下载。它们被组织成以下类别：

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

以及书籍和手册：

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

来源：

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

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

快速开始

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

使用VSCode快速安装

在VS Code中安装

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

  1. 安装Github Copilot扩展
  2. 安装Node.js（npx命令必须在PATH中可用）。
  3. 安装MCP服务器：
    • 使用上面的安装MCP服务器按钮在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"
      }
    }
  }
}

[!注意]
环境变量是可选的。根据需要自定义它们。

流式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_EXECUTABLEopenMSX可执行文件的路径或命令openmsx/usr/local/bin/openmsx
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）stdiohttp
MCP_HTTP_PORTHTTP传输模式的端口号30008080

高级手动使用

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

目前，MCP服务器需要Linux才能编译。尚未在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问题页面上打开一个问题或查看项目讨论。

贡献

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

更多星标！

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

星标历史图表

星标历史