@nataliapc/mcp-openmsx 1.2.9 → 1.2.10

package/README.md

@@ -249,6 +249,27 @@ Edit it to include the following JSON entry:
 | `MCP_TRANSPORT` | Transport mode (`stdio` or `http`) | `stdio` | `http` |
 | `MCP_HTTP_PORT` | Port number for HTTP transport mode | `3000` | `8080` |
 | `MCP_ALLOWED_ORIGINS` | Comma-separated list of allowed origins for HTTP transport | Empty for all allowed | `http://localhost,http://mydomain.com` |
+| `OPENMSX_WINDOWS_CONTROL` | **Windows only.** How the server talks to openMSX's control socket (see below) | `stdio-proxy` | `direct-sspi` |
+| `OPENMSX_WINDOWS_PROXY_EXECUTABLE` | **Windows only.** Override path to the SSPI proxy helper (development) | Bundled `bin/win-x64/mcp-openmsx-sspi-proxy.exe` | `C:\path\to\mcp-openmsx-sspi-proxy.exe` |
+
+#### Windows control modes (`OPENMSX_WINDOWS_CONTROL`)
+
+On Windows, openMSX is a GUI app whose TCP control socket requires SSPI (Negotiate/NTLM) authentication. The server supports several transports:
+
+| Value | Description |
+|-------|-------------|
+| `stdio-proxy` | **Default.** Launches a self-contained .NET helper that performs SSPI and exposes a clean XML stdio channel — the most robust path. |
+| `direct-sspi` | Authenticates from Node via the optional `node-expose-sspi` package. Fallback / debugging. |
+| `socket` | Legacy alias of `direct-sspi`. |
+
+Linux and macOS are unaffected (`openmsx -control stdio`).
+
+The bundled proxy is built from `helpers/openmsx-sspi-proxy` and can be rebuilt reproducibly from Linux with Docker (no local .NET required):
+
+```bash
+cd mcp-server
+pnpm build:proxy:win-x64:docker   # → bin/win-x64/mcp-openmsx-sspi-proxy.exe
+```
 
 
 ## Advanced Manual Usage

package/dist/openmsx.js

@@ -5,21 +5,23 @@
  * @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';
+import { OpenMsxWindowsConnector } from "./openmsx_windows.js";
 /** 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)
+    // Active writable control channel: process.stdin (Linux/macOS) or the
+    // Windows connection's input (TCP socket / SSPI proxy stdin).
+    controlWritable = null;
+    // Windows-only control connection (TCP+SSPI or stdio proxy). Owns the
+    // transport and its teardown; null on Linux/macOS. See openmsx_windows.ts.
+    controlConnection = null;
+    // Accumulated I/O data for readData() — shared by all transports (never coexist)
     ioBuffer = '';
     // Notify callback: fired when new I/O data arrives — shared by both platforms
     ioNotify = null;
@@ -51,6 +53,23 @@ export class OpenMSX {
                 }
                 this.resetIO();
                 this.commandQueue = Promise.resolve(''); // reset queue for new session
+                // Resolve the Windows control mode up front so an invalid value
+                // fails before we spawn openMSX (avoids orphaned GUI processes).
+                let windowsMode = null;
+                if (IS_WINDOWS) {
+                    try {
+                        windowsMode = OpenMsxWindowsConnector.getControlMode();
+                    }
+                    catch (e) {
+                        safeResolve(`Error: ${e instanceof Error ? e.message : e}`);
+                        return;
+                    }
+                    if (windowsMode === 'pipe') {
+                        safeResolve('Error: OPENMSX_WINDOWS_CONTROL=pipe is reserved but not implemented yet');
+                        return;
+                    }
+                    diag(`Windows control mode: ${windowsMode}`);
+                }
                 // Build args
                 const args = [];
                 if (!IS_WINDOWS) {
@@ -169,85 +188,88 @@ export class OpenMSX {
         });
     }
     /**
-     * Windows connection: TCP socket + SSPI authentication.
-     * Polls for the socket file, connects, authenticates, and starts the XML session.
+     * Windows connection (both modes). All transport — socket-file polling, TCP
+     * connect, SSPI, or proxy launch — is delegated to {@link OpenMsxWindowsConnector},
+     * which returns a uniform connection with SSPI already done. Here we only
+     * attach the generic XML stream handlers and open the session. Both Windows
+     * modes use the TCP semantics: we send `<openmsx-control>` and openMSX replies
+     * with `<openmsx-output>`.
      */
     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;
