@nataliapc/mcp-openmsx 1.2.4 → 1.2.5

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
 
@@ -104,7 +110,7 @@ The MCP server translates high-level natural language commands from your Copilot
 - `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,7 +234,8 @@ 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
 
@@ -236,11 +248,13 @@ Edit it to include the following JSON entry:
 | `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.
 
@@ -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/server.js

@@ -125,6 +125,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,6 +119,10 @@ 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;

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;
+}