@nataliapc/mcp-openmsx 1.2.3 → 1.2.5

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

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { basicInstructions } from "./server_resources.js";
+// ============================================================================
+// Prompts available in the MCP server
+// https://modelcontextprotocol.io/docs/concepts/prompts
+export async function registerPrompts(server) {
+    server.registerPrompt(
+    // Name of the prompt (used to call it)
+    "basic", {
+        title: "MSX BASIC Instruction Manual",
+        // Description of the prompt (what it does)
+        description: "MSX BASIC instructions manual",
+        // Schema for the prompt (input validation)
+        argsSchema: {
+            instruction: z.string()
+                .min(1, "Instruction name cannot be empty")
+                .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 }) => {
+        // Normalize instruction name for better matching
+        const normalizedInstruction = instruction.replace(/[()]/g, '').trim();
+        let prompt = '';
+        // Check if instruction is in the known list
+        const isKnownInstruction = basicInstructions.some(basic => basic.replace(/[()]/g, '').toUpperCase() === normalizedInstruction);
+        if (isKnownInstruction) {
+            prompt = `Provide comprehensive information about the MSX BASIC instruction '${instruction}'.
+STRICT REQUIREMENTS: 
+- NEVER invent or assume any information not explicitly found in the MCP resources
+- ONLY use information from 'msxdocs:' resources and tools #msxdocs_resource_get and #vector_db_query
+- If specific details (ranges, values, behaviors) are not in the resources, state "Not specified in available documentation"
+- Do NOT use general knowledge about MSX systems - stick ONLY to what the resources contain
+- When citing parameters or ranges, quote them EXACTLY as written in the source documentation
+MANDATORY SECTIONS:
+- Include these sections if information is available in resources: 'Description', 'Syntax', 'Parameters', 'Notes', 'Usage examples', 'Related instructions', and 'Availability'.
+- You MUST respond in the user language, unless otherwise specified.
+SOURCES:
+- Always cite the specific MCP resources used at the end in section 'Sources' with exact resource uri.
+- For each resource, add a markdown link to the resource if external url is available.`;
+        }
+        else {
+            const suggestions = basicInstructions
+                .filter(basic => basic.toUpperCase().includes(normalizedInstruction) ||
+                normalizedInstruction.includes(basic.replace(/[()]/g, '').toUpperCase()))
+                .slice(0, 5);
+            // If the instruction is not known, suggest alternatives
+            prompt = `Explain that '${instruction}' does not appear to be a standard MSX BASIC instruction.
+STRICT REQUIREMENTS:
+- ONLY use information found in MCP resources via #vector_db_query tool
+- Do NOT assume or invent any information about MSX BASIC instructions
+- If suggesting alternatives, provide ONLY what is found in the search results
+${suggestions.length > 0 ? `Suggest one of these: ${suggestions.join(', ')} instructions as a correct search string. List them with a brief description using ONLY information found in the resources 'msxdocs://basic_wiki/{instruction}'` : 'Use #vector_db_query to search for similar instructions.'}
+IMPORTANT: Review the available MSX BASIC instructions using the available MCP resources. You may still try to find information using the available resources, as it could be documented under a different name or as part of another instruction. Base your response EXCLUSIVELY on what the resources and tools return.
+You MUST respond in the user language, unless otherwise specified.`;
+        }
+        return {
+            messages: [{
+                    role: "assistant",
+                    content: {
+                        type: "text",
+                        text: prompt,
+                    },
+                }]
+        };
+    });
+}

package/dist/server_resources.js

