mcp-openmsx-usage

MCP-OpenMSX 使用指南

技能使用方法

• 完整阅读此文件。
• 如果链接文件的主题／说明与你的任务相关，请阅读这些文件。只要有一丝可能会用到其中的内容，就务必加载参考文件。掌握相关上下文总比错过某种模式或犯错更好。

概述

mcp-openmsx 是一款 MCP 服务，可连接 AI 助手与 openMSX MSX 模拟器。它会启动 openMSX，并通过 STDIO 或 HTTP 传输发送 TCL 命令。

典型工作流：启动模拟器 → 插入媒体 → 交互（键盘／BASIC／调试）→ 截取屏幕 → 关闭。

前置条件

• 安装带有 npx 的 Node.js >= 18：
  • Windows：通过 nodejs.org 安装，或运行 winget install OpenJS.NodeJS
  • macOS：运行 brew install node，或使用官方安装程序
  • Linux：使用发行版的软件包管理器或 nvm
• 安装并确保可访问 openMSX 模拟器（各操作系统的路径请参见 MCP 配置）。 如果 openMSX 不在 PATH 中，请设置 OPENMSX_EXECUTABLE 环境变量。
• 在 MCP 客户端中配置 mcp-openmsx。
• 如果自动检测失败或需要指定自定义文件夹，请设置 OPENMSX_SHARE_DIR 环境变量。

技能索引

• MCP 配置：如何配置 MCP 服务，包括选择传输方式（stdio 或 HTTP）、模拟器可执行文件路径和共享目录设置。
• 环境变量
• MCP 工具参考：
  1. 模拟器控制：管理模拟器状态（启动、电源、重置）、媒体（磁带、ROM、磁盘）、机器信息、键盘输入、存档状态和时间回溯重放。
  2. VDP（视频显示处理器）：查看和修改 VDP 状态，包括寄存器、调色板、屏幕模式和文本内容。
  3. 屏幕截图：截取模拟器屏幕截图并转储屏幕内存。
  4. 调试：控制执行（中断、继续、单步执行）、查看 CPU 寄存器、RAM 和 VRAM，以及管理断点。
  5. BASIC 编程：在模拟器上编写、加载、运行和管理 BASIC 程序。
  6. 文档与搜索：了解如何在内置向量数据库和资源库中搜索和检索 MSX 技术文档，以支持开发任务。
  7. 原生 Tcl 自动发现：通过可选的 openmsx_tcl_cmd 工具，发现并使用尚未由类型化工具涵盖的 openMSX 控制台功能。
• MCP 资源：内置于 MCP 向量数据库中的丰富 MSX 文档资源和参考资料，按类别和主题整理，便于检索。
• MCP 提示词：自定义 MCP 提示词，可基于内置文档资源生成结构化参考资料，例如 MSX BASIC 指令手册页面。
• 提示与最佳实践

工作流参考文件和指南

针对常见工作流的详细分步指南。只要有哪怕一丝可能会用到其中的内容，就务必加载参考文件。了解相关上下文总比遗漏模式或犯错好。需要时阅读相关文件：

• MSX 文档搜索工作流 — 从嵌入式向量数据库和资源库中搜索并检索 MSX 技术文档，为开发任务提供支持。
• 启动和配置 MSX 机器 — 发现机器和扩展、启动、等待引导完成、验证状态、控制速度、重启电源。
• 使用 MSX BASIC 编程 — 编写、加载、运行、验证和管理 BASIC 程序。包括行管理、中断程序和加载大型程序。
• 调试 VDP — 检查或修改 VDP 寄存器、调色板、VRAM 和屏幕模式。包括精灵调试和屏幕损坏分析工作流。
• 调试 BASIC 程序 — 中断执行、检查状态、编辑行、低级解释器调试、时间回溯、无限循环检测、变量检查。
• 调试 ASM 程序 — 断点、单步执行、寄存器和内存检查、反汇编、BIOS 调用验证、崩溃或挂起分析，以及在没有 .sym 文件时定位函数。
• 调试 MSX-DOS 程序 — 为从磁盘加载的 MSX-DOS 程序采用正确的断点工作流，避免启动污染（应用启动前 BIOS/DOS 触发断点）。包括挂起检测和存档状态检查点。
• 使用媒体（ROM、磁盘、磁带） — 插入或弹出 ROM、磁盘、磁带。针对每种媒体类型的开发工作流。
• 使用回放和存档状态进行时间回溯调试 — 时间线导航、逐帧执行、创建检查点、比较执行路径。
• 屏幕捕获和视觉验证 — 屏幕截图（内嵌或文件）、屏幕转储（MSX 格式）、文本读取、前后对比。
• 原生 Tcl 自动发现 — 通过可选的原始 Tcl 工具，使用 help、about、machine_info 和 openmsx_info 在运行时进行发现。

提示与最佳实践

• 对于特定的 BASIC 指令，使用 read_mcp_resource 直接读取 msxdocs://basic_wiki/{INSTRUCTION}（对于以枚举命名的资源，则使用 msxdocs_resource_get）。并结合 vector_db_query 查询。basic_wiki 资源可通过一次调用提供完整的作用、语法、参数和示例、兼容性页面；而向量查询适用于搜索跨主题内容。例如，要获取 CALL 指令页面，请使用 msxdocs://basic_wiki/call 和 vector_db_query("CALL")。
• 使用 vector_db_query 探索或查询跨主题问题（例如“精灵碰撞 + 隔行模式”、“PSG 包络定时”）。
• BASIC 程序始终使用 \r（CR）作为行结束符。避免使用 \n（LF）或 \r\n（CRLF），以防解析问题。
• 所有地址和值均使用十六进制格式（例如 0x4000、0xA5）。
• 执行 launch 后，始终使用 emu_control.wait 等待几秒，让机器完全启动后再进行交互。
• 随时使用 screen_shot.as_image 直观确认模拟器状态。
• 在使用 emu_replay.goBack 或 absoluteGoto 前，先使用 debug_run.break，以保持时间线稳定。
• 在依赖常识之前，先使用 vector_db_query 搜索 MSX 文档。
• 开发 BASIC 时，使用 basic_programming 工具，而不是 emu_keyboard.sendText——这些工具会自动处理速度优化和输入编码。
• 在复杂的调试过程中，使用 emu_savestates 保存检查点。
• .sym/.map 文件中的地址可直接用于 debug_breakpoints.create 和 debug_run.runTo。
• 如果触发条件是机器状态而非位置，请使用 debug_conditions.create——它会在 CPU 运行时持续求值 Tcl 表达式（例如 [reg SP] > 0xC000）。
• MSX-DOS 程序：确认应用已显示在屏幕上之前，切勿设置断点——BIOS/DOS 启动时会先触发这些断点。参见 调试 MSX-DOS 程序。
• CP437 字符编码是最接近 MSX 国际字符映射的编码，请用它进行文本输入/输出。请留意特殊字符。