@nataliapc/mcp-openmsx 1.2.6 → 1.2.7

package/README.md

@@ -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` (Linux/macOS) / `openmsx.exe` (Windows) | `/usr/local/bin/openmsx` or `C:\Program Files\openMSX\openmsx.exe` |
+| `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` |

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) => {
@@ -311,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
@@ -364,6 +474,7 @@ export class OpenMSX {
             this.process = null;
             this.isConnected = false;
         }
+        this.closePipeWriter();
     }
 }
 /**

package/dist/server.js

@@ -20,7 +20,7 @@ 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";
@@ -32,9 +32,7 @@ const resourcesDir = path.join(__dirname, "../resources");
 const vectorDbDir = path.join(__dirname, "../vector-db");
 export const emuDirectories = {
     OPENMSX_SHARE_DIR: '',
-    // 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_EXECUTABLE: detectOpenMSXExecutable(),
     OPENMSX_REPLAYS_DIR: '',
     OPENMSX_SCREENSHOT_DIR: '',
     OPENMSX_SCREENDUMP_DIR: '',

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.6",
+  "version": "1.2.7",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",