@@ -0,0 +1,149 @@
+/**
+ * @package @nataliapc/mcp-openmsx
+ * @author Natalia Pujol Cremades (@nataliapc)
+ * @license GPL2
+ */
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import fs from "fs/promises";
+import path from "path";
+import { fetchCleanWebpage, addFileExtension, listResourcesDirectory } from "./utils.js";
+// Source: https://www.msx.org/wiki/Category:MSX-BASIC_Instructions
+export const basicInstructions = [
+    "ABS()", "AND", "ASC()", "ATN()", "AUTO", "BASE()", "BEEP", "BIN$()", "BLOAD", "BSAVE", "CALL", "CALL ADJUST",
+    "CALL IMPOSE", "CALL OPTIONS", "CALL PAUSE", "CALL PCMPLAY", "CALL PCMREC", "CDBL()", "CHR$()", "CINT()", "CIRCLE",
+    "CLEAR", "CLOAD", "CLOAD?", "CLOSE", "CLS", "COLOR", "COLOR=", "COLOR SPRITE()", "COLOR SPRITE$()", "CONT", "COPY",
+    "COPY SCREEN", "COS()", "CSAVE", "CSNG()", "CSRLIN", "DATA", "DEFDBL", "DEF FN", "DEFINT", "DEFSNG", "DEFSTR",
+    "DEF USR", "DELETE", "DIM", "DRAW", "ELSE", "END", "EOF()", "EQV", "ERASE", "ERL", "ERR", "ERROR", "EXP()", "FIELD",
+    "FIX()", "FN", "FOR...NEXT", "FRE()", "GET DATE", "GET TIME", "GOSUB", "GOTO", "HEX$()", "IF...GOTO...ELSE",
+    "IF...THEN...ELSE", "IMP", "INKEY$", "INP()", "INPUT", "INPUT$()", "INSTR()", "INT()", "INTERVAL", "KEY", "KEY()",
+    "LEFT$()", "LEN()", "LET", "LINE", "LINE INPUT", "LIST", "LLIST", "LOAD", "LOCATE", "LOG()", "LPOS()", "LPRINT",
+    "MAXFILES", "MERGE", "MID$()", "MOD", "MOTOR", "NEW", "NOT", "OCT$()", "ON...GOSUB", "ON...GOTO", "ON ERROR GOTO",
+    "ON INTERVAL GOSUB", "ON KEY GOSUB", "ON SPRITE GOSUB", "ON STOP GOSUB", "ON STRIG GOSUB", "OPEN", "OR", "OUT",
+    "PAD()", "PAINT", "PDL()", "PEEK()", "PLAY", "PLAY()", "POINT", "POKE", "POS()", "PRESET", "PRINT", "PSET",
+    "PUT KANJI", "PUT SPRITE", "READ", "REM", "RENUM", "RESTORE", "RESUME", "RETURN", "RIGHT$()", "RND()", "RUN",
+    "SAVE", "SCREEN", "SET ADJUST", "SET BEEP", "SET DATE", "SET PAGE", "SET PASSWORD", "SET PROMPT", "SET SCREEN",
+    "SET SCROLL", "SET TIME", "SET TITLE", "SET VIDEO", "SGN()", "SIN()", "SOUND", "SPACE$()", "SPC()", "SPRITE",
+    "SPRITE$()", "SQR()", "STICK()", "STOP", "STR$()", "STRIG()", "STRING$()", "SWAP", "TAB()", "TAN()", "TIME",
+    "TROFF", "TRON", "USR()", "VAL()", "VARPTR()", "VDP()", "VPEEK()", "VPOKE", "WAIT", "WIDTH", "XOR"
+];
+const regResources = [];
+export function getRegisteredResourcesList() {
+    return regResources;
+}
+// ============================================================================
+// Resources available in the MCP server
+// https://modelcontextprotocol.io/docs/concepts/resources
+export async function registerResources(server, resourcesDir) {
+    // ============================================================================
+    // MSX Documentation resources
+    const resdocs = (await listResourcesDirectory(resourcesDir)).sort();
+    for (let index = 0; index < resdocs.length; index++) {
+        // Read the toc.json file if exists, otherwise skip this section
+        const sectionName = resdocs[index];
+        const tocFile = path.join(resourcesDir, `${sectionName}/toc.json`);
+        let tocContent = { toc: [] };
+        try {
+            tocContent = JSON.parse(await fs.readFile(tocFile, 'utf8'));
+        }
+        catch (error) {
+            // The toc.json file does not exist or is invalid, skip this section
+            continue;
+        }
+        // Register each item in the toc.json as a resource
+        tocContent.toc.forEach((item, itemIndex) => {
+            const itemName = path.parse(item.uri.split('/').pop()).base || '';
+            let resource = {
+                uri: item.uri,
+                filename: '',
+                resource: server.registerResource(
+                // Name of the resource (used to call it)
+                `msxdocs_${sectionName}_${item.title.replace(/[^a-z0-9]+/gi, '_').toLowerCase()}`, 
+                // Resource URI template
+                item.uri, 
+                // Metadata for the resource
+                {
+                    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) => {
+                    let resourceContent;
+                    let mimeType;
+                    if (uri.href.startsWith('http://') || uri.href.startsWith('https://')) {
+                        // Fetch the resource from the URL
+                        try {
+                            [resourceContent, mimeType] = await fetchCleanWebpage(uri.href);
+                        }
+                        catch (error) {
+                            // Throw exception (MCP protocol requirement)
+                            throw error;
+                        }
+                    }
+                    else {
+                        // Read the resource from the local MCP server resources directory
+                        try {
+                            let resourceFile;
+                            [mimeType, resourceFile] = await addFileExtension(path.join(resourcesDir, `${sectionName}/${itemName}`));
+                            resourceContent = await fs.readFile(resourceFile, 'utf8');
+                        }
+                        catch (error) {
+                            // Throw exception (MCP protocol requirement)
+                            throw new Error(`Error reading resource ${sectionName}/${item.uri}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                    return {
+                        contents: [{
+                                uri: uri.href,
+                                text: resourceContent,
+                                mimeType: mimeType || 'text/plain',
+                            }],
+                    };
+                })
+            };
+            regResources.push(resource);
+        });
+    }
+    ;
+    // Source: https://www.msx.org/wiki/Category:MSX-BASIC_Instructions
+    server.registerResource("msxdocs_basic_wiki", new ResourceTemplate("msxdocs://basic_wiki/{instruction}", {
+        list: undefined,
+        complete: {
+            instruction: (value) => basicInstructions,
+        },
+    }), {
+        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(' ', '_');
+        try {
+            let resourceFile;
+            [mimeType, resourceFile] = await addFileExtension(path.join(resourcesDir, 'programming', 'basic_wiki', instruction));
+            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)}`);
+        }
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: resourceContent,
+                    mimeType: mimeType || 'text/plain',
+                }],
+        };
+    });
+}

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