mcp-openmsx-usage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP-OpenMSX Usage Guide

MCP-OpenMSX 使用指南

Skill usage

技能使用说明

Read this file completely.
Read the linked files if topic/description is relevant to your task. Always load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.

完整阅读本文档。
如果主题/描述与你的任务相关，请阅读链接文件。只要有微小概率可能需要相关内容，就务必加载参考文件。拥有上下文总好过遗漏模式或犯错。

Overview

概述

mcp-openmsx

is an MCP server that bridges AI assistants with the openMSX MSX emulator. It spawns openMSX, sending TCL commands via STDIO or HTTP transports.

Typical workflow: launch emulator → insert media → interact (keyboard/BASIC/debug) → capture screen → close.

mcp-openmsx

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

典型工作流：启动模拟器 → 插入介质 → 交互（键盘/BASIC/调试）→ 捕获屏幕 → 关闭。

Prerequisites

前提条件

Using

mcp-openmsx

stdio

mode requires:

```
npx
```
installed.
```
openMSX emulator
```
installed and accessible via
```
$PATH
```
or set
```
OPENMSX_EXECUTABLE
```
env.
```
mcp-openmsx
```
installed
.
Set
```
OPENMSX_SHARE_DIR
```
env if auto-detection fails or custom folder is needed.

在

stdio

模式下使用

mcp-openmsx

需要：

已安装
```
npx
```
。
已安装
```
openMSX模拟器
```
，且可通过
```
$PATH
```
访问，或设置
```
OPENMSX_EXECUTABLE
```
环境变量。
已
安装
```
mcp-openmsx
```
。
如果自动检测失败或需要自定义文件夹，请设置
```
OPENMSX_SHARE_DIR
```
环境变量。

Skill Index

技能索引

MCP Configuration: How to configure the MCP server, including transport selection (stdio vs HTTP), emulator executable path, and share directory settings.
Environment Variables
MCP tools reference:
1. Emulator Control: Manage emulator state (launch, power, reset), media (tapes, ROMs, disks), machine info, keyboard input, savestates, and time-travel replay.
2. VDP (Video Display Processor): Inspect and modify VDP state, including registers, palette, screen mode, and text content.
3. Screen Capture: Capture screenshots, and screen memory dumps from the emulator.
4. Debugging: Control execution (break, continue, step), inspect CPU registers, RAM, and VRAM, manage breakpoints.
5. BASIC Programming: Write, load, run, and manage BASIC programs on the emulator.
6. Documentation & Search: Search and retrieve MSX technical documentation from the embedded vector database and resource library to support development tasks.
MCP Resources: Extensive collection of MSX documentation resources and reference materials embedded in the MCP vector database, organized by category and topic for easy retrieval.
MCP Prompts: Custom MCP prompts for generating structured reference materials based on the embedded documentation resources, such as an MSX BASIC instruction manual page.
Tips & Best Practices

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

Workflows reference files and guides

工作流参考文件与指南

Detailed step-by-step guides for common workflows. ALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake. Read the relevant file when needed:

MSX documentation search workflow — Search and retrieve MSX technical documentation from the embedded vector database and resource library to support development tasks.
Launch and configure an MSX machine — Discover machines/extensions, launch, wait for boot, verify status, speed control, power cycle.
Programming in MSX BASIC — Write, load, run, verify, and manage BASIC programs. Includes line management, interrupting, and loading large programs.
Debugging the VDP — Inspect/modify VDP registers, palette, VRAM, screen modes. Includes sprite debugging and screen corruption analysis workflows.
Debugging a BASIC program — Interrupt execution, inspect state, edit lines, low-level interpreter debugging, time-travel, infinite loop detection, variable inspection.
Debugging an ASM program — Breakpoints, stepping, register/memory inspection, disassembly, BIOS call verification, crash/hang analysis, locating functions without .sym files.
Debugging MSX-DOS programs — Correct breakpoint workflow for MSX-DOS disk-loaded programs. Avoids boot contamination (BIOS/DOS firing breakpoints before app starts). Includes hang detection and savestate checkpointing.
Working with media (ROM, disk, tape) — Insert/eject ROMs, disks, tapes. Development workflows for each media type.
Time-travel debugging with replay and savestates — Timeline navigation, frame-by-frame stepping, checkpointing, comparing execution paths.
Screen capture and visual verification — Screenshots (inline/file), screen dumps (MSX format), text reading, before/after comparison.

以下是常见工作流的详细分步指南。只要有微小概率可能需要相关内容，就务必加载参考文件。拥有上下文总好过遗漏模式或犯错。必要时阅读相关文件：

MSX文档搜索工作流 — 从嵌入式向量数据库和资源库中搜索和检索MSX技术文档，以支持开发任务。
启动并配置MSX机器 — 发现机器/扩展、启动、等待开机、验证状态、速度控制、电源循环。
MSX BASIC编程 — 编写、加载、运行、验证和管理BASIC程序。包括行管理、中断和加载大型程序。
VDP调试 — 检查/修改VDP寄存器、调色板、VRAM、屏幕模式。包括精灵调试和屏幕损坏分析工作流。
BASIC程序调试 — 中断执行、检查状态、编辑代码行、底层解释器调试、时间回溯、无限循环检测、变量检查。
ASM程序调试 — 断点、单步执行、寄存器/内存检查、反汇编、BIOS调用验证、崩溃/挂起分析、在无.sym文件的情况下定位函数。
MSX-DOS程序调试 — 针对MSX-DOS磁盘加载程序的正确断点工作流。避免启动污染（BIOS/DOS在应用启动前触发断点）。包括挂起检测和存档状态检查点。
介质操作（ROM、磁盘、磁带） — 插入/弹出ROM、磁盘、磁带。针对每种介质类型的开发工作流。
基于重放和存档状态的时间回溯调试 — 时间线导航、逐帧单步、检查点、比较执行路径。
屏幕捕获与视觉验证 — 截图（内联/文件）、屏幕转储（MSX格式）、文本读取、前后对比。

Tips & Best Practices

技巧与最佳实践

All addresses and values use hexadecimal format (e.g.
```
0x4000
```
,
```
0xA5
```
).
Always
```
emu_control.wait
```
a few seconds after
```
launch
```
to let the machine fully boot before interacting.
Use
```
screen_shot.as_image
```
to visually verify emulator state at any point.

Use

debug_run.break

before

emu_replay.goBack

absoluteGoto

to keep the timeline stable.

Use
```
vector_db_query
```
to search MSX documentation before relying on general knowledge.
Use
```
basic_programming
```
tools instead of
```
emu_keyboard.sendText
```
for BASIC development — they handle speed optimization and input encoding automatically.
Use
```
emu_savestates
```
to checkpoint progress during complex debugging sessions.
Addresses from
```
.sym
```
/
```
.map
```
files can be used directly with
```
debug_breakpoints.create
```
and
```
debug_run.runTo
```
.
MSX-DOS programs: never set breakpoints before confirming the app is on screen — the BIOS/DOS boot fires them first. See Debugging MSX-DOS Programs.
CP437 character encoding is the nearest encoding for MSX international charmap, use it for text input/output. Be mindful of special characters.

所有地址和值均使用十六进制格式（例如
```
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

。

MSX-DOS程序：在确认应用已显示在屏幕上之前，切勿设置断点——BIOS/DOS启动过程会先触发这些断点。请参阅MSX-DOS程序调试。
CP437字符编码是最接近MSX国际字符集的编码，请将其用于文本输入/输出。注意特殊字符。