+        const connector = new OpenMsxWindowsConnector({
+            openmsxProcess: this.process,
+            diag: ctx.diag,
+        });
+        connector.connect().then((connection) => {
+            this.controlConnection = connection;
+            this.controlWritable = connection.input;
             this.ioBuffer = '';
-            socket.on('error', e => {
+            // Diagnostics from the SSPI proxy (stderr only — never stdout).
+            connection.errorOutput?.on('data', (data) => {
+                const msg = data.toString().trim();
+                if (msg && !this.isConnected)
+                    ctx.diag(`control stderr: ${msg.substring(0, 300)}`);
+            });
+            // stdio-proxy: proxy exiting before we connect means SSPI/connect failed.
+            connection.controlProcess?.on('exit', (code, signal) => {
+                ctx.diag(`control process exit: code=${code} signal=${signal} isConnected=${this.isConnected}`);
+                if (!this.isConnected && !ctx.isResolved()) {
+                    ctx.safeResolve(`Error: control process exited before connecting (code=${code}, signal=${signal}).`);
+                }
+            });
+            // direct-sspi: TCP socket errors / close.
+            connection.tcpSocket?.on('error', e => {
                 ctx.diag(`TCP socket error: ${e.message}`);
                 if (!ctx.isResolved())
                     ctx.safeResolve(`Error: TCP socket error: ${e.message}`);
             });
-            socket.on('close', () => {
+            connection.tcpSocket?.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.
+            connection.output.on('error', (e) => ctx.diag(`control stream error: ${e.message}`));
+            this.attachOutputHandler(connection.output, ctx);
+            // Open the XML session: we send <openmsx-control>; openMSX replies with
+            // <openmsx-output>. (In stdio-proxy the proxy forwards it after SSPI.)
             ctx.diag('sending <openmsx-control> to start XML session');
-            socket.write('<openmsx-control>\n');
-        }).catch(err => {
-            ctx.diag(`connectWindowsTCP failed: ${err.message}`);
+            connection.input.write('<openmsx-control>\n');
+        }).catch((err) => {
+            ctx.diag(`windows connect failed: ${err.message}`);
             ctx.safeResolve(`Error: ${err.message}`);
         });
     }
+    /**
+     * Shared output handler for both Windows modes (proxy stdout or TCP socket):
+     * accumulate into `ioBuffer`, wake any pending `readData()`, and on the first
+     * `<openmsx-output>` mark connected and trigger the initial command sequence
+     * with `onReady(false)` (we already sent `<openmsx-control>`). Linux/macOS uses
+     * its own variant in {@link launchConnectLinux} (openMSX emits the tag unprompted).
+     */
+    attachOutputHandler(output, ctx) {
+        output.on('data', (data) => {
+            const chunk = data.toString();
+            this.ioBuffer += chunk;
+            if (this.ioNotify) {
+                const notify = this.ioNotify;
+                this.ioNotify = null;
+                notify();
+            }
+            if (!this.isConnected && this.ioBuffer.includes('<openmsx-output>')) {
+                this.isConnected = true;
+                this.ioBuffer = this.ioBuffer.substring(this.ioBuffer.indexOf('<openmsx-output>') + '<openmsx-output>'.length);
+                setTimeout(async () => {
+                    if (!ctx.isResolved()) {
+                        try {
+                            await ctx.onReady(false);
+                        } // <openmsx-control> already sent
+                        catch (e) {
+                            ctx.safeResolve(`Error: Failed to send control commands - ${e instanceof Error ? e.message : e}`);
+                        }
+                    }
+                }, 300);
+            }
+        });
+    }
     /**
      * Linux/macOS connection: stdio pipes.
      * Registers stdout handler for ioBuffer accumulation and <openmsx-output> detection.
@@ -255,6 +277,7 @@ export class OpenMSX {
     launchConnectLinux(ctx) {
         const FATAL_ERROR_GRACE_PERIOD = 500;
         let connectionTime = null;
+        this.controlWritable = this.process.stdin;
         this.process.stdout.on('data', (data) => {
             const output = data.toString();
             if (!this.isConnected) {
@@ -294,164 +317,17 @@ export class OpenMSX {
             }
         });
     }
-    /**
-     * 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) {
+        // Tear down the Windows control connection (TCP socket / SSPI proxy).
+        // No-op on Linux/macOS where controlConnection is null.
+        if (this.controlConnection) {
             try {
-                this.tcpSocket.destroy();
+                this.controlConnection.forceClose();
             }
             catch (_) { /* ignore */ }
-            this.tcpSocket = null;
+            this.controlConnection = null;
         }
+        this.controlWritable = null;
         this.ioBuffer = '';
         this.ioNotify = null;
     }
