@nataliapc/mcp-openmsx 1.2.6 → 1.2.8

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

@@ -5,27 +5,39 @@
  * @license GPL2
  */
 import fs from "fs/promises";
+import fsSync from "fs";
 import { extractDescriptionFromXML, decodeHtmlEntities, encodeHtmlEntities } from "./utils.js";
 import { spawn } from 'child_process';
+import net from 'net';
+import os from 'os';
 import path from 'path';
-/**
- * OpenMSX class for controlling the openMSX emulator via TCL commands over TCP socket
- */
+/** True when running on Windows. Evaluated once at module load. */
+const IS_WINDOWS = process.platform === 'win32';
 export class OpenMSX {
     lastMachine = null;
     process = null;
     isConnected = false;
+    // Windows TCP socket — bidirectional after SSPI auth
+    tcpSocket = null;
+    // Accumulated I/O data for readData() — shared by both platforms (never coexist)
+    ioBuffer = '';
+    // Notify callback: fired when new I/O data arrives — shared by both platforms
+    ioNotify = null;
+    // Serial command queue — ensures sendCommand calls never overlap on any platform
+    commandQueue = Promise.resolve('');
     /**
-     * Launch the openMSX emulator in stdio control mode
-     * @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
+     * Launch the openMSX emulator.
+     * Linux/macOS: -control stdio via stdin/stdout pipes.
+     * Windows: spawn with ignore+ignore+pipe, TCP socket + SSPI auth.
      */
     async emu_launch(executable, machine, extensions) {
         return new Promise((resolve) => {
             let resolved = false;
-            let connectionTime = null;
-            const FATAL_ERROR_GRACE_PERIOD = 500; // 1/2 second grace period after connection
+            const diagLog = [];
+            const diag = (msg) => {
+                console.error(`[mcp-openmsx] ${msg}`);
+                diagLog.push(msg);
+            };
             const safeResolve = (message) => {
                 if (!resolved) {
                     resolved = true;
@@ -33,108 +45,123 @@ export class OpenMSX {
                 }
             };
             try {
-                // Check if emulator is already running
                 if (this.process && !this.process.killed) {
-                    safeResolve(`Error: openMSX emulator instance is already running (currrent machine: ${this.lastMachine}). Close it first before launching a new one.`);
+                    safeResolve(`Error: openMSX emulator instance is already running (current machine: ${this.lastMachine}). Close it first.`);
                     return;
                 }
-                // Build command line arguments
-                const args = ['-control', 'stdio'];
-                // Add machine parameter if specified
+                this.resetIO();
+                this.commandQueue = Promise.resolve(''); // reset queue for new session
+                // Build args
+                const args = [];
+                if (!IS_WINDOWS) {
+                    args.push('-control', 'stdio');
+                }
                 if (machine) {
-                    this.lastMachine = machine; // Store last machine for future reference
+                    this.lastMachine = machine;
                     args.push('-machine', machine);
                 }
-                // Add extensions if specified
-                if (extensions && extensions.length > 0) {
-                    extensions.forEach(ext => {
-                        args.push('-ext', ext);
-                    });
+                if (extensions?.length > 0) {
+                    extensions.forEach(ext => args.push('-ext', ext));
                 }
-                // Launch openMSX with stdio control
+                diag(`platform=${process.platform} IS_WINDOWS=${IS_WINDOWS}`);
+                diag(`spawn: "${executable}" ${args.join(' ')}`);
+                // Windows: stdin+stdout ignored (GUI subsystem — pipes don't work).
+                // Linux/macOS: all three streams piped.
                 this.process = spawn(executable, args, {
-                    stdio: ['pipe', 'pipe', 'pipe']
+                    stdio: IS_WINDOWS ? ['ignore', 'ignore', 'pipe'] : ['pipe', 'pipe', 'pipe'],
+                    windowsHide: false
                 });
-                if (!this.process.stdin || !this.process.stdout || !this.process.stderr) {
+                if (IS_WINDOWS && !this.process.stderr) {
+                    safeResolve('Error: Failed to create stderr pipe');
+                    return;
+                }
+                if (!IS_WINDOWS && (!this.process.stdout || !this.process.stderr || !this.process.stdin)) {
                     safeResolve('Error: Failed to create stdio pipes');
                     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';
-                    this.process = null; // Reset process to null on failure
-                    this.isConnected = false;
-                    safeResolve(`Error: ${stderrMessage}`);
+                    this.process = null;
+                    safeResolve('Error: Failed to launch openMSX process');
                     return;
                 }
-                // Handle process events
+                diag(`process spawned PID=${this.process.pid}`);
                 this.process.on('error', (error) => {
-                    console.error('openMSX process error:', error);
-                    safeResolve(`Error: ${error.message}`);
+                    diag(`process error: code=${error.code} ${error.message}`);
+                    if (error.code === 'ENOENT') {
+                        safeResolve(`Error: openMSX executable not found: "${executable}". ` +
+                            `Set OPENMSX_EXECUTABLE to the full path. ` +
+                            `On Windows: C:\\Users\\<user>\\openMSX\\openmsx.exe or ` +
+                            `C:\\Program Files\\openMSX\\openmsx.exe; ` +
+                            `on macOS: /Applications/openMSX.app/Contents/MacOS/openmsx; ` +
+                            `on Linux: openmsx (in PATH).`);
+                    }
+                    else {
+                        safeResolve(`Error: ${error.message}`);
+                    }
                 });
                 this.process.on('exit', (code, signal) => {
+                    diag(`process exit: code=${code} signal=${signal} isConnected=${this.isConnected}`);
+                    if (!resolved) {
+                        safeResolve(`Error: openMSX process exited unexpectedly (code=${code}, signal=${signal}). ` +
+                            `Diagnostics: ${diagLog.join(' | ')}`);
+                    }
                     this.isConnected = false;
                     this.process = null;
+                    this.resetIO();
                 });
-                // Wait for the opening XML tag to confirm connection
-                this.process.stdout.on('data', (data) => {
-                    const output = data.toString();
-                    if (output.includes('<openmsx-output>')) {
-                        this.isConnected = true;
-                        connectionTime = Date.now();
-                        // Don't resolve immediately, wait for potential fatal errors
-                        setTimeout(() => {
-                            // Only resolve if no fatal error occurred during grace period
-                            if (!resolved) {
-                                try {
-                                    this.writeData('<openmsx-control>\n');
-                                    // Set save settings on exit off
-                                    this.sendCommand('set save_settings_on_exit off');
-                                    // Set renderer to SDL
-                                    this.sendCommand('set renderer SDLGL-PP');
-                                    // set machine on
-                                    this.sendCommand('set power on');
-                                    // start reverse replay mode
-                                    this.sendCommand('reverse start');
-                                    // Return success message
-                                    let result = 'Ok: openMSX emulator launched successfully';
-                                    if (machine) {
-                                        result += ` with machine "${machine}"`;
-                                    }
-                                    if (extensions && extensions.length > 0) {
-                                        if (machine) {
-                                            result += ' and';
-                                        }
-                                        result += ` with extensions: "${extensions.join('", "')}"`;
-                                    }
-                                    result += ', is powered on, and replay mode is started.';
-                                    safeResolve(result);
-                                }
-                                catch (error) {
-                                    safeResolve(`Error: Failed to send control commands - ${error instanceof Error ? error.message : 'Unknown error'}`);
-                                }
-                            }
-                        }, FATAL_ERROR_GRACE_PERIOD);
-                    }
-                });
-                // Handle stderr - check for fatal errors during grace period
                 this.process.stderr.on('data', (data) => {
-                    const errorOutput = data.toString();
-                    // Check for fatal errors before connection or during grace period
-                    const isInGracePeriod = connectionTime && (Date.now() - connectionTime) < FATAL_ERROR_GRACE_PERIOD;
-                    if (errorOutput.includes('Fatal error:') && (!this.isConnected || isInGracePeriod)) {
+                    const msg = data.toString().trim();
+                    if (!this.isConnected)
+                        diag(`stderr: ${msg.substring(0, 300)}`);
+                    if (msg.includes('Fatal error:') && !this.isConnected) {
                         this.forceClose();
-                        safeResolve(`Error: ${errorOutput.trim()}`);
-                        return;
+                        safeResolve(`Error: ${msg}`);
                     }
                 });
-                // Set timeout for connection
+                const onOpenMSXReady = async (sendControlTag) => {
+                    diag('onOpenMSXReady: sending initial commands');
+                    // On Linux/macOS: we receive <openmsx-output> first unprompted,
+                    // then we must send <openmsx-control> to start the session.
+                    // On Windows: we already sent <openmsx-control> to trigger <openmsx-output>,
+                    // so we must NOT send it again.
+                    if (sendControlTag) {
+                        this.writeData('<openmsx-control>\n');
+                    }
+                    // await each command so replies are consumed in order and don't
+                    // contaminate ioBuffer for subsequent user commands
+                    await this.sendCommand('set save_settings_on_exit off');
+                    await this.sendCommand('set renderer SDLGL-PP');
+                    await this.sendCommand('set power on');
+                    await this.sendCommand('reverse start');
+                    let result = 'Ok: openMSX emulator launched successfully';
+                    if (machine)
+                        result += ` with machine "${machine}"`;
+                    if (extensions?.length > 0) {
+                        if (machine)
+                            result += ' and';
+                        result += ` with extensions: "${extensions.join('", "')}"`;
+                    }
+                    result += ', is powered on, and replay mode is started.';
+                    safeResolve(result);
+                };
+                const ctx = {
+                    diag, safeResolve,
+                    isResolved: () => resolved,
+                    onReady: onOpenMSXReady,
+                };
+                if (IS_WINDOWS) {
+                    this.launchConnectWindows(ctx);
+                }
+                else {
+                    this.launchConnectLinux(ctx);
+                }
+                // Global timeout — 20s to allow for SSPI auth + slow VMs
                 setTimeout(() => {
                     if (!this.isConnected) {
                         this.emu_close();
-                        safeResolve('Error: Timeout waiting for openMSX to start');
+                        safeResolve(`Error: Timeout waiting for openMSX to start. Diagnostics: ${diagLog.join(' | ')}`);
                     }
-                }, 5000); // 5 second timeout
+                }, 20000);
             }
             catch (error) {
                 safeResolve(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
@@ -142,74 +169,341 @@ export class OpenMSX {
         });
     }
     /**
-     * Close the openMSX emulator process
-     * @returns Promise that resolves when the process is closed
+     * Windows connection: TCP socket + SSPI authentication.
+     * Polls for the socket file, connects, authenticates, and starts the XML session.
+     */
+    launchConnectWindows(ctx) {
+        const tmpDir = process.env.TEMP ?? process.env.TMP ??
+            path.join(os.homedir(), 'AppData', 'Local', 'Temp');
+        const socketFile = path.join(tmpDir, 'openmsx-default', `socket.${this.process.pid}`);
+        ctx.diag(`waiting for socket file: ${socketFile}`);
+        this.connectWindowsTCP(socketFile).then(async ({ socket, port }) => {
+            ctx.diag(`TCP connected on port ${port}`);
+            this.tcpSocket = socket;
+            this.ioBuffer = '';
+            socket.on('error', e => {
+                ctx.diag(`TCP socket error: ${e.message}`);
+                if (!ctx.isResolved())
+                    ctx.safeResolve(`Error: TCP socket error: ${e.message}`);
+            });
+            socket.on('close', () => {
+                ctx.diag('TCP socket closed');
+                this.tcpSocket = null;
+                this.isConnected = false;
+            });
+            // Register the main data handler BEFORE performSspiAuth.
+            // This prevents any gap where data could be discarded:
+            // performSspiAuth adds its own 'data' listener that runs in
+            // parallel — both handlers receive data, but:
+            //  - during SSPI: ioBuffer accumulates binary SSPI tokens
+            //    (harmless, won't contain '<openmsx-output>')
+            //  - after SSPI: ioBuffer is cleared, then <openmsx-control>
+            //    is sent, and <openmsx-output> is detected normally.
+            socket.on('data', (data) => {
+                const chunk = data.toString();
+                // Accumulate all incoming data
+                this.ioBuffer += chunk;
+                // Signal readData() that new data arrived (notify pattern)
+                if (this.ioNotify) {
+                    const notify = this.ioNotify;
+                    this.ioNotify = null;
+                    notify();
+                }
+                // During launch: detect <openmsx-output> in the accumulated stream
+                if (!this.isConnected && this.ioBuffer.includes('<openmsx-output>')) {
+                    this.isConnected = true;
+                    // Discard everything up to and including <openmsx-output>
+                    this.ioBuffer = this.ioBuffer.substring(this.ioBuffer.indexOf('<openmsx-output>') + '<openmsx-output>'.length);
+                    setTimeout(async () => {
+                        if (!ctx.isResolved()) {
+                            try {
+                                await ctx.onReady(false);
+                            } // Windows: don't resend <openmsx-control>
+                            catch (e) {
+                                ctx.safeResolve(`Error: Failed to send control commands - ${e instanceof Error ? e.message : e}`);
+                            }
+                        }
+                    }, 300);
+                }
+            });
+            // SSPI authentication (adds its own parallel 'data' listener internally)
+            try {
+                ctx.diag('starting SSPI authentication...');
+                await this.performSspiAuth(socket);
+                ctx.diag('SSPI authentication successful');
+            }
+            catch (e) {
+                ctx.safeResolve(`Error: SSPI authentication failed: ${e instanceof Error ? e.message : e}. ` +
+                    `Make sure 'node-expose-sspi' is installed: npm install node-expose-sspi`);
+                return;
+            }
+            // Clear SSPI binary garbage from ioBuffer before XML session
+            this.ioBuffer = '';
+            // Send <openmsx-control> to initiate the XML session.
+            // On Windows/TCP, openMSX sends <openmsx-output> in response.
+            ctx.diag('sending <openmsx-control> to start XML session');
+            socket.write('<openmsx-control>\n');
+        }).catch(err => {
+            ctx.diag(`connectWindowsTCP failed: ${err.message}`);
+            ctx.safeResolve(`Error: ${err.message}`);
+        });
+    }
+    /**
+     * Linux/macOS connection: stdio pipes.
+     * Registers stdout handler for ioBuffer accumulation and <openmsx-output> detection.
+     */
+    launchConnectLinux(ctx) {
+        const FATAL_ERROR_GRACE_PERIOD = 500;
+        let connectionTime = null;
+        this.process.stdout.on('data', (data) => {
+            const output = data.toString();
+            if (!this.isConnected) {
+                if (output.includes('<openmsx-output>')) {
+                    ctx.diag('<openmsx-output> detected on stdout');
+                    this.isConnected = true;
+                    this.ioBuffer = '';
+                    connectionTime = Date.now();
+                    setTimeout(async () => {
+                        if (!ctx.isResolved()) {
+                            try {
+                                await ctx.onReady(true);
+                            } // Linux/macOS: must send <openmsx-control>
+                            catch (e) {
+                                ctx.safeResolve(`Error: Failed to send control commands - ${e instanceof Error ? e.message : e}`);
+                            }
+                        }
+                    }, FATAL_ERROR_GRACE_PERIOD);
+                }
+            }
+            else {
+                // Accumulate for readData() — persistent shared ioBuffer
+                this.ioBuffer += output;
+                if (this.ioNotify) {
+                    const notify = this.ioNotify;
+                    this.ioNotify = null;
+                    notify();
+                }
+            }
+        });
+        this.process.stderr.on('data', (data) => {
+            const msg = data.toString().trim();
+            const isInGracePeriod = connectionTime && (Date.now() - connectionTime) < FATAL_ERROR_GRACE_PERIOD;
+            if (msg.includes('Fatal error:') && (!this.isConnected || isInGracePeriod)) {
+                this.forceClose();
+                ctx.safeResolve(`Error: ${msg}`);
+            }
+        });
+    }
+    /**
+     * SSPI (Negotiate/NTLM) authentication handshake — Windows only.
+     * Required since openMSX 0.7.1 for TCP socket connections.
+     * Uses `node-expose-sspi` v0.1.x optional npm package.
+     *
+     * Reference C++ implementation: openMSX debugger SspiNegotiateClient.cpp
+     * Protocol: loop until SEC_E_OK — each round:
+     *   client → [4-byte BE length][SSPI token]
+     *   server → [4-byte BE length][SSPI response]  (if SEC_I_CONTINUE_NEEDED)
+     * After SEC_E_OK: no server read — proceed directly with XML protocol.
      */
+    async performSspiAuth(socket) {
+        let nes;
+        try {
+            const { createRequire } = await import('module');
+            const req = createRequire(import.meta.url);
+            nes = req('node-expose-sspi');
+        }
+        catch (e) {
+            throw new Error(`node-expose-sspi not available (${e instanceof Error ? e.message : e}). ` +
+                `Install with: npm install node-expose-sspi`);
+        }
+        // Accumulate TCP data for length-prefixed reads during SSPI phase.
+        // Pattern: onSspiData appends to buffer and NOTIFIES (does not clear).
+        // readLengthPrefixed checks the buffer size after each notification.
+        let sspiBuffer = Buffer.alloc(0);
+        let sspiNotify = null;
+        const onSspiData = (chunk) => {
+            sspiBuffer = Buffer.concat([sspiBuffer, chunk]);
+            if (sspiNotify) {
+                const notify = sspiNotify;
+                sspiNotify = null;
+                notify(); // just signal — buffer stays intact
+            }
+        };
+        socket.on('data', onSspiData);
+        // Wait until new data arrives (doesn't clear the buffer)
+        const waitMore = () => new Promise(resolve => {
+            sspiNotify = resolve;
+        });
+        const readLengthPrefixed = async () => {
+            // Wait until we have at least the 4-byte length prefix
+            while (sspiBuffer.length < 4)
+                await waitMore();
+            const len = sspiBuffer.readUInt32BE(0);
+            const total = 4 + len;
+            // Wait until the full payload has arrived
+            while (sspiBuffer.length < total)
+                await waitMore();
+            const result = sspiBuffer.slice(4, total);
+            sspiBuffer = sspiBuffer.slice(total); // consume only what we read
+            return result;
+        };
+        const sendToken = (token) => {
+            const buf = Buffer.from(token);
+            const lenBuf = Buffer.alloc(4);
+            lenBuf.writeUInt32BE(buf.length, 0);
+            socket.write(lenBuf);
+            socket.write(buf);
+        };
+        try {
+            // node-expose-sspi v0.1.x API:
+            //   AcquireCredentialsHandle → CredentialWithExpiry { credential, tsExpiry }
+            //   InitializeSecurityContextInput.credential = CredHandle (the .credential property)
+            //   InitializeSecurityContextInput.SecBufferDesc = server's token (NOT serverSecurityContext)
+            //   InitializeSecurityContextInput.contextReq = string[] of ISC_REQ_* flags
+            //   Flags from openMSX C++ ref: ISC_REQ_ALLOCATE_MEMORY | ISC_REQ_CONNECTION | ISC_REQ_STREAM
+            const credWithExpiry = nes.sspi.AcquireCredentialsHandle({
+                packageName: 'Negotiate',
+                credentialUse: 'SECPKG_CRED_OUTBOUND',
+            });
+            const credential = credWithExpiry.credential;
+            const packageInfo = nes.sspi.QuerySecurityPackageInfo('Negotiate');
+            const ISC_FLAGS = ['ISC_REQ_ALLOCATE_MEMORY', 'ISC_REQ_CONNECTION', 'ISC_REQ_STREAM'];
+            let contextHandle = undefined;
+            let serverSecBufDesc = undefined;
+            // Loop until SEC_E_OK (mirrors C++ reference implementation)
+            while (true) {
+                const ctxInput = {
+                    credential,
+                    targetName: '',
+                    cbMaxToken: packageInfo.cbMaxToken,
+                    contextReq: ISC_FLAGS,
+                    targetDataRep: 'SECURITY_NETWORK_DREP',
+                };
+                if (contextHandle !== undefined)
+                    ctxInput.contextHandle = contextHandle;
+                if (serverSecBufDesc !== undefined)
+                    ctxInput.SecBufferDesc = serverSecBufDesc;
+                const clientCtx = nes.sspi.InitializeSecurityContext(ctxInput);
+                contextHandle = clientCtx.contextHandle;
+                // Send our token to the server (if non-empty)
+                const tokenBuf = clientCtx.SecBufferDesc?.buffers?.[0];
+                if (tokenBuf && tokenBuf.byteLength > 0) {
+                    sendToken(tokenBuf);
+                }
+                if (clientCtx.SECURITY_STATUS === 'SEC_E_OK') {
+                    // Auth complete — no final read from server, proceed to XML
+                    break;
+                }
+                if (clientCtx.SECURITY_STATUS !== 'SEC_I_CONTINUE_NEEDED') {
+                    throw new Error(`SSPI error: ${clientCtx.SECURITY_STATUS}`);
+                }
+                // Read server's response token
+                const response = await readLengthPrefixed();
+                const responseAB = response.buffer.slice(response.byteOffset, response.byteOffset + response.byteLength);
+                serverSecBufDesc = { ulVersion: 0, buffers: [responseAB] };
+            }
+        }
+        finally {
+            // Remove SSPI data handler — main handler will be added after this returns
+            socket.removeListener('data', onSspiData);
+        }
+    }
+    /**
+     * Poll for the TCP socket file, read the port, connect.
+     */
+    connectWindowsTCP(socketFile) {
+        return new Promise((resolve, reject) => {
+            const maxWaitMs = 8000;
+            const pollMs = 200;
+            let elapsed = 0;
+            const poll = () => {
+                if (fsSync.existsSync(socketFile)) {
+                    let port;
+                    try {
+                        port = parseInt(fsSync.readFileSync(socketFile, 'utf8').trim(), 10);
+                    }
+                    catch (e) {
+                        return reject(new Error(`Cannot read socket file: ${e}`));
+                    }
+                    if (!port || isNaN(port))
+                        return reject(new Error(`Invalid port in socket file`));
+                    const sock = net.createConnection(port, '127.0.0.1');
+                    sock.once('connect', () => resolve({ socket: sock, port }));
+                    sock.once('error', err => { sock.destroy(); reject(new Error(`TCP connect to ${port} failed: ${err.message}`)); });
+                }
+                else {
+                    elapsed += pollMs;
+                    if (elapsed >= maxWaitMs) {
+                        reject(new Error(`openMSX socket file not found after ${maxWaitMs}ms: ${socketFile}`));
+                    }
+                    else {
+                        setTimeout(poll, pollMs);
+                    }
+                }
+            };
+            poll();
+        });
+    }
+    resetIO() {
+        if (this.tcpSocket) {
+            try {
+                this.tcpSocket.destroy();
+            }
+            catch (_) { /* ignore */ }
+            this.tcpSocket = null;
+        }
+        this.ioBuffer = '';
+        this.ioNotify = null;
+    }
     async emu_close() {
         return new Promise((resolve) => {
+            let resolved = false;
+            const safeResolve = (message) => {
+                if (!resolved) {
+                    resolved = true;
+                    resolve(message);
+                }
+            };
             if (!this.process) {
-                resolve("Error: No emulator process running");
+                safeResolve("Error: No emulator process running");
                 return;
             }
             this.process.on('exit', () => {
-                this.lastMachine = null; // Clear last machine on exit
+                this.lastMachine = null;
                 this.isConnected = false;
                 this.process = null;
-                resolve("Ok: Emulator process closed successfully");
+                this.resetIO();
+                safeResolve("Ok: Emulator process closed successfully");
             });
-            this.process.on('error', (error) => {
-                resolve(`Error: error closing emulator: ${error.message}`);
-            });
-            // Try graceful shutdown first
+            this.process.on('error', (error) => safeResolve(`Error: error closing emulator: ${error.message}`));
             if (this.isConnected) {
-                try {
-                    this.sendCommand('exit');
-                }
-                catch (error) {
-                    // If writing fails, force kill.
-                    // Use no-argument kill() for cross-platform safety:
-                    // on POSIX it sends SIGTERM; on Windows it calls TerminateProcess().
+                this.sendCommand('exit').catch(() => {
                     try {
-                        this.process.kill();
+                        this.process?.kill();
                     }
                     catch (_) { /* ignore */ }
-                }
+                });
             }
             else {
                 this.forceClose();
-                resolve("Error: Emulator process had to be force killed");
+                safeResolve("Error: Emulator process had to be force killed");
             }
-            // Force kill after timeout
-            setTimeout(() => {
-                this.forceClose();
-                resolve("Error: Timeout. Emulator process had to be force killed");
-            }, 1000);
+            setTimeout(() => { this.forceClose(); safeResolve("Error: Timeout. Emulator process had to be force killed"); }, 1000);
         });
     }
-    /**
-     * Get the status of the openMSX emulator using machine_info command
-     * @returns Promise<string> - JSON string with machine information or error message
-     */
     async emu_status() {
         try {
             const response = await this.sendCommand('machine_info');
-            if (response.startsWith('Error:')) {
+            if (response.startsWith('Error:'))
                 return response;
-            }
-            // Parse machine_info output into key-value pairs
             const skipInfo = ['issubslotted', 'input_port', 'slot', 'isexternalslot', 'output_port'];
             const parameters = response.trim().split(' ');
             const machineInfo = {};
             for (const param of parameters) {
-                const trimmedLine = param.trim();
-                // Skip certain parameters that are not useful
-                if (skipInfo.includes(trimmedLine)) {
+                const trimmed = param.trim();
+                if (skipInfo.includes(trimmed) || !trimmed)
                     continue;
-                }
-                if (trimmedLine) {
-                    const value = await this.sendCommand(`machine_info ${trimmedLine}`);
-                    machineInfo[trimmedLine] = value.trim();
-                }
+                machineInfo[trimmed] = (await this.sendCommand(`machine_info ${trimmed}`)).trim();
             }
             return JSON.stringify(machineInfo, null, 2);
         }
@@ -222,151 +516,128 @@ export class OpenMSX {
             const response = await this.sendCommand('slotselect');
             return response.includes('0000: slot 0') && response.includes('4000: slot 0');
         }
-        catch (error) {
+        catch (_) {
             return false;
         }
     }
-    /**
-     * Get the list of machines available in the openMSX emulator
-     * @returns Promise<object> - object with machine names and descriptions or error message
-     */
     async getMachineList(machinesDirectory) {
-        // Read the machines directory
-        let machines = [];
-        let machinesList = "Error: No machines found.";
-        try {
-            const allFiles = await fs.readdir(machinesDirectory);
-            machines = await Promise.all(allFiles
-                .filter((file) => file.endsWith('.xml'))
-                .map(async (file) => {
-                return {
-                    name: file.replace('.xml', ''),
-                    description: await extractDescriptionFromXML(path.join(machinesDirectory, file))
-                };
-            }));
-            if (machines.length !== 0) {
-                machinesList = JSON.stringify(machines, null, 2);
-            }
-            return machinesList;
-        }
-        catch (error) {
-            return `Error: error reading machines directory - ${error instanceof Error ? error.message : error}`;
-        }
+        return this.getXMLList(machinesDirectory, 'machines');
     }
-    /**
-     * Get the list of extensions available in the openMSX emulator
-     * @returns Promise<object> - object with extension names and descriptions or error message
-     */
     async getExtensionList(extensionDirectory) {
-        // Read the extensions directory
-        let extensions = [];
-        let extensionsList = "Error: No extensions found.";
+        return this.getXMLList(extensionDirectory, 'extensions');
+    }
+    async getXMLList(directory, entityName) {
         try {
-            const allFiles = await fs.readdir(extensionDirectory);
-            extensions = await Promise.all(allFiles
-                .filter((file) => file.endsWith('.xml'))
-                .map(async (file) => {
-                return {
-                    name: file.replace('.xml', ''),
-                    description: await extractDescriptionFromXML(path.join(extensionDirectory, file))
-                };
-            }));
-            if (extensions.length !== 0) {
-                extensionsList = JSON.stringify(extensions, null, 2);
-            }
-            return extensionsList;
+            const allFiles = await fs.readdir(directory);
+            const items = await Promise.all(allFiles.filter(f => f.endsWith('.xml')).map(async (f) => ({
+                name: f.replace('.xml', ''),
+                description: await extractDescriptionFromXML(path.join(directory, f))
+            })));
+            return items.length ? JSON.stringify(items, null, 2) : `Error: No ${entityName} found.`;
         }
         catch (error) {
-            return `Error: error reading extensions directory - ${error instanceof Error ? error.message : error}`;
+            return `Error: error reading ${entityName} directory - ${error instanceof Error ? error.message : error}`;
         }
     }
-    ;
     /**
-     * Send a command to the openMSX emulator and return the response
-     * @param command - XML command to send to the emulator
-     * @returns string - resulting response from the emulator or an error message
+     * Send a TCL command to openMSX and return the response.
+     *
+     * Internally serialized via a promise queue so concurrent callers (with or
+     * without `await`) never overlap — each command waits for the previous one
+     * to complete before writing to the channel and reading the reply.
+     * This is safe on all platforms (Linux/macOS stdio and Windows TCP).
      */
     async sendCommand(command) {
-        try {
-            // Send command
-            this.writeData(`<command>${encodeHtmlEntities(command)}</command>\n`);
-            // Read response using readData()
-            const output = (await this.readData()).trim();
-            // Look for reply tags in the output
-            const replyMatch = output.match(/<reply result="(ok|nok)"[^>]*>(.*?)<\/reply>/s);
-            if (replyMatch) {
-                const outputContent = decodeHtmlEntities(replyMatch[2].trim());
-                if (replyMatch[1] === 'ok') {
-                    return outputContent;
-                }
-                else {
-                    return `Error: ${outputContent}`;
+        const execute = async () => {
+            try {
+                this.writeData(`<command>${encodeHtmlEntities(command)}</command>\n`);
+                const output = (await this.readData()).trim();
+                const replyMatch = output.match(/<reply result="(ok|nok)"[^>]*>(.*?)<\/reply>/s);
+                if (replyMatch) {
+                    const content = decodeHtmlEntities(replyMatch[2].trim());
+                    return replyMatch[1] === 'ok' ? content : `Error: ${content}`;
                 }
+                return decodeHtmlEntities(output);
             }
-            // Return raw output with HTML entities decoded
-            return decodeHtmlEntities(output.trim());
-        }
-        catch (error) {
-            return `Error: ${error instanceof Error ? error.message : error}`;
-        }
+            catch (error) {
+                return `Error: ${error instanceof Error ? error.message : error}`;
+            }
+        };
+        // Chain onto the queue: wait for the previous command to finish, then run
+        const result = this.commandQueue.then(execute, execute);
+        // Update the queue tail — swallow errors so the chain never breaks
+        this.commandQueue = result.then(() => '', () => '');
+        return result;
     }
-    /**
-     * Write data to the openMSX process stdin
-     * @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');
+        if (IS_WINDOWS) {
+            if (!this.tcpSocket || this.tcpSocket.destroyed)
+                throw new Error('Windows TCP socket not open');
+            this.tcpSocket.write(data);
+        }
+        else {
+            if (!this.process.stdin)
+                throw new Error('openMSX stdin not available');
+            this.process.stdin.write(data);
         }
-        this.process.stdin.write(data);
     }
-    /**
-     * Read data from openMSX process stdout
-     * @returns Promise<string> - The data received from stdout
-     */
     readData() {
         return new Promise((resolve, reject) => {
-            if (!this.process || !this.process.stdout || !this.isConnected) {
+            if (!this.isConnected) {
                 reject(new Error('openMSX process not running or not connected'));
                 return;
             }
-            const onData = (data) => {
-                this.process.stdout.removeListener('data', onData);
-                resolve(data.toString());
+            if (IS_WINDOWS) {
+                if (!this.tcpSocket || this.tcpSocket.destroyed) {
+                    reject(new Error('Windows TCP socket not open'));
+                    return;
+                }
+            }
+            else {
+                if (!this.process?.stdout) {
+                    reject(new Error('openMSX stdout not available'));
+                    return;
+                }
+            }
+            // Unified for both platforms: accumulate in ioBuffer until a complete
+            // <reply>…</reply> block, then extract and return it.
+            const RESPONSE_TIMEOUT = 10000;
+            const timer = setTimeout(() => {
+                this.ioNotify = null;
+                this.ioBuffer = '';
+                reject(new Error('Timeout waiting for openMSX response'));
+            }, RESPONSE_TIMEOUT);
+            const tryExtractReply = () => {
+                const end = this.ioBuffer.indexOf('</reply>');
+                if (end !== -1) {
+                    clearTimeout(timer);
+                    const full = this.ioBuffer.substring(0, end + '</reply>'.length);
+                    this.ioBuffer = this.ioBuffer.substring(end + '</reply>'.length);
+                    resolve(full);
+                }
+                else {
+                    this.ioNotify = tryExtractReply;
+                }
             };
-            this.process.stdout.on('data', onData);
+            tryExtractReply();
         });
     }
-    /**
-     * Destructor - Clean up resources and close emulator if running
-     * This method should be called when the instance is no longer needed
-     */
     async destroy() {
-        if (this.process && !this.process.killed) {
+        if (this.process && !this.process.killed)
             await this.emu_close();
-        }
     }
-    /**
-     * Force close the emulator immediately (synchronous)
-     * Used for emergency shutdown when async methods may not work
-     */
     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) {
-                // Ignore errors during force close
-            }
+            catch (_) { /* ignore */ }
             this.process = null;
             this.isConnected = false;
         }
+        this.resetIO();
     }
 }
-/**
- * Global instance of OpenMSX for emulator control
- */
 export const openMSXInstance = new OpenMSX();

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: '',
@@ -232,6 +230,15 @@ async function main() {
     }
     emuDirectories.MACHINES_DIR = path.join(emuDirectories.OPENMSX_SHARE_DIR, 'machines');
     emuDirectories.EXTENSIONS_DIR = path.join(emuDirectories.OPENMSX_SHARE_DIR, 'extensions');
+    if (!emuDirectories.OPENMSX_SCREENSHOT_DIR) {
+        emuDirectories.OPENMSX_SCREENSHOT_DIR = path.join(emuDirectories.OPENMSX_SHARE_DIR, 'screenshots');
+    }
+    if (!emuDirectories.OPENMSX_SCREENDUMP_DIR) {
+        emuDirectories.OPENMSX_SCREENDUMP_DIR = path.join(emuDirectories.OPENMSX_SHARE_DIR, 'screenshots');
+    }
+    if (!emuDirectories.OPENMSX_REPLAYS_DIR) {
+        emuDirectories.OPENMSX_REPLAYS_DIR = path.join(emuDirectories.OPENMSX_SHARE_DIR, 'replays');
+    }
     VectorDB.setIndexDirectory(vectorDbDir);
     // Detect transport type from environment or command line
     const transportType = process.env.MCP_TRANSPORT || process.argv[2] || 'stdio';

package/dist/server_tools.js

@@ -3,7 +3,7 @@ import fs from "fs/promises";
 import path from "path";
 import { openMSXInstance } from "./openmsx.js";
 import { VectorDB } from "./vectordb.js";
-import { encodeTypeText, buildKeyComboCommand, isErrorResponse, getResponseContent, parseCpuRegs, is16bitRegister, parseVdpRegs, parsePalette, parseBreakpoints, parseReplayStatus, sleepWithAbort } from "./utils.js";
+import { encodeTypeText, buildKeyComboCommand, isErrorResponse, getResponseContent, parseCpuRegs, is16bitRegister, parseVdpRegs, parsePalette, parseBreakpoints, parseReplayStatus, sleepWithAbort, ensureDirectoryExists, tclPath } from "./utils.js";
 import { getRegisteredResourcesList } from "./server_resources.js";
 import { resolveLaunchParams } from "./server_elicitations.js";
 // ============================================================================
@@ -1246,13 +1246,19 @@ export async function registerTools(server, emuDirectories) {
                 tclCommand = `reverse_frame ${frames}`;
                 break;
             case "saveReplay":
-                if (filename)
-                    filename = path.join(emuDirectories.OPENMSX_REPLAYS_DIR, filename);
+                if (filename) {
+                    if (!filename.endsWith('.omr'))
+                        filename += '.omr';
+                    filename = tclPath(path.join(emuDirectories.OPENMSX_REPLAYS_DIR, filename));
+                }
                 tclCommand = `reverse savereplay ${filename || ''}`;
                 break;
             case "loadReplay":
-                if (filename)
-                    filename = path.join(emuDirectories.OPENMSX_REPLAYS_DIR, filename);
+                if (filename) {
+                    if (!filename.endsWith('.omr'))
+                        filename += '.omr';
+                    filename = tclPath(path.join(emuDirectories.OPENMSX_REPLAYS_DIR, filename));
+                }
                 tclCommand = `reverse loadreplay ${filename}`;
                 break;
             default:
@@ -1394,20 +1400,46 @@ export async function registerTools(server, emuDirectories) {
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command }) => {
-        const openmsxCommand = `screenshot -raw -doublesize -prefix "${path.join(emuDirectories.OPENMSX_SCREENSHOT_DIR, 'mcp_')}"`;
+        // Ensure the screenshot directory exists before saving
+        const screenshotDirError = await ensureDirectoryExists(emuDirectories.OPENMSX_SCREENSHOT_DIR);
+        if (screenshotDirError) {
+            return getResponseContent([`Error: ${screenshotDirError}`], true);
+        }
+        // Use a unique prefix so we can locate the file even if openMSX
+        // doesn't return the filename (some versions return empty on success).
+        const uniqueId = `mcp_${Date.now()}_`;
+        const screenshotPrefix = tclPath(path.join(emuDirectories.OPENMSX_SCREENSHOT_DIR, uniqueId));
+        const openmsxCommand = `screenshot -raw -doublesize -prefix "${screenshotPrefix}"`;
         const response = await openMSXInstance.sendCommand(openmsxCommand);
+        if (isErrorResponse(response)) {
+            return getResponseContent([response], true);
+        }
+        // Resolve the screenshot file path: use the response if it contains
+        // a valid path, otherwise scan the directory for the generated file.
+        let screenshotPath = response;
+        if (!screenshotPath || !screenshotPath.endsWith('.png')) {
+            try {
+                const files = await fs.readdir(emuDirectories.OPENMSX_SCREENSHOT_DIR);
+                const match = files.find(f => f.startsWith(uniqueId) && f.endsWith('.png'));
+                if (match) {
+                    screenshotPath = path.join(emuDirectories.OPENMSX_SCREENSHOT_DIR, match);
+                }
+            }
+            catch (_) { /* directory read failed, screenshotPath stays empty */ }
+        }
+        if (!screenshotPath || !screenshotPath.endsWith('.png')) {
+            return getResponseContent([
+                `Error: Screenshot command succeeded but no file was found (prefix: "${uniqueId}")`,
+            ], true);
+        }
         switch (command) {
             case "as_image":
                 try {
-                    // Check if the response is a file path
-                    if (!response || !response.startsWith(emuDirectories.OPENMSX_SCREENSHOT_DIR) || !response.endsWith('.png')) {
-                        throw new Error(`Invalid screenshot "${response}"`);
-                    }
                     // Read the screenshot file
-                    const imageBuffer = await fs.readFile(response);
+                    const imageBuffer = await fs.readFile(screenshotPath);
                     const base64image = imageBuffer.toString('base64');
                     // Remove the file after reading it
-                    await fs.unlink(response);
+                    await fs.unlink(screenshotPath);
                     // Return the image in the response
                     return {
                         content: [{
@@ -1422,13 +1454,13 @@ export async function registerTools(server, emuDirectories) {
                 }
                 catch (error) {
                     return getResponseContent([
-                        'Error creating screenshot: ' + response,
+                        'Error reading screenshot file: ' + screenshotPath,
                         error instanceof Error ? error.message : String(error),
                     ], true);
                 }
             case "to_file":
                 return getResponseContent([
-                    isErrorResponse(response) ? response : 'Screenshot taken in file: ' + response
+                    'Screenshot taken in file: ' + screenshotPath
                 ]);
         }
         return getResponseContent([
@@ -1461,7 +1493,12 @@ The parameter scrbasename is the name of the filename (without path) to save the
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ scrbasename }) => {
-        const openmsxCommand = `save_msx_screen "${path.join(emuDirectories.OPENMSX_SCREENDUMP_DIR, scrbasename)}"`;
+        // Ensure the screendump directory exists before saving
+        const screendumpDirError = await ensureDirectoryExists(emuDirectories.OPENMSX_SCREENDUMP_DIR);
+        if (screendumpDirError) {
+            return getResponseContent([`Error: ${screendumpDirError}`], true);
+        }
+        const openmsxCommand = `save_msx_screen "${tclPath(path.join(emuDirectories.OPENMSX_SCREENDUMP_DIR, scrbasename))}"`;
         const response = await openMSXInstance.sendCommand(openmsxCommand);
         return getResponseContent([
             isErrorResponse(response) ? 'Fail:' : 'Screendump file saved as:',

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
@@ -24,9 +50,13 @@ export function detectOpenMSXShareDir() {
             path.join(os.homedir(), '.openMSX', 'share'),
             '/usr/local/share/openmsx',
             '/usr/share/openmsx',
-            // Windows paths
+            // Windows paths (appdata, documents, program files, portable)
+            ...(process.env.APPDATA ? [path.join(process.env.APPDATA, 'openMSX', 'share')] : []),
+            ...(process.env.LOCALAPPDATA ? [path.join(process.env.LOCALAPPDATA, 'openMSX', 'share')] : []),
             path.join(os.homedir(), 'Documents', 'openMSX', 'share'),
+            path.join(os.homedir(), 'openMSX', 'share'),
             path.join(process.env.PROGRAMFILES || 'C:\\Program Files', 'openMSX', 'share'),
+            ...(process.env['PROGRAMFILES(X86)'] ? [path.join(process.env['PROGRAMFILES(X86)'], 'openMSX', 'share')] : []),
             // macOS paths
             path.join(os.homedir(), 'Library', 'Application Support', 'openMSX', 'share'),
             '/Applications/openMSX.app/Contents/Resources/share',
@@ -466,6 +496,31 @@ export function parseReplayStatus(response) {
         snapshotCount,
     };
 }
+/**
+ * Ensure a directory exists, creating it (and any parents) if necessary.
+ * @param dirPath - Absolute path to the directory
+ * @returns null on success, or an error message string if creation failed
+ */
+export async function ensureDirectoryExists(dirPath) {
+    try {
+        await fs.mkdir(dirPath, { recursive: true });
+        return null;
+    }
+    catch (error) {
+        return `Cannot create directory "${dirPath}": ` +
+            (error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Normalize a file path for use inside openMSX TCL commands.
+ * Converts Windows backslashes to forward slashes, which TCL accepts on all platforms.
+ * On Linux/macOS this is a no-op (no backslashes to replace).
+ * @param filePath - File path to normalize
+ * @returns Path with forward slashes only
+ */
+export function tclPath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
 /*
  * Sleep for a specified number of milliseconds
  * @param ms - Number of milliseconds to sleep

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",
@@ -30,13 +30,22 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsc && shx chmod +x dist/server.js",
-    "watch": "tsc --watch",
+    "build": "node_modules/.bin/tsc && shx chmod +x dist/server.js",
+    "watch": "node_modules/.bin/tsc --watch",
     "start": "node dist/server.js",
     "dev": "tsx src/server.ts",
     "prepublishOnly": "npm run build",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
+  "optionalDependencies": {
+    "node-expose-sspi": "^0.1.60",
+    "sharp": ">=0.32.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "sharp": "$sharp"
+    }
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@themaximalist/embeddings.js": "^0.1.3",