@nataliapc/mcp-openmsx 1.2.4 → 1.2.6

package/README.md

@@ -1,6 +1,6 @@
 # MCP-openMSX
 
-*"Orchestrating a binary opera where AI conducts, MCP interprets, and openMSX acts as the 8-bit diva."*
+_"Orchestrating a binary opera where AI conducts, MCP interprets, and openMSX acts as the 8-bit diva."_
 
 [![Built by NataliaPC](https://img.shields.io/badge/Built%20by-NataliaPC-blue)](https://github.com/nataliapc)
 [![License](https://img.shields.io/badge/License-GPL2-blue.svg)](https://github.com/nataliapc/mcp-openmsx/blob/main/LICENSE)
@@ -13,13 +13,18 @@ A [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) s
 
 This server provides comprehensive tools for MSX software development, testing, and automation through standardized MCP protocols.
 
+
+> 🎁🎁 _If you find this project useful, please consider making a donation: [PAYPAL Link](https://www.paypal.com/donate/?hosted_button_id=9X268YDDS9SYC)_
+
+---
+
 ## Table of Contents
 
 - [Project overview](#project-overview)
 - [Architecture](#architecture)
 - [Available MCP Tools](#available-mcp-tools)
 - [Available MCP Resources](#available-mcp-resources)
-- [**Quick Start**](#quick-start)
+- ⚡ [Quick Start](#quick-start)
   - [Quick installation with **VSCode**](#quick-installation-with-vscode)
   - [Basic installation with **Claude Desktop**](#basic-installation-with-claude-desktop)
   - [Environment Variables](#environment-variables)
@@ -28,6 +33,7 @@ This server provides comprehensive tools for MSX software development, testing,
 - [License](#license)
 - [Support](#support)
 - [Contributing](#contributing)
+- 🌟 [More stars!](#more-stars) 🌟
 
 ## Project Overview
 
@@ -99,12 +105,12 @@ The MCP server translates high-level natural language commands from your Copilot
 ### Debugging Tools
 - `debug_run`: Control execution: _`break`, `isBreaked`, `continue`, `stepIn`, `stepOut`, `stepOver`, `stepBack`, `runTo`_.
 - `debug_cpu`: Read/write CPU registers, CPU info, Stack pile, and Disassemble code: _`getCpuRegisters`, `getRegister`, `setRegister`, `getStackPile`, `disassemble`, `getActiveCpu`_.
-- `debug_memory`: RAM memory operations: _`selectedSlots`, `getBlock`, `readByte`, `readWord`, `writeByte`, `writeWord`, `advanced_basic_listing`_.
-- `debug_vram`: VRAM operations: _`getBlock`, `readByte`, `writeByte`_.
+- `debug_memory`: RAM memory operations: _`selectedSlots`, `getBlock`, `readByte`, `readWord`, `writeByte`, `writeWord`, `searchBytes`_.
+- `debug_vram`: VRAM operations: _`getBlock`, `readByte`, `writeByte`, `searchBytes`_.
 - `debug_breakpoints`: Breakpoint management: _`create`, `remove`, `list`_.
 
 ### Automation Tools
-- `emu_keyboard`: Send text input to emulator: _`sendText`_.
+- `emu_keyboard`: Send text or key combinations to emulator: _`sendText`, `sendKeyCombo`_.
 - `emu_savestates`: Save and restore machine states: _`load`, `save`, `list`_.
 - `screen_shot`: Capture emulator screen: _`as_image`, `to_file`_.
 - `screen_dump`: Export screen data as BASIC BSAVE instruction.
@@ -154,7 +160,8 @@ And books and manuals:
 
 Thanks to the authors of these resources, who have made them available under various licenses. This MCP server includes some of these resources to enhance the development experience.
 
-The rights to these resources belong to their respective authors and are distributed under the licenses they have defined.
+> [!IMPORTANT]  
+> The rights to these resources belong to their respective authors and are distributed under the licenses they have defined.
 
 ## Quick Start
 
@@ -165,9 +172,11 @@ You can use this MCP server in this basic way with the [precompiled NPM package]
 [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?style=flat&logo=visualstudiocode&logoColor=ffffff)](https://insiders.vscode.dev/redirect/mcp/install?name=mcp-openmsx&config=%7B%22name%22%3A%22mcp-openmsx%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40nataliapc%2Fmcp-openmsx%22%5D%7D)
 
 Steps to install the MCP server in VSCode:
-* Install [Github Copilot extension](https://code.visualstudio.com/docs/copilot/overview)
-* Use the **Install MCP Server** button above to install the MCP server in your VSCode settings.
-* Or add to your workspace a file `.vscode/mcp.json` with the json configuration below.
+1. Install [Github Copilot extension](https://code.visualstudio.com/docs/copilot/overview)
+2. [Install nodejs](https://nodejs.org/en/download) (`npx` command must be available in your PATH).
+3. Install de MCP Server:
+    - Use the **Install MCP Server** button above to install the MCP server in your VSCode settings.
+    - Or add to your _workspace folder_ a file named `.vscode/mcp.json` with the json configuration below.
 
 ### STDIO mode (recommended)
 
@@ -185,7 +194,8 @@ Steps to install the MCP server in VSCode:
 }
 ```
 
-**Note:** Environment variables are optional. Customize them as you need.
+> [!NOTE]  
+> Environment variables are optional. Customize them as you need.
 
 ### Streamed HTTP mode (more advanced)
 
@@ -201,7 +211,8 @@ Steps to install the MCP server in VSCode:
 }
 ```
 
-**Note:** The MCP HTTP Server must be running standalone in the same computer or in another (`make run_http`).
+> [!NOTE]  
+> The MCP HTTP Server must be running standalone in the same computer or in another (`make run_http`).
 
 ### Basic Installation with Claude Desktop
 
@@ -223,26 +234,29 @@ Edit it to include the following JSON entry:
 }
 ```
 
-**Note:** Environment variables are optional. Customize them as you need.
+> [!NOTE]  
+> Environment variables are optional. Customize them as you need.
 
 ### Environment Variables
 
 | Variable | Description | Default Value | Example |
 |----------|-------------|---------------|---------|
-| `OPENMSX_EXECUTABLE` | Path or command to the openMSX executable | `openmsx` | `/usr/local/bin/openmsx` |
+| `OPENMSX_EXECUTABLE` | Path or command to the openMSX executable | `openmsx` (Linux/macOS) / `openmsx.exe` (Windows) | `/usr/local/bin/openmsx` or `C:\Program Files\openMSX\openmsx.exe` |
 | `OPENMSX_SHARE_DIR` | Directory containing openMSX data files (machines, extensions, etc.) | System dependent | `/home/myuser/.openmsx/share` |
 | `OPENMSX_SCREENSHOT_DIR` | Directory where screenshots will be saved | Default for openmsx | `/myproject/screenshots` |
 | `OPENMSX_SCREENDUMP_DIR` | Directory where screen dumps will be saved | Default for openmsx | `/myproject/screendumps` |
 | `OPENMSX_REPLAYS_DIR` | Directory where replay files will be saved | Default for openmsx | `/myproject/replays` |
 | `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` |
 
 
 ## Advanced Manual Usage
 
-This is not needed for using the MCP server, but if you want to install it manually, follow these steps.
+> [!IMPORTANT]  
+> This is not needed for using the MCP server, but if you want to install it manually, follow these steps.
 
-Currently, the MCP server requires Linux to be compiled. It has not been tested on Windows or macOS, although it will likely work on the latter as well.
+The MCP server runs on Linux, macOS, and Windows. Building from source requires Node.js >= 18 and TypeScript.
 
 ### Manual installation
 
@@ -261,6 +275,7 @@ export OPENMSX_SCREENSHOT_DIR="/my_project/screenshots"
 export OPENMSX_SCREENDUMP_DIR="/my_project/screendumps"
 export OPENMSX_REPLAYS_DIR="/my_project/replays"
 export MCP_HTTP_PORT=3000
+export MCP_ALLOWED_ORIGINS="http://localhost,http://mydomain.com"
 ```
 
 ### As MCP Server (stdio)
@@ -279,7 +294,8 @@ mcp-openmsx http
 
 ## Development
 
-This is not needed for using the MCP server, but if you want to contribute or modify the code, follow these steps.
+> [!IMPORTANT]  
+> This is not needed for using the MCP server, but if you want to contribute or modify the code, follow these steps.
 
 ### Prerequisites to build
 
@@ -316,4 +332,12 @@ If you need help, or have questions or suggestions, please open an issue on the
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
+
+## More stars!
+
+Please give us a star on [GitHub](https://github.com/nataliapc/mcp-openmsx) if you like this project.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=nataliapc/mcp-openmsx&type=Date&theme=dark)](https://www.star-history.com/#nataliapc/mcp-openmsx&Date)
+## Star History
+
 ---

package/dist/openmsx.js

@@ -166,8 +166,13 @@ export class OpenMSX {
                     this.sendCommand('exit');
                 }
                 catch (error) {
-                    // If writing fails, force kill
-                    this.process.kill('SIGTERM');
+                    // If writing fails, force kill.
+                    // Use no-argument kill() for cross-platform safety:
+                    // on POSIX it sends SIGTERM; on Windows it calls TerminateProcess().
+                    try {
+                        this.process.kill();
+                    }
+                    catch (_) { /* ignore */ }
                 }
             }
             else {
@@ -348,6 +353,9 @@ export class OpenMSX {
     forceClose() {
         if (this.process && !this.process.killed) {
             try {
+                // 'SIGKILL' is accepted on Windows too (maps to TerminateProcess).
+                // No-argument kill() is also acceptable here, but SIGKILL makes
+                // the intent explicit: we want unconditional termination.
                 this.process.kill('SIGKILL');
             }
             catch (error) {

package/dist/server.js

@@ -16,6 +16,7 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { randomUUID } from "node:crypto";
 import express from "express";
 import path from "path";
+import { fileURLToPath } from 'node:url';
 import { createRequire } from 'module';
 import { openMSXInstance } from "./openmsx.js";
 import { VectorDB } from "./vectordb.js";
@@ -26,11 +27,14 @@ import { registerPrompts } from "./server_prompts.js";
 // Dynamically obtain PACKAGE_VERSION from package.json at runtime
 const require = createRequire(import.meta.url);
 export const PACKAGE_VERSION = require('../package.json').version;
-const resourcesDir = path.join(path.dirname(new URL(import.meta.url).pathname), "../resources");
-const vectorDbDir = path.join(path.dirname(new URL(import.meta.url).pathname), "../vector-db");
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const resourcesDir = path.join(__dirname, "../resources");
+const vectorDbDir = path.join(__dirname, "../vector-db");
 export const emuDirectories = {
     OPENMSX_SHARE_DIR: '',
-    OPENMSX_EXECUTABLE: 'openmsx',
+    // On Windows, Node.js spawn() may not resolve 'openmsx' to 'openmsx.exe' unless it is in PATH.
+    // Using the platform-aware default reduces friction for Windows users who have openMSX in PATH.
+    OPENMSX_EXECUTABLE: process.platform === 'win32' ? 'openmsx.exe' : 'openmsx',
     OPENMSX_REPLAYS_DIR: '',
     OPENMSX_SCREENSHOT_DIR: '',
     OPENMSX_SCREENDUMP_DIR: '',
@@ -125,6 +129,8 @@ async function startHttpServer() {
         else if (!sessionId && isInitializeRequest(req.body)) {
             transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: () => randomUUID(),
+                enableDnsRebindingProtection: true,
+                allowedOrigins: process.env.MCP_ALLOWED_ORIGINS?.split(',') || [],
                 onsessioninitialized: (sessionId) => {
                     transports[sessionId] = transport;
                 }

package/dist/server_elicitations.js

@@ -0,0 +1,178 @@
+import { openMSXInstance } from "./openmsx.js";
+import { isErrorResponse } from "./utils.js";
+import { samplingFindMatches } from "./server_sampling.js";
+// ============================================================================
+// Default machines offered when no machine is specified in launch command
+// ============================================================================
+const DEFAULT_MACHINES = [
+    { const: 'C-BIOS_MSX1', title: 'MSX1 (C-BIOS, no system ROMs needed)' },
+    { const: 'Philips_VG_8020', title: 'MSX1 European (Philips VG-8020)' },
+    { const: 'C-BIOS_MSX2', title: 'MSX2 (C-BIOS, no system ROMs needed)' },
+    { const: 'Philips_NMS_8250', title: 'MSX2 European (Philips NMS-8250)' },
+    { const: 'C-BIOS_MSX2+', title: 'MSX2+ (C-BIOS, openMSX default)' },
+    { const: 'Panasonic_FS-A1GT', title: 'MSX turboR (Panasonic FS-A1GT)' },
+];
+// ============================================================================
+// Helper: Resolve machine and extensions for launch using elicitation + sampling
+// ============================================================================
+export async function resolveLaunchParams(server, emuDirectories, machine, extensions) {
+    // Load lists lazily only when needed
+    let machinesList;
+    let extensionsList;
+    const loadMachinesList = async () => {
+        if (!machinesList) {
+            const raw = await openMSXInstance.getMachineList(emuDirectories.MACHINES_DIR);
+            if (isErrorResponse(raw))
+                throw new Error(raw);
+            machinesList = JSON.parse(raw);
+        }
+        return machinesList;
+    };
+    const loadExtensionsList = async () => {
+        if (!extensionsList) {
+            const raw = await openMSXInstance.getExtensionList(emuDirectories.EXTENSIONS_DIR);
+            if (isErrorResponse(raw))
+                throw new Error(raw);
+            extensionsList = JSON.parse(raw);
+        }
+        return extensionsList;
+    };
+    // ── Resolve machine ──────────────────────────────────────────────────
+    let resolvedMachine = machine || '';
+    if (machine) {
+        // Check for exact match
+        const machines = await loadMachinesList();
+        const exactMatch = machines.find(m => m.name.toLowerCase() === machine.toLowerCase());
+        if (exactMatch) {
+            resolvedMachine = exactMatch.name;
+        }
+        else {
+            // Ambiguous machine name → use sampling to find suggestions, then elicit
+            try {
+                const suggestions = await samplingFindMatches(server, machine, machines, 'machine');
+                if (suggestions.length > 0) {
+                    const elicitResult = await server.server.elicitInput({
+                        mode: 'form',
+                        message: `No exact match found for machine "${machine}". Please select the MSX machine to emulate:`,
+                        requestedSchema: {
+                            type: 'object',
+                            properties: {
+                                machine: {
+                                    type: 'string',
+                                    title: 'MSX Machine',
+                                    description: `Best matches for "${machine}"`,
+                                    oneOf: suggestions,
+                                },
+                            },
+                            required: ['machine'],
+                        },
+                    });
+                    if (elicitResult.action !== 'accept' || !elicitResult.content) {
+                        return { machine: '', extensions: [], cancelled: true };
+                    }
+                    resolvedMachine = elicitResult.content.machine;
+                }
+                else {
+                    // Sampling found nothing → use the original value (let openMSX handle the error)
+                    resolvedMachine = machine;
+                }
+            }
+            catch {
+                // Client doesn't support sampling/elicitation → fallback
+                resolvedMachine = machine;
+            }
+        }
+    }
+    else {
+        // No machine provided → elicit with common defaults
+        try {
+            const elicitResult = await server.server.elicitInput({
+                mode: 'form',
+                message: 'No machine specified. Please select the MSX machine to emulate:',
+                requestedSchema: {
+                    type: 'object',
+                    properties: {
+                        machine: {
+                            type: 'string',
+                            title: 'MSX Machine',
+                            description: 'Select the type of MSX machine to launch',
+                            oneOf: DEFAULT_MACHINES,
+                        },
+                    },
+                    required: ['machine'],
+                },
+            });
+            if (elicitResult.action !== 'accept' || !elicitResult.content) {
+                return { machine: '', extensions: [], cancelled: true };
+            }
+            resolvedMachine = elicitResult.content.machine;
+        }
+        catch {
+            // Client doesn't support elicitation → launch with openMSX default
+            resolvedMachine = '';
+        }
+    }
+    // ── Resolve extensions ───────────────────────────────────────────────
+    let resolvedExtensions = extensions || [];
+    if (extensions && extensions.length > 0) {
+        try {
+            const allExtensions = await loadExtensionsList();
+            const extNameMap = new Map(allExtensions.map(e => [e.name.toLowerCase(), e]));
+            const matched = [];
+            const ambiguous = [];
+            for (const ext of extensions) {
+                const exact = extNameMap.get(ext.toLowerCase());
+                if (exact) {
+                    matched.push(exact.name);
+                }
+                else {
+                    ambiguous.push(ext);
+                }
+            }
+            if (ambiguous.length > 0) {
+                // Use sampling to find best matches for ALL ambiguous extensions at once
+                const ambiguousQuery = ambiguous.join(', ');
+                const suggestions = await samplingFindMatches(server, ambiguousQuery, allExtensions, 'extension', 6);
+                if (suggestions.length > 0) {
+                    // Pre-select the already matched extensions in the suggestions
+                    const elicitResult = await server.server.elicitInput({
+                        mode: 'form',
+                        message: `No exact match found for extension(s): ${ambiguous.map(e => `"${e}"`).join(', ')}. Please select the extensions to use:`,
+                        requestedSchema: {
+                            type: 'object',
+                            properties: {
+                                extensions: {
+                                    type: 'array',
+                                    title: 'MSX Extensions',
+                                    description: `Best matches for: ${ambiguousQuery}`,
+                                    items: {
+                                        anyOf: suggestions,
+                                    },
+                                },
+                            },
+                            required: ['extensions'],
+                        },
+                    });
+                    if (elicitResult.action !== 'accept' || !elicitResult.content) {
+                        return { machine: resolvedMachine, extensions: [], cancelled: true };
+                    }
+                    const selectedExtensions = elicitResult.content.extensions;
+                    resolvedExtensions = [...matched, ...selectedExtensions];
+                }
+                else {
+                    // Sampling found nothing → use original values
+                    resolvedExtensions = extensions;
+                }
+            }
+            else {
+                // All extensions matched exactly
+                resolvedExtensions = matched;
+            }
+        }
+        catch {
+            // Client doesn't support sampling/elicitation → fallback
+            resolvedExtensions = extensions;
+        }
+    }
+    return { machine: resolvedMachine, extensions: resolvedExtensions };
+}

package/dist/server_prompts.js

@@ -17,7 +17,7 @@ export async function registerPrompts(server) {
                 .max(50, "Instruction name too long")
                 .describe("Name of the MSX BASIC instruction to get information about (e.g. 'PRINT', 'FOR', 'POKE'). Case insensitive.")
                 .transform(val => val.trim().toUpperCase()),
-        }
+        },
     }, 
     // Handler for the prompt (function to be executed when the prompt is called)
     ({ instruction }) => {

package/dist/server_resources.js

@@ -65,6 +65,10 @@ export async function registerResources(server, resourcesDir) {
                     title: item.title || `MSX Documentation '${sectionName}': ${itemName}`,
                     description: item.description || `Documentation for MSX resource '${sectionName}': ${itemName}`,
                     mimeType: item.mimeType || 'text/markdown',
+                    annotations: {
+                        "audience": ["user", "assistant"],
+                        "priority": 0.8,
+                    },
                 }, 
                 // Handler for the resource (function to be executed when the resource is called)
                 async (uri) => {
@@ -106,7 +110,7 @@ export async function registerResources(server, resourcesDir) {
     }
     ;
     // Source: https://www.msx.org/wiki/Category:MSX-BASIC_Instructions
-    server.resource("msxdocs_basic_wiki", new ResourceTemplate("msxdocs://basic_wiki/{instruction}", {
+    server.registerResource("msxdocs_basic_wiki", new ResourceTemplate("msxdocs://basic_wiki/{instruction}", {
         list: undefined,
         complete: {
             instruction: (value) => basicInstructions,
@@ -115,20 +119,28 @@ export async function registerResources(server, resourcesDir) {
         title: "MSX BASIC Instructions Documentation",
         description: "Documentation about all the standard MSX BASIC instructions from www.msx.org/wiki/Category:MSX-BASIC_Instructions",
         mimeType: "text/html",
+        annotations: {
+            "audience": ["user", "assistant"],
+            "priority": 0.8,
+        },
     }, async (uri, variables) => {
         let instruction = variables.instruction;
         let resourceContent;
         let mimeType;
         // urldecode the instruction to avoid issues with special characters
         instruction = decodeURIComponent(instruction).replaceAll(' ', '_');
+        // Convert Windows-invalid characters to safe equivalents for the filesystem lookup.
+        // The RAG and MCP URIs keep the canonical command name (e.g. CLOAD?),
+        // but the file on disk uses a safe name (e.g. CLOAD_Q.md).
+        const instructionFile = instruction.replaceAll('?', '_Q');
         try {
             let resourceFile;
-            [mimeType, resourceFile] = await addFileExtension(path.join(resourcesDir, 'programming', 'basic_wiki', instruction));
+            [mimeType, resourceFile] = await addFileExtension(path.join(resourcesDir, 'programming', 'basic_wiki', instructionFile));
             resourceContent = await fs.readFile(resourceFile, 'utf8');
         }
         catch (error) {
             // Throw exception (MCP protocol requirement)
-            throw new Error(`Error reading resource programming/basic_wiki/${instruction}: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`Error reading resource programming/basic_wiki/${instruction} (file: ${instructionFile}): ${error instanceof Error ? error.message : String(error)}`);
         }
         return {
             contents: [{

package/dist/server_sampling.js

@@ -0,0 +1,35 @@
+// ============================================================================
+// Helper: Use sampling (LLM) to pick the best matches from a list
+// ============================================================================
+export async function samplingFindMatches(server, userQuery, items, itemType, maxResults = 6) {
+    // Build a compact list for the LLM
+    const itemList = items.map(m => `${m.name}: ${m.description}`).join('\n');
+    const samplingResult = await server.server.createMessage({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `The user wants to launch an MSX emulator with ${itemType}: "${userQuery}".\n\nHere is the full list of available ${itemType}s:\n${itemList}\n\nReturn ONLY the top ${maxResults} best matching ${itemType} names (exact names from the list), one per line, no numbering, no descriptions, no extra text. Most relevant first.`
+                }
+            }],
+        maxTokens: 300,
+        systemPrompt: `You are a helpful assistant that matches user queries to MSX ${itemType} names. Return ONLY exact names from the provided list, one per line. No extra text.`,
+        temperature: 0,
+    });
+    if (samplingResult.content.type !== 'text')
+        return [];
+    const suggestedNames = samplingResult.content.text
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.length > 0);
+    // Map back to items with validation
+    const nameMap = new Map(items.map(m => [m.name.toLowerCase(), m]));
+    const matches = [];
+    for (const name of suggestedNames) {
+        const item = nameMap.get(name.toLowerCase());
+        if (item && matches.length < maxResults) {
+            matches.push({ const: item.name, title: `${item.name} — ${item.description}` });
+        }
+    }
+    return matches;
+}