@nataliapc/mcp-openmsx 1.2.5 → 1.2.7

package/README.md

@@ -105,8 +105,8 @@ The MCP server translates high-level natural language commands from your Copilot
 ### Debugging Tools
 - `debug_run`: Control execution: _`break`, `isBreaked`, `continue`, `stepIn`, `stepOut`, `stepOver`, `stepBack`, `runTo`_.
 - `debug_cpu`: Read/write CPU registers, CPU info, Stack pile, and Disassemble code: _`getCpuRegisters`, `getRegister`, `setRegister`, `getStackPile`, `disassemble`, `getActiveCpu`_.
-- `debug_memory`: RAM memory operations: _`selectedSlots`, `getBlock`, `readByte`, `readWord`, `writeByte`, `writeWord`, `advanced_basic_listing`_.
-- `debug_vram`: VRAM operations: _`getBlock`, `readByte`, `writeByte`_.
+- `debug_memory`: RAM memory operations: _`selectedSlots`, `getBlock`, `readByte`, `readWord`, `writeByte`, `writeWord`, `searchBytes`_.
+- `debug_vram`: VRAM operations: _`getBlock`, `readByte`, `writeByte`, `searchBytes`_.
 - `debug_breakpoints`: Breakpoint management: _`create`, `remove`, `list`_.
 
 ### Automation Tools
@@ -241,7 +241,7 @@ Edit it to include the following JSON entry:
 
 | Variable | Description | Default Value | Example |
 |----------|-------------|---------------|---------|
-| `OPENMSX_EXECUTABLE` | Path or command to the openMSX executable | `openmsx` | `/usr/local/bin/openmsx` |
+| `OPENMSX_EXECUTABLE` | Path or command to the openMSX executable | Auto-detected: `openmsx` (Linux), `/Applications/openMSX.app/Contents/MacOS/openmsx` (macOS), `openmsx.exe` (Windows) | `/usr/local/bin/openmsx` or `C:\Program Files\openMSX\openmsx.exe` |
 | `OPENMSX_SHARE_DIR` | Directory containing openMSX data files (machines, extensions, etc.) | System dependent | `/home/myuser/.openmsx/share` |
 | `OPENMSX_SCREENSHOT_DIR` | Directory where screenshots will be saved | Default for openmsx | `/myproject/screenshots` |
 | `OPENMSX_SCREENDUMP_DIR` | Directory where screen dumps will be saved | Default for openmsx | `/myproject/screendumps` |
@@ -256,7 +256,7 @@ Edit it to include the following JSON entry:
 > [!IMPORTANT]  
 > This is not needed for using the MCP server, but if you want to install it manually, follow these steps.
 
-Currently, the MCP server requires Linux to be compiled. It has not been tested on Windows or macOS, although it will likely work on the latter as well.
+The MCP server runs on Linux, macOS, and Windows. Building from source requires Node.js >= 18 and TypeScript.
 
 ### Manual installation
 

package/dist/openmsx.js

@@ -7,16 +7,37 @@
 import fs from "fs/promises";
 import { extractDescriptionFromXML, decodeHtmlEntities, encodeHtmlEntities } from "./utils.js";
 import { spawn } from 'child_process';
+import { createWriteStream } from 'fs';
 import path from 'path';
+/** True when running on Windows. Evaluated once at module load. */
+const IS_WINDOWS = process.platform === 'win32';
 /**
- * OpenMSX class for controlling the openMSX emulator via TCL commands over TCP socket
+ * OpenMSX class for controlling the openMSX emulator via TCL commands over stdio (Linux/macOS)
+ * or a Windows named pipe (Windows).
+ *
+ * Protocol summary (same XML protocol on all platforms):
+ *   openMSX → stdout  : XML output including <openmsx-output>, <reply>, <log>, <update>
+ *   controller → openMSX : XML commands via stdin (stdio mode) or named pipe (pipe mode)
+ *
+ * On Linux/macOS: openmsx -control stdio
+ *   Commands are sent via the child process stdin; replies come on stdout.
+ *
+ * On Windows: openmsx -control pipe:<pipename>
+ *   openMSX reads commands from \\.\pipe\<pipename> (a Windows named pipe).
+ *   Replies/output are still written to stdout (captured by Node's stdio pipes).
+ *   We write commands to the named pipe using a WriteStream opened on the pipe path.
+ *
+ * Reference: https://openmsx.org/manual/openmsx-control.html
  */
 export class OpenMSX {
     lastMachine = null;
     process = null;
     isConnected = false;
+    // Windows named pipe write stream (only used on Windows with -control pipe)
+    pipeWriter = null;
     /**
-     * Launch the openMSX emulator in stdio control mode
+     * Launch the openMSX emulator in stdio control mode (Linux/macOS)
+     * or pipe control mode (Windows).
      * @param machine - MSX machine to emulate (e.g., 'Panasonic_FS-A1GT', 'C-BIOS_MSX2+')
      * @param extensions - Array of extensions to load (e.g., ['fmpac', 'ide'])
      * @returns Promise that resolves when the emulator is ready
@@ -38,8 +59,21 @@ export class OpenMSX {
                     safeResolve(`Error: openMSX emulator instance is already running (currrent machine: ${this.lastMachine}). Close it first before launching a new one.`);
                     return;
                 }
-                // Build command line arguments
-                const args = ['-control', 'stdio'];
+                // Clean up any leftover pipe writer from a previous session
+                // (e.g. if the process crashed and the exit handler didn't run)
+                this.closePipeWriter();
+                // Build command line arguments.
+                // On Windows, openMSX -control stdio has a known issue: the stdin reader
+                // thread blocks on read() and never unblocks cleanly when the pipe closes,
+                // causing openMSX to hang on exit. The correct mode for Windows is
+                // -control pipe:<name>, which uses a Windows named pipe for input and
+                // still writes replies/output to stdout.
+                // On Linux/macOS, -control stdio is correct and uses stdin/stdout directly.
+                // On Windows, use a unique pipe name based on PID to avoid collisions
+                // when multiple MCP server instances run simultaneously.
+                const pipeName = IS_WINDOWS ? `openmsx-mcp-${process.pid}` : '';
+                const controlArg = IS_WINDOWS ? `pipe:${pipeName}` : 'stdio';
+                const args = ['-control', controlArg];
                 // Add machine parameter if specified
                 if (machine) {
                     this.lastMachine = machine; // Store last machine for future reference
@@ -51,14 +85,21 @@ export class OpenMSX {
                         args.push('-ext', ext);
                     });
                 }
-                // Launch openMSX with stdio control
+                // Launch openMSX.
+                // On both modes, stdout/stderr are piped so we can read replies and errors.
+                // On stdio mode, stdin is also piped (we write commands there).
+                // On pipe mode, stdin is ignored ('ignore') — openMSX reads from the named pipe.
                 this.process = spawn(executable, args, {
-                    stdio: ['pipe', 'pipe', 'pipe']
+                    stdio: IS_WINDOWS ? ['ignore', 'pipe', 'pipe'] : ['pipe', 'pipe', 'pipe']
                 });
-                if (!this.process.stdin || !this.process.stdout || !this.process.stderr) {
+                if (!this.process.stdout || !this.process.stderr) {
                     safeResolve('Error: Failed to create stdio pipes');
                     return;
                 }
+                if (!IS_WINDOWS && !this.process.stdin) {
+                    safeResolve('Error: Failed to create stdin pipe');
+                    return;
+                }
                 // Check if process was launched successfully
                 if (!this.process.pid || this.process.killed) {
                     const stderrMessage = this.process.stderr.read()?.toString() || 'Failed to launch openMSX process';
@@ -70,11 +111,21 @@ export class OpenMSX {
                 // Handle process events
                 this.process.on('error', (error) => {
                     console.error('openMSX process error:', error);
-                    safeResolve(`Error: ${error.message}`);
+                    if (error.code === 'ENOENT') {
+                        safeResolve(`Error: openMSX executable not found: "${executable}". ` +
+                            `Set the OPENMSX_EXECUTABLE environment variable to the full path of the openMSX binary. ` +
+                            `On macOS the standard path is /Applications/openMSX.app/Contents/MacOS/openmsx; ` +
+                            `on Windows it is typically C:\\Program Files\\openMSX\\openmsx.exe; ` +
+                            `on Linux it is usually 'openmsx' (in PATH after package install).`);
+                    }
+                    else {
+                        safeResolve(`Error: ${error.message}`);
+                    }
                 });
                 this.process.on('exit', (code, signal) => {
                     this.isConnected = false;
                     this.process = null;
+                    this.closePipeWriter();
                 });
                 // Wait for the opening XML tag to confirm connection
                 this.process.stdout.on('data', (data) => {
@@ -83,10 +134,16 @@ export class OpenMSX {
                         this.isConnected = true;
                         connectionTime = Date.now();
                         // Don't resolve immediately, wait for potential fatal errors
-                        setTimeout(() => {
+                        setTimeout(async () => {
                             // Only resolve if no fatal error occurred during grace period
                             if (!resolved) {
                                 try {
+                                    // On Windows, open the named pipe for writing commands.
+                                    // openMSX has already created the pipe server side by now.
+                                    if (IS_WINDOWS) {
+                                        const pipePath = `\\\\.\\pipe\\${pipeName}`;
+                                        await this.openWindowsPipe(pipePath);
+                                    }
                                     this.writeData('<openmsx-control>\n');
                                     // Set save settings on exit off
                                     this.sendCommand('set save_settings_on_exit off');
@@ -141,6 +198,43 @@ export class OpenMSX {
             }
         });
     }
+    /**
+     * Open a Windows named pipe for writing commands to openMSX.
+     * openMSX creates the pipe server when launched with -control pipe:<name>.
+     * We connect as a client (write-only) after openMSX signals it's ready.
+     * @param pipePath - Full Windows named pipe path, e.g. \\.\pipe\openmsx-mcp-1234
+     */
+    openWindowsPipe(pipePath) {
+        return new Promise((resolve, reject) => {
+            try {
+                // Node.js fs.createWriteStream supports Windows named pipe paths.
+                // The pipe must already exist (created by openMSX) at this point.
+                const writer = createWriteStream(pipePath, { flags: 'r+' });
+                writer.on('open', () => {
+                    this.pipeWriter = writer;
+                    resolve();
+                });
+                writer.on('error', (err) => {
+                    reject(new Error(`Failed to open Windows named pipe "${pipePath}": ${err.message}`));
+                });
+            }
+            catch (err) {
+                reject(new Error(`Failed to create Windows named pipe writer: ${err instanceof Error ? err.message : err}`));
+            }
+        });
+    }
+    /**
+     * Close and destroy the Windows named pipe writer if open.
+     */
+    closePipeWriter() {
+        if (this.pipeWriter) {
+            try {
+                this.pipeWriter.destroy();
+            }
+            catch (_) { /* ignore */ }
+            this.pipeWriter = null;
+        }
+    }
     /**
      * Close the openMSX emulator process
      * @returns Promise that resolves when the process is closed
@@ -155,6 +249,7 @@ export class OpenMSX {
                 this.lastMachine = null; // Clear last machine on exit
                 this.isConnected = false;
                 this.process = null;
+                this.closePipeWriter();
                 resolve("Ok: Emulator process closed successfully");
             });
             this.process.on('error', (error) => {
@@ -166,8 +261,13 @@ export class OpenMSX {
                     this.sendCommand('exit');
                 }
                 catch (error) {
-                    // If writing fails, force kill
-                    this.process.kill('SIGTERM');
+                    // If writing fails, force kill.
+                    // Use no-argument kill() for cross-platform safety:
+                    // on POSIX it sends SIGTERM; on Windows it calls TerminateProcess().
+                    try {
+                        this.process.kill();
+                    }
+                    catch (_) { /* ignore */ }
                 }
             }
             else {
@@ -306,14 +406,29 @@ export class OpenMSX {
         }
     }
     /**
-     * Write data to the openMSX process stdin
+     * Write data to openMSX.
+     * On Linux/macOS: writes to the child process stdin.
+     * On Windows: writes to the named pipe (pipeWriter).
      * @param data - XML command or data to send
      */
     writeData(data) {
-        if (!this.process || !this.process.stdin || !this.isConnected) {
+        if (!this.process || !this.isConnected) {
             throw new Error('openMSX process not running or not connected');
         }
-        this.process.stdin.write(data);
+        if (IS_WINDOWS) {
+            // Windows: send via named pipe
+            if (!this.pipeWriter || this.pipeWriter.destroyed) {
+                throw new Error('Windows named pipe not open');
+            }
+            this.pipeWriter.write(data);
+        }
+        else {
+            // Linux/macOS: send via child process stdin
+            if (!this.process.stdin) {
+                throw new Error('openMSX stdin not available');
+            }
+            this.process.stdin.write(data);
+        }
     }
     /**
      * Read data from openMSX process stdout
@@ -348,6 +463,9 @@ export class OpenMSX {
     forceClose() {
         if (this.process && !this.process.killed) {
             try {
+                // 'SIGKILL' is accepted on Windows too (maps to TerminateProcess).
+                // No-argument kill() is also acceptable here, but SIGKILL makes
+                // the intent explicit: we want unconditional termination.
                 this.process.kill('SIGKILL');
             }
             catch (error) {
@@ -356,6 +474,7 @@ export class OpenMSX {
             this.process = null;
             this.isConnected = false;
         }
+        this.closePipeWriter();
     }
 }
 /**

package/dist/server.js

@@ -16,21 +16,23 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { randomUUID } from "node:crypto";
 import express from "express";
 import path from "path";
+import { fileURLToPath } from 'node:url';
 import { createRequire } from 'module';
 import { openMSXInstance } from "./openmsx.js";
 import { VectorDB } from "./vectordb.js";
-import { detectOpenMSXShareDir } from "./utils.js";
+import { detectOpenMSXExecutable, detectOpenMSXShareDir } from "./utils.js";
 import { registerTools } from "./server_tools.js";
 import { registerResources } from "./server_resources.js";
 import { registerPrompts } from "./server_prompts.js";
 // Dynamically obtain PACKAGE_VERSION from package.json at runtime
 const require = createRequire(import.meta.url);
 export const PACKAGE_VERSION = require('../package.json').version;
-const resourcesDir = path.join(path.dirname(new URL(import.meta.url).pathname), "../resources");
-const vectorDbDir = path.join(path.dirname(new URL(import.meta.url).pathname), "../vector-db");
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const resourcesDir = path.join(__dirname, "../resources");
+const vectorDbDir = path.join(__dirname, "../vector-db");
 export const emuDirectories = {
     OPENMSX_SHARE_DIR: '',
-    OPENMSX_EXECUTABLE: 'openmsx',
+    OPENMSX_EXECUTABLE: detectOpenMSXExecutable(),
     OPENMSX_REPLAYS_DIR: '',
     OPENMSX_SCREENSHOT_DIR: '',
     OPENMSX_SCREENDUMP_DIR: '',

package/dist/server_resources.js

@@ -129,14 +129,18 @@ export async function registerResources(server, resourcesDir) {
         let mimeType;
         // urldecode the instruction to avoid issues with special characters
         instruction = decodeURIComponent(instruction).replaceAll(' ', '_');
+        // Convert Windows-invalid characters to safe equivalents for the filesystem lookup.
+        // The RAG and MCP URIs keep the canonical command name (e.g. CLOAD?),
+        // but the file on disk uses a safe name (e.g. CLOAD_Q.md).
+        const instructionFile = instruction.replaceAll('?', '_Q');
         try {
             let resourceFile;
-            [mimeType, resourceFile] = await addFileExtension(path.join(resourcesDir, 'programming', 'basic_wiki', instruction));
+            [mimeType, resourceFile] = await addFileExtension(path.join(resourcesDir, 'programming', 'basic_wiki', instructionFile));
             resourceContent = await fs.readFile(resourceFile, 'utf8');
         }
         catch (error) {
             // Throw exception (MCP protocol requirement)
-            throw new Error(`Error reading resource programming/basic_wiki/${instruction}: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`Error reading resource programming/basic_wiki/${instruction} (file: ${instructionFile}): ${error instanceof Error ? error.message : String(error)}`);
         }
         return {
             contents: [{

package/dist/server_tools.js

@@ -10,6 +10,7 @@ import { resolveLaunchParams } from "./server_elicitations.js";
 // Tools available in the MCP server
 // https://modelcontextprotocol.io/docs/concepts/tools#tool-definition-structure
 export async function registerTools(server, emuDirectories) {
+    // emu_control
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_control", {
@@ -193,6 +194,7 @@ export async function registerTools(server, emuDirectories) {
             isError: false,
         };
     });
+    // emu_info
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_media", {
@@ -278,6 +280,7 @@ export async function registerTools(server, emuDirectories) {
             response
         ]);
     });
+    // emu_info
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_info", {
@@ -345,6 +348,7 @@ export async function registerTools(server, emuDirectories) {
             isError: false,
         };
     });
+    // emu_vdp
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_vdp", {
@@ -477,6 +481,7 @@ export async function registerTools(server, emuDirectories) {
             isError: false,
         };
     });
+    // debug_run
     server.registerTool(
     // Name of the tool (used to call it)
     "debug_run", {
@@ -549,6 +554,7 @@ export async function registerTools(server, emuDirectories) {
             response
         ]);
     });
+    // debug_cpu
     server.registerTool(
     // Name of the tool (used to call it)
     "debug_cpu", {
@@ -695,6 +701,7 @@ export async function registerTools(server, emuDirectories) {
             isError: false,
         };
     });
+    // debug_memory
     server.registerTool(
     // Name of the tool (used to call it)
     "debug_memory", {
@@ -703,7 +710,7 @@ export async function registerTools(server, emuDirectories) {
         description: "Slots info, and Read/write from/to memory in the openMSX emulator.",
         // Schema for the tool (input validation)
         inputSchema: {
-            command: z.enum(["selectedSlots", "getBlock", "readByte", "readWord", "writeByte", "writeWord"])
+            command: z.enum(["selectedSlots", "getBlock", "readByte", "readWord", "writeByte", "writeWord", "searchBytes"])
                 .describe(`Available commands:
 	'selectedSlots': to get a list of the currently selected memory slots.
 	'getBlock <address> [lines]': to read a block of memory from the specified address.
@@ -711,6 +718,7 @@ export async function registerTools(server, emuDirectories) {
 	'readWord <address>': to read a WORD from the specified address.
 	'writeByte <address> <value8>': to write a BYTE to the specified address.
 	'writeWord <address> <value16>': to write a WORD to the specified address.
+	'searchBytes <address> <length> <values>': to search a sequence of bytes in RAM memory starting from the specified address and within the specified length.
 **Important Note**: Addresses and values are in hexadecimal format (e.g. 0x0000).
 `),
             address: z.string()
@@ -731,6 +739,15 @@ export async function registerTools(server, emuDirectories) {
                 .regex(/^0x[0-9a-fA-F]{4}$/, 'Must be a 4 digits hexadecimal number')
                 .optional()
                 .describe("4 hexadecimal digits for a word value (e.g. 0xa5b1). Used by [writeWord]"),
+            values: z.string()
+                .regex(/^(\s*0x[0-9a-fA-F]{2}\s*)+$/, "Values must be a space-separated string of 2 digits hexadecimal numbers (e.g. '0x1A 0xFF 0x00')")
+                .optional()
+                .describe("Space-separated string of 2 hexadecimal digits for byte values to search (e.g. '0x1A 0xFF 0x00'). Used by [searchBytes]"),
+            length: z.number()
+                .min(1, 'Minimum search length too low. Min: 1')
+                .max(65536, 'Maximum search length too high. Max: 65536')
+                .optional()
+                .describe("Decimal number of bytes to search within. Used by [searchBytes]"),
         },
         // Structured output schema (MCP protocol 2025-11-25)
         outputSchema: {
@@ -746,6 +763,10 @@ export async function registerTools(server, emuDirectories) {
                 .describe("Hex dump block of memory. Present for 'getBlock'."),
             slots: z.string().optional()
                 .describe("Currently selected memory slots info. Present for 'selectedSlots'."),
+            length: z.number().optional()
+                .describe("Length of bytes searched. Present for 'searchBytes'."),
+            values: z.string().optional()
+                .describe("Values searched for. Present for 'searchBytes'."),
             result: z.string().optional()
                 .describe("Generic result or status message."),
         },
@@ -757,7 +778,7 @@ export async function registerTools(server, emuDirectories) {
         },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
-    async ({ command, address, lines, value8, value16 }) => {
+    async ({ command, address, lines, value8, value16, length, values }) => {
         let tclCommand;
         switch (command) {
             case "selectedSlots":
@@ -778,6 +799,23 @@ export async function registerTools(server, emuDirectories) {
             case "writeWord":
                 tclCommand = `poke16 ${address} ${value16}`;
                 break;
+            case "searchBytes":
+                length = parseInt(address, 16) + length > 0x10000 ? 0x10000 - parseInt(address, 16) : length;
+                tclCommand = `set pattern { ${values} }
+								set len [llength $pattern]
+								set results ""
+								for {set i ${address}} {$i \<= [expr {${address} + ${length} - $len}]} {incr i} {
+									set match 1
+									for {set j 0} {$j \< $len} {incr j} {
+										if {[peek [expr {$i + $j}]] != [lindex $pattern $j]} {
+											set match 0; break
+										}
+									}
+									if {$match} { append results [format "Found at 0x%04X\n" $i] }
+								}
+								if {$results eq ""} { return "No matches found" }
+								return $results`;
+                break;
             default:
                 return { content: [{ type: "text", text: `Error: Unknown memory command "${command}".` }], isError: true };
         }
@@ -814,6 +852,10 @@ export async function registerTools(server, emuDirectories) {
                 structuredContent = { command, address, result: response || "Ok" };
                 break;
             }
+            case "searchBytes": {
+                structuredContent = { command, address, length, values, result: response };
+                break;
+            }
             default:
                 structuredContent = { command, result: response };
         }
@@ -823,6 +865,7 @@ export async function registerTools(server, emuDirectories) {
             isError: false,
         };
     });
+    // debug_vram
     server.registerTool(
     // Name of the tool (used to call it)
     "debug_vram", {
@@ -831,11 +874,12 @@ export async function registerTools(server, emuDirectories) {
         description: "Read or write from/to VRAM video memory from the openMSX emulator.",
         // Schema for the tool (input validation)
         inputSchema: {
-            command: z.enum(["getBlock", "readByte", "writeByte"])
+            command: z.enum(["getBlock", "readByte", "writeByte", "searchBytes"])
                 .describe(`Available commands:
 	'getBlock <address> [lines]': to read a block of VRAM memory from the specified address.
 	'readByte <address>': to read a BYTE from the specified VRAM address.
 	'writeByte <address> <value8>': to write a BYTE to the specified VRAM address.
+	'searchBytes <address> <length> <values>': to search a sequence of bytes in VRAM memory starting from the specified address and within the specified length.
 **Important Note**: Addresses and values are in hexadecimal format (e.g. 0x0000).
 `),
             address: z.string()
@@ -849,6 +893,15 @@ export async function registerTools(server, emuDirectories) {
                 .default(8)
                 .describe("Number of lines to obtain. Used by [getBlock]"),
             value8: z.string().regex(/^0x[0-9a-fA-F]{2}$/).optional().describe("2 hexadecimal digits for a byte value (e.g. 0xa5). Used by [writeByte]"),
+            values: z.string()
+                .regex(/^(\s*0x[0-9a-fA-F]{2}\s*)+$/, "Values must be a space-separated string of 2 digits hexadecimal numbers (e.g. '0x1A 0xFF 0x00')")
+                .optional()
+                .describe("Space-separated string of 2 hexadecimal digits for byte values to search (e.g. '0x1A 0xFF 0x00'). Used by [searchBytes]"),
+            length: z.number()
+                .min(1, 'Minimum search length too low. Min: 1')
+                .max(65536, 'Maximum search length too high. Max: 65536')
+                .optional()
+                .describe("Decimal number of bytes to search within. Used by [searchBytes]"),
         },
         // Structured output schema (MCP protocol 2025-11-25)
         outputSchema: {
@@ -862,6 +915,10 @@ export async function registerTools(server, emuDirectories) {
                 .describe("VRAM byte value in hexadecimal. Present for 'readByte'."),
             hexDump: z.string().optional()
                 .describe("Hex dump block of VRAM. Present for 'getBlock'."),
+            length: z.number().optional()
+                .describe("Length of bytes searched. Present for 'searchBytes'."),
+            values: z.string().optional()
+                .describe("Values searched for. Present for 'searchBytes'."),
             result: z.string().optional()
                 .describe("Generic result or status message."),
         },
@@ -873,7 +930,7 @@ export async function registerTools(server, emuDirectories) {
         },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
-    async ({ command, address, lines, value8 }) => {
+    async ({ command, address, lines, value8, values, length }) => {
         let tclCommand;
         switch (command) {
             case "getBlock":
@@ -885,6 +942,23 @@ export async function registerTools(server, emuDirectories) {
             case "writeByte":
                 tclCommand = `vpoke ${address} ${value8}`;
                 break;
+            case "searchBytes":
+                length = parseInt(address, 16) + length > 0x20000 ? 0x20000 - parseInt(address, 16) : length;
+                tclCommand = `set pattern { ${values} }
+								set len [llength $pattern]
+								set results ""
+								for {set i ${address}} {$i \<= [expr {${address} + ${length} - $len}]} {incr i} {
+									set match 1
+									for {set j 0} {$j \< $len} {incr j} {
+										if {[vpeek [expr {$i + $j}]] != [lindex $pattern $j]} {
+											set match 0; break
+										}
+									}
+									if {$match} { append results [format "Found at 0x%04X\n" $i] }
+								}
+								if {$results eq ""} { return "No matches found" }
+								return $results`;
+                break;
             default:
                 return { content: [{ type: "text", text: `Error: Unknown video memory command "${command}".` }], isError: true };
         }
@@ -907,6 +981,10 @@ export async function registerTools(server, emuDirectories) {
                 structuredContent = { command, address, result: response || "Ok" };
                 break;
             }
+            case "searchBytes": {
+                structuredContent = { command, address, length, values, result: response };
+                break;
+            }
             default:
                 structuredContent = { command, result: response };
         }
@@ -916,6 +994,7 @@ export async function registerTools(server, emuDirectories) {
             isError: false,
         };
     });
+    // debug_breakpoints
     server.registerTool(
     // Name of the tool (used to call it)
     "debug_breakpoints", {
@@ -1010,6 +1089,7 @@ export async function registerTools(server, emuDirectories) {
             isError: false,
         };
     });
+    // emu_savestates
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_savestates", {
@@ -1066,6 +1146,7 @@ export async function registerTools(server, emuDirectories) {
             response
         ]);
     });
+    // emu_replay
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_replay", {
@@ -1210,6 +1291,7 @@ export async function registerTools(server, emuDirectories) {
             isError: false,
         };
     });
+    // emu_keyboard
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_keyboard", {
@@ -1288,6 +1370,7 @@ export async function registerTools(server, emuDirectories) {
             response
         ]);
     });
+    // screen_shot
     server.registerTool(
     // Name of the tool (used to call it)
     "screen_shot", {
@@ -1352,6 +1435,7 @@ export async function registerTools(server, emuDirectories) {
             `Error: Unknown screen_shot command "${command}".`
         ]);
     });
+    // screen_dump
     server.registerTool(
     // Name of the tool (used to call it)
     "screen_dump", {
@@ -1384,6 +1468,7 @@ The parameter scrbasename is the name of the filename (without path) to save the
             response
         ]);
     });
+    // basic_programming
     server.registerTool(
     // Name of the tool (used to call it)
     "basic_programming", {
@@ -1549,6 +1634,7 @@ The parameter scrbasename is the name of the filename (without path) to save the
             isError: false,
         };
     });
+    // vector_db_query
     server.registerTool(
     // Name of the tool (used to call it)
     "vector_db_query", {
@@ -1597,6 +1683,7 @@ The response is the list of the top 10 result resources that match the query, in
     // ============================================================================
     // Register a tool to get a specific MSX documentation resource
     // Retrieve MCP resources for MCP clients that don't support MCP resources.
+    // msxdocs_resource_get
     server.registerTool(
     // Name of the tool (used to call it)
     "msxdocs_resource_get", {

package/dist/utils.js

@@ -12,6 +12,32 @@ import { PACKAGE_VERSION } from "./server.js";
 import sanitizeHtml from 'sanitize-html';
 import { existsSync } from "fs";
 import os from "os";
+/**
+ * Detect the openMSX executable path for the current platform.
+ *
+ * - Linux:   'openmsx' (expected in PATH after package install)
+ * - Windows: 'openmsx.exe' (Node spawn() needs the .exe extension on Windows)
+ * - macOS:   probes the standard .app bundle path first; falls back to 'openmsx'
+ *            in case the user has it in PATH (e.g. via Homebrew or manual install).
+ *
+ * The standard macOS bundle path is /Applications/openMSX.app/Contents/MacOS/openmsx.
+ * This is the path documented by the openMSX project (and its Catapult launcher).
+ */
+export function detectOpenMSXExecutable() {
+    if (process.platform === 'win32') {
+        return 'openmsx.exe';
+    }
+    if (process.platform === 'darwin') {
+        const appBundlePath = '/Applications/openMSX.app/Contents/MacOS/openmsx';
+        if (existsSync(appBundlePath)) {
+            return appBundlePath;
+        }
+        // Fallback: user may have openMSX in PATH (e.g. via Homebrew)
+        return 'openmsx';
+    }
+    // Linux / other POSIX
+    return 'openmsx';
+}
 /**
  * Detect the openMSX share directory by checking various methods
  * @returns string - The detected share directory or an empty string if not found

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",