@@ -472,6 +348,7 @@ export class OpenMSX {
                 this.lastMachine = null;
                 this.isConnected = false;
                 this.process = null;
+                // resetIO() also tears down the Windows control connection (proxy/socket).
                 this.resetIO();
                 safeResolve("Ok: Emulator process closed successfully");
             });
@@ -572,16 +449,10 @@ export class OpenMSX {
     writeData(data) {
         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);
-        }
+        const channel = this.controlWritable;
+        if (!channel || channel.destroyed)
+            throw new Error('openMSX control channel not available');
+        channel.write(data);
     }
     readData() {
         return new Promise((resolve, reject) => {
@@ -589,19 +460,11 @@ export class OpenMSX {
                 reject(new Error('openMSX process not running or not connected'));
                 return;
             }
-            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;
-                }
+            if (!this.controlWritable) {
+                reject(new Error('openMSX control channel not available'));
+                return;
             }
-            // Unified for both platforms: accumulate in ioBuffer until a complete
+            // Unified for all transports: accumulate in ioBuffer until a complete
             // <reply>…</reply> block, then extract and return it.
             const RESPONSE_TIMEOUT = 10000;
             const timer = setTimeout(() => {
@@ -629,14 +492,16 @@ export class OpenMSX {
             await this.emu_close();
     }
     forceClose() {
+        // Kill the openMSX emulator; resetIO() force-closes the control connection
+        // (TCP socket / SSPI proxy) on Windows.
         if (this.process && !this.process.killed) {
             try {
                 this.process.kill('SIGKILL');
             }
             catch (_) { /* ignore */ }
-            this.process = null;
-            this.isConnected = false;
         }
+        this.process = null;
+        this.isConnected = false;
         this.resetIO();
     }
 }

package/dist/openmsx_windows.js

@@ -0,0 +1,316 @@
+/**
+ * Windows control-channel connector for openMSX.
+ *
+ * On Windows, openMSX is a /SUBSYSTEM:WINDOWS GUI app whose stdin/stdout cannot
+ * be piped, and its TCP control socket requires SSPI (Negotiate/NTLM) auth since
+ * openMSX 0.7.1. This module owns ALL Windows-specific transport details (mode
+ * selection, socket-file polling, TCP connect, SSPI handshake, proxy launch) so
+ * that `openmsx.ts` keeps only platform-agnostic orchestration: it consumes the
+ * returned {@link WindowsControlConnection} and attaches the same generic XML
+ * stream handlers it uses on Linux/macOS.
+ *
+ * Modes (env var `OPENMSX_WINDOWS_CONTROL`):
+ *   - `stdio-proxy` (default): launch the bundled .NET helper
+ *     `bin/win-x64/mcp-openmsx-sspi-proxy.exe <port>` which does SSPI and exposes
+ *     a clean XML stdio channel, exactly like `openmsx -control stdio` on Linux.
+ *   - `direct-sspi`: Node opens the TCP socket and authenticates with
+ *     `node-expose-sspi`. Fallback path.
+ *   - `socket`: alias of `direct-sspi`.
+ *   - `pipe`: reserved/not implemented.
+ *
+ * @author Natalia Pujol Cremades (@nataliapc)
+ * @license GPL2
+ */
+import fsSync from 'fs';
+import net from 'net';
+import os from 'os';
+import path from 'path';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { sleep } from './utils.js';
+/** Directory of this module (works under both `src/` (tsx) and `dist/`). */
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+/** Resolve the Windows temp directory openMSX writes its socket file into. */
+function windowsTempDir(env) {
+    return env.TEMP ?? env.TMP ?? path.join(os.homedir(), 'AppData', 'Local', 'Temp');
+}
+export class OpenMsxWindowsConnector {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    get env() {
+        return this.options.env ?? process.env;
+    }
+    /**
+     * Resolve the requested Windows control mode from `OPENMSX_WINDOWS_CONTROL`.
+     * Defaults to `stdio-proxy`. `socket` is a legacy alias of `direct-sspi`.
+     * Throws on an unrecognised value.
+     */
+    static getControlMode(env = process.env) {
+        const raw = env.OPENMSX_WINDOWS_CONTROL?.trim().toLowerCase() || 'stdio-proxy';
+        if (raw === 'socket')
+            return 'direct-sspi';
+        if (raw === 'stdio-proxy' || raw === 'direct-sspi' || raw === 'pipe')
+            return raw;
+        throw new Error(`Invalid OPENMSX_WINDOWS_CONTROL="${raw}". ` +
+            `Supported values: stdio-proxy, direct-sspi, socket, pipe.`);
+    }
+    /**
+     * Resolve the path to the SSPI proxy executable.
+     * Honours `OPENMSX_WINDOWS_PROXY_EXECUTABLE` for development overrides,
+     * otherwise points at the bundled `bin/win-x64/mcp-openmsx-sspi-proxy.exe`
+     * relative to this module (i.e. `../bin/win-x64/...` from `dist/`).
+     */
+    static resolveProxyExecutable(env = process.env) {
+        const override = env.OPENMSX_WINDOWS_PROXY_EXECUTABLE?.trim();
+        if (override)
+            return override;
+        return path.resolve(MODULE_DIR, '..', 'bin', 'win-x64', 'mcp-openmsx-sspi-proxy.exe');
+    }
+    /**
+     * Poll for openMSX's socket file and return the TCP control port it contains.
+     * The file appears at `%TEMP%\openmsx-default\socket.<pid>` and holds a port
+     * number (9938-9958).
+     */
+    async waitForWindowsSocketPort(socketFile, maxWaitMs = 8000, pollMs = 200) {
+        let elapsed = 0;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            if (fsSync.existsSync(socketFile)) {
+                let raw;
+                try {
+                    raw = fsSync.readFileSync(socketFile, 'utf8').trim();
+                }
+                catch (e) {
+                    throw new Error(`Cannot read openMSX socket file: ${e instanceof Error ? e.message : e}`);
+                }
+                const port = parseInt(raw, 10);
+                if (!port || isNaN(port)) {
+                    throw new Error(`Invalid port in openMSX socket file: "${raw}"`);
+                }
+                return port;
+            }
+            elapsed += pollMs;
+            if (elapsed >= maxWaitMs) {
+                throw new Error(`openMSX socket file not found after ${maxWaitMs}ms: ${socketFile}`);
+            }
+            await sleep(pollMs);
+        }
+    }
+    /**
+     * Establish the Windows control channel for the configured mode and return a
+     * uniform connection. SSPI is fully completed before returning: for
+     * `direct-sspi` here in Node; for `stdio-proxy` inside the .NET helper. The
+     * caller only has to attach generic XML stream handlers and send
+     * `<openmsx-control>`.
+     */
+    async connect() {
+        const mode = OpenMsxWindowsConnector.getControlMode(this.env);
+        if (mode === 'pipe') {
+            throw new Error('OPENMSX_WINDOWS_CONTROL=pipe is reserved but not implemented yet');
+        }
+        const pid = this.options.openmsxProcess.pid;
+        if (!pid)
+            throw new Error('openMSX process has no pid');
+        const socketFile = path.join(windowsTempDir(this.env), 'openmsx-default', `socket.${pid}`);
+        this.options.diag(`waiting for openMSX socket file: ${socketFile}`);
+        const port = await this.waitForWindowsSocketPort(socketFile);
+        this.options.diag(`openMSX control port: ${port}`);
+        return mode === 'stdio-proxy'
+            ? this.connectStdioProxy(port)
+            : this.connectDirectSspi(port);
+    }
+    /**
+     * `stdio-proxy`: launch the bundled .NET helper (it connects to openMSX, does
+     * SSPI and pipes raw XML over its stdio). SSPI never touches Node.
+     */
+    connectStdioProxy(port) {
+        const proxyExe = OpenMsxWindowsConnector.resolveProxyExecutable(this.env);
+        if (!fsSync.existsSync(proxyExe)) {
+            throw new Error(`SSPI proxy executable not found: ${proxyExe}. ` +
+                `Build it with: pnpm build:proxy:win-x64:docker ` +
+                `(or set OPENMSX_WINDOWS_PROXY_EXECUTABLE to a built proxy).`);
+        }
+        this.options.diag(`launching SSPI proxy: "${proxyExe}" ${port}`);
+        const proxy = spawn(proxyExe, [String(port)], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        if (!proxy.stdin || !proxy.stdout || !proxy.stderr) {
+            throw new Error('Failed to create SSPI proxy stdio pipes');
+        }
+        return {
+            mode: 'stdio-proxy',
+            controlProcess: proxy,
+            input: proxy.stdin,
+            output: proxy.stdout,
+            errorOutput: proxy.stderr,
+            close: () => { try {
+                proxy.stdin?.end();
+            }
+            catch { /* ignore */ } },
+            forceClose: () => { try {
+                if (!proxy.killed)
+                    proxy.kill('SIGKILL');
+            }
+            catch { /* ignore */ } },
+        };
+    }
+    /**
+     * `direct-sspi`: open the TCP socket and authenticate from Node with
+     * `node-expose-sspi`. The returned socket is a Duplex used for both XML
+     * directions.
+     */
+    async connectDirectSspi(port) {
+        const socket = await this.tcpConnect(port);
+        this.options.diag('starting SSPI authentication...');
+        await this.performSspiAuth(socket);
+        this.options.diag('SSPI authentication successful');
+        return {
+            mode: 'direct-sspi',
+            controlProcess: null,
+            tcpSocket: socket,
+            input: socket,
+            output: socket,
+            close: () => { try {
+                socket.end();
+            }
+            catch { /* ignore */ } },
+            forceClose: () => { try {
+                socket.destroy();
+            }
+            catch { /* ignore */ } },
+        };
+    }
+    /** Open a TCP connection to openMSX's loopback control port. */
+    tcpConnect(port) {
+        return new Promise((resolve, reject) => {
+            const socket = net.createConnection(port, '127.0.0.1');
+            socket.once('connect', () => resolve(socket));
+            socket.once('error', err => {
+                socket.destroy();
+                reject(new Error(`TCP connect to ${port} failed: ${err.message}`));
+            });
+        });
+    }
+    /**
+     * SSPI (Negotiate/NTLM) authentication handshake — Windows only.
+     * Required since openMSX 0.7.1 for TCP socket connections.
+     * Uses the optional `node-expose-sspi` v0.1.x 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 — the XML protocol begins.
+     *
+     * The socket is paused before returning so any data openMSX sends after auth
+     * buffers until the caller attaches its own `data` handler (no data is lost).
+     */
+    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.subarray(4, total);
+            sspiBuffer = sspiBuffer.subarray(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 the SSPI data listener and pause the socket so any post-auth
+            // bytes buffer until the caller attaches its own 'data' handler.
+            socket.removeListener('data', onSspiData);
+            socket.pause();
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",
@@ -30,22 +30,23 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "node_modules/.bin/tsc && shx chmod +x dist/server.js",
-    "watch": "node_modules/.bin/tsc --watch",
+    "build": "shx rm -rf dist && tsc && shx chmod +x dist/server.js",
+    "watch": "tsc --watch",
     "start": "node dist/server.js",
     "dev": "tsx src/server.ts",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "build:proxy:win-x64": "dotnet publish helpers/openmsx-sspi-proxy/OpenMsxSspiProxy.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:PublishTrimmed=true -p:TrimMode=partial -p:EnableCompressionInSingleFile=true -o bin/win-x64",
+    "build:proxy:win-x64:docker": "docker run --rm --user $(id -u):$(id -g) -e HOME=/tmp -e DOTNET_CLI_HOME=/tmp -v \"$PWD\":/work -w /work mcr.microsoft.com/dotnet/sdk:8.0 dotnet publish helpers/openmsx-sspi-proxy/OpenMsxSspiProxy.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:PublishTrimmed=true -p:TrimMode=partial -p:EnableCompressionInSingleFile=true -o bin/win-x64",
+    "build:all": "pnpm build && pnpm build:proxy:win-x64:docker"
   },
   "optionalDependencies": {
     "node-expose-sspi": "^0.1.60"
   },
-  "pnpm": {
-    "overrides": {
-      "sharp": "$sharp"
-    }
+  "overrides": {
+    "sharp": "^0.34.5"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
@@ -56,25 +57,26 @@
     "debug": "^4.4.3",
     "express": "^5.2.1",
     "mime-types": "^3.0.2",
-    "sanitize-html": "^2.17.0",
+    "sanitize-html": "^2.17.4",
     "sharp": "^0.34.5",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.0",
     "vectra": "^0.11.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@modelcontextprotocol/inspector": "^0.20.0",
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.7.0",
     "@types/sanitize-html": "^2.16.0",
-    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/coverage-v8": "^4.1.6",
     "shx": "^0.4.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.6"
   },
   "files": [
     "dist/**/*",
     "resources/**/*",
     "vector-db/**/*",
+    "bin/win-x64/**/*",
     "README.md",
     "LICENSE"
   ],