mcp-openmsx-usage

MCP-OpenMSX Usage Guide

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.

Prerequisites

• Node.js >= 18 with npx:
  • Windows: install via nodejs.org or winget install OpenJS.NodeJS
  • macOS: brew install node or the official installer
  • Linux: use your distro package manager or nvm
• openMSX emulator installed and accessible (see MCP Configuration for per-OS paths). Set OPENMSX_EXECUTABLE env if not in PATH.
• mcp-openmsx configured in your MCP client.
• Set OPENMSX_SHARE_DIR env if auto-detection fails or a custom folder is needed.

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: How to search and retrieve MSX technical documentation from the embedded vector database and resource library to support development tasks.
  7. Native Tcl Autodiscovery: Discover and use openMSX console functionality not covered by typed tools through the optional openmsx_tcl_cmd tool.
• 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

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.
• Native Tcl autodiscovery — Runtime discovery with help, about, machine_info, and openmsx_info through the optional raw Tcl tool.

Tips & Best Practices

• For a specific BASIC instruction, read msxdocs://basic_wiki/{INSTRUCTION} directly with read_mcp_resource (or msxdocs_resource_get for enum-named resources). And complement it with a vector_db_query. The basic_wiki resource gives the complete Effect/Syntax/Parameters/Examples/Compatibility page in one call and the vector query search for cross cutting topics. For example, to get the CALL instruction page, use msxdocs://basic_wiki/call and vector_db_query("CALL").
• Use vector_db_query for discovery or cross-cutting questions (e.g. "sprite collision + interlaced mode", "PSG envelope timing").
• Use always \r (CR) as line terminators in BASIC programs. Avoid \n (LF) or \r\n (CRLF) to prevent parsing issues.
• 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 or 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.
• Use debug_conditions.create when the trigger is a machine state rather than a location — a Tcl expression (e.g. [reg SP] > 0xC000) evaluated continuously while the CPU runs.
• 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.