@nataliapc/mcp-openmsx 1.2.5 → 1.2.6

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 | `openmsx` (Linux/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

@@ -166,8 +166,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 {
@@ -348,6 +353,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) {

package/dist/server.js

@@ -16,6 +16,7 @@ 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";
@@ -26,11 +27,14 @@ 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',
+    // On Windows, Node.js spawn() may not resolve 'openmsx' to 'openmsx.exe' unless it is in PATH.
+    // Using the platform-aware default reduces friction for Windows users who have openMSX in PATH.
+    OPENMSX_EXECUTABLE: process.platform === 'win32' ? 'openmsx.exe' : 'openmsx',
     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/package.json

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

package/resources/programming/basic_wiki/_toc.json

@@ -119,7 +119,7 @@
         },
         {
             "title": "CLOAD? - Verify Cassette Load",
-            "uri": "msxdocs://basic_wiki/CLOAD?",
+            "uri": "msxdocs://basic_wiki/CLOAD_Q",
             "description": "Verifies a BASIC program on cassette tape against the program in memory."
         },
         {