@nataliapc/mcp-openmsx 1.1.14 → 1.1.15

package/README.md

@@ -2,6 +2,14 @@
 
 *"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)
+[![GitHub Repo stars](https://img.shields.io/github/stars/nataliapc/mcp-openmsx)
+](https://github.com/nataliapc/mcp-openmsx/stargazers/)  
+[![NPM Version](https://img.shields.io/npm/v/%40nataliapc%2Fmcp-openmsx)](https://www.npmjs.com/package/@nataliapc/mcp-openmsx?activeTab=versions)
+[![NPM Downloads](https://img.shields.io/npm/dm/%40nataliapc%2Fmcp-openmsx?color=808000)]()
+
+
 A [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server for automating [openMSX emulator](https://github.com/openMSX/openMSX) instances.
 
 This server provides comprehensive tools for MSX software development, testing, and automation through standardized MCP protocols.
@@ -64,6 +72,7 @@ The MCP server translates high-level commands from your Copilot AI into `TCL` co
 - `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.
+- `msxdocs_resource_get`: Retrieve MCP resources for MCP clients that don't support MCP resources.
 
 ## 📚 Available MCP Resources
 
@@ -85,10 +94,11 @@ There are more than 60 resources available, some included directly in the MCP an
 - `MSX-UNAPI`
 - `MSX BASIC`
 
-And two books:
+And books and manuals:
 
 - `MSX2 Technical Handbook`
 - `The MSX Red Book`
+- `SDCC Compiler`
 
 ### Resources from:
 
@@ -98,8 +108,9 @@ And two books:
 - [MSX2 Technical Handbook](https://github.com/Konamiman/MSX2-Technical-Handbook)
 - [Konamiman MSX-UNAPI-specification](https://github.com/Konamiman/MSX-UNAPI-specification)
 - [BiFi MSX Net](http://bifi.msxnet.org/msxnet/)
-- [MSX Wiki](https://www.msx.org/wiki/Main_Page)
+- [MRC Wiki](https://www.msx.org/wiki/Main_Page)
 - [MSX Banzai!](http://msxbanzai.tni.nl/)
+- [SDCC](https://sdcc.sourceforge.net/)
 
 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.
 
@@ -116,6 +127,9 @@ You can use this MCP server in this basic way with the [precompiled NPM package]
 
 ### STDIO mode (recommended)
 
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22stdio%22%2C%22command%22%3A%20%22npx%22%2C%22args%22%3A%20%5B%22%40nataliapc%2Fmcp-openmsx%22%5D%2C%20%22env%22%3A%20%7B%22OPENMSX_SHARE_DIR%22%3A%20%22%2Fusr%2Fshare%2Fopenmsx%22%7D%7D)
+[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22stdio%22%2C%22command%22%3A%20%22npx%22%2C%22args%22%3A%20%5B%22%40nataliapc%2Fmcp-openmsx%22%5D%2C%20%22env%22%3A%20%7B%22OPENMSX_SHARE_DIR%22%3A%20%22%2Fusr%2Fshare%2Fopenmsx%22%7D%7D&quality=insiders)
+
 ```json
 {
   "servers": {

package/dist/server.js

@@ -6,7 +6,7 @@
  * through TCL commands via stdio.
  *
  * @package @nataliapc/mcp-openmsx
- * @version 1.1.14
+ * @version 1.1.15
  * @author Natalia Pujol Cremades (@nataliapc)
  * @license GPL2
  */
@@ -22,7 +22,7 @@ import path from "path";
 import { openMSXInstance } from "./openmsx.js";
 import { fetchCleanWebpage, addFileExtension, listResourcesDirectory, encodeTypeText, isErrorResponse, getResponseContent } from "./utils.js";
 // Version info for CLI
-const PACKAGE_VERSION = "1.1.14";
+export const PACKAGE_VERSION = "1.1.15";
 const resourcesDir = path.join(path.dirname(new URL(import.meta.url).pathname), "../resources");
 // Defaults for openMSX paths
 var OPENMSX_EXECUTABLE = 'openmsx';
@@ -864,84 +864,95 @@ The parameter scrbasename is the name of the filename (without path) to save the
     // ============================================================================
     // MSX Documentation resources
     const resdocs = (await listResourcesDirectory(resourcesDir)).sort();
+    const regResources = [];
     for (let index = 0; index < resdocs.length; index++) {
         const sectionName = resdocs[index];
         const tocFile = path.join(resourcesDir, `${sectionName}/toc.json`);
         const tocContent = JSON.parse(await fs.readFile(tocFile, 'utf8'));
         tocContent.toc.forEach((item, itemIndex) => {
             const itemName = path.parse(item.uri.split('/').pop()).name || '';
-            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',
-            }, 
-            // 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);
+            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',
+                }, 
+                // 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;
+                        }
                     }
-                    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)}`);
+                        }
                     }
-                }
-                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',
-                        }],
-                };
-            });
+                    return {
+                        contents: [{
+                                uri: uri.href,
+                                text: resourceContent,
+                                mimeType: mimeType || 'text/plain',
+                            }],
+                    };
+                })
+            };
+            regResources.push(resource);
         });
     }
     ;
+    // Source: https://www.msx.org/wiki/Category:MSX-BASIC_Instructions
+    const basicInstructions = [
+        "ABS()", "AND", "ASC()", "ATN()", "AUTO", "BASE()", "BEEP", "BIN$()", "BLOAD", "BSAVE", "CALL", "CALL ADJUST", "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()", "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"
+    ];
     server.resource("msxdocs_basic_wiki", new ResourceTemplate("msxdocs://basic_wiki/{instruction}", {
         list: undefined,
         complete: {
-            instruction: (value) => [
-                "ABS()", "AND", "ASC()", "ATN()", "AUTO", "BASE()", "BEEP", "BIN$()", "BLOAD", "BSAVE", "CALL", "CALL ADJUST", "CALL PAUSE", "CALL PCMPLAY", "CALL PCMREC",
-                "CDBL()", "CHR$()", "CINT()", "CIRCLE", "CLEAR", "CLOAD", "CLOAD?", "CLOSE", "CLS", "COLOR", "COLOR=", "COLOR", "COLOR", "CONT", "COPY", "COPY", "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()", "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"
-            ],
+            instruction: (value) => basicInstructions,
         },
     }), {
         title: "MSX BASIC Instructions Documentation",
         description: "Documentation about all the standard MSX BASIC instructions from www.msx.org",
         mimeType: "text/html",
     }, async (uri, variables) => {
-        const instruction = variables.instruction.replace(/ /g, '_').replace(/\?/g, '%3F').replace(/=/g, '%3D');
+        const instruction = variables.instruction
+            .replace(/ /g, '_')
+            .replace(/\?/g, '%3F')
+            .replace(/=/g, '%3D');
         const url = `https://www.msx.org/wiki/${instruction}`;
         let resourceContent;
         let mimeType;
@@ -960,6 +971,73 @@ The parameter scrbasename is the name of the filename (without path) to save the
                 }],
         };
     });
+    // Register the tool to get a specific MSX documentation resource
+    server.registerTool(
+    // Name of the tool (used to call it)
+    "msxdocs_resource_get", {
+        title: "Tool to get a resource",
+        // Description of the tool (what it does)
+        description: "Get a specific available MSX documentation resource from this MCP server resources.",
+        // Schema for the tool (input validation)
+        inputSchema: {
+            resourceName: z.enum(regResources.map(res => res.resource.name)).describe("Name of the resource to obtain, e.g. 'msxdocs_programming_interrupts'"),
+        },
+    }, 
+    // Handler for the tool (function to be executed when the tool is called)
+    async ({ resourceName }, extra) => {
+        const index = regResources.findIndex((res) => res.resource.name === resourceName);
+        const uriString = index !== -1 ? regResources[index].uri : undefined;
+        const resource = index !== -1 ? regResources[index].resource : undefined;
+        if (!resource || !uriString) {
+            return getResponseContent([
+                `Error: Resource '${resourceName}' not found.`
+            ]);
+        }
+        let documentationText = '';
+        try {
+            // If the resource is found, return its content
+            let resourceContent = await resource.readCallback(new URL(uriString), extra);
+            if (!resourceContent.contents?.length) {
+                return getResponseContent([
+                    `Error: Resource '${resourceName}' has no content available.`
+                ]);
+            }
+            // Return the first content item (assuming it's the main content)
+            const content = resourceContent.contents[0];
+            if ('text' in content) {
+                documentationText = content.text;
+            }
+            else {
+                return getResponseContent([
+                    `Error: Resource '${resourceName}' has no content available.`
+                ]);
+            }
+        }
+        catch (error) {
+            return getResponseContent([
+                `Error: error reading resource '${resourceName}': ${error instanceof Error ? error.message : String(error)}`
+            ]);
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: `Content from resource: '${resourceName}'`,
+                }, {
+                    type: "text",
+                    text: documentationText || 'No content available for this resource.',
+                    mimeType: resource.metadata?.mimeType || 'text/plain',
+                } /*, {
+                    type: "resource",
+                    resource: {
+                        uri: resource.metadata?.uri || resourceName,
+                        title: resource.metadata?.title || `Resource: ${resourceName}`,
+                        mimeType: resource.metadata?.mimeType || 'text/plain',
+                        text: documentationText || 'No content available for this resource.',
+                    }
+                }*/
+            ],
+        };
+    });
 }
 // ============================================================================
 // Cleanup handlers for graceful shutdown of MCP server
@@ -1071,8 +1149,8 @@ async function startHttpServer() {
         }
         await transport.handleRequest(req, res, req.body);
     });
-    // Handle GET requests for server-to-client notifications via SSE
-    app.get('/mcp', async (req, res) => {
+    // Reusable handle GET / DELETE requests
+    const handleSessionRequest = async (req, res) => {
         const sessionId = req.headers['mcp-session-id'];
         if (!sessionId || !transports[sessionId]) {
             res.status(400).send('Invalid or missing session ID');
@@ -1080,7 +1158,9 @@ async function startHttpServer() {
         }
         const transport = transports[sessionId];
         await transport.handleRequest(req, res);
-    });
+    };
+    app.get('/mcp', handleSessionRequest);
+    app.delete('/mcp', handleSessionRequest);
     const port = process.env.MCP_HTTP_PORT || 3000;
     app.listen(port, () => {
         console.log(`MCP Server listening on port ${port}`);

package/dist/utils.js

@@ -7,6 +7,9 @@
 import fs from 'fs/promises';
 import path from 'path';
 import mime from 'mime-types';
+import { gunzipSync } from 'zlib';
+import { PACKAGE_VERSION } from "./server.js";
+import sanitizeHtml from 'sanitize-html';
 /**
  * Extract description from XML file
  * @param filePath - Full path to the XML file
@@ -77,12 +80,48 @@ export async function fetchCleanWebpage(url) {
     let resourceContent;
     let mimeType = 'text/plain';
     try {
-        resourceContent = await fetch(url).then(response => {
+        const response = await fetch(url, {
+            headers: {
+                // Accept compressed content gzip/deflate
+                'Accept-Encoding': 'gzip, deflate, br',
+                // User agent to avoid blocking by some servers
+                'User-Agent': `Mozilla/5.0 (compatible; MCP-openMSX/${PACKAGE_VERSION})`
+            }
+        });
+        if (response.status === 200) {
             mimeType = response.headers.get('content-type') || 'text/plain';
-            return response.text();
-        }) || 'Error downloading content';
-        // Remove script, style, and link tags from the content
-        resourceContent = resourceContent.replace(/<script\b[^>]*>[\s\S]*?<\/script>|<style\b[^>]*>[\s\S]*?<\/style>|<link\b[^>]*\/?>/gi, '');
+            const contentType = response.headers.get('content-type') || '';
+            if (contentType.includes('x-gzip') || contentType.includes('gzip')) {
+                const arrayBuffer = await response.arrayBuffer();
+                const uint8Array = new Uint8Array(arrayBuffer);
+                if (uint8Array[0] === 0x1f && uint8Array[1] === 0x8b) {
+                    try {
+                        const decompressed = gunzipSync(Buffer.from(uint8Array));
+                        resourceContent = decompressed.toString('utf8');
+                        mimeType = 'text/html';
+                    }
+                    catch (error) {
+                        resourceContent = new TextDecoder().decode(uint8Array);
+                        mimeType = 'text/html';
+                    }
+                }
+                else {
+                    resourceContent = new TextDecoder().decode(uint8Array);
+                    mimeType = 'text/html';
+                }
+            }
+            else {
+                // Normal case, use response.text() which automatically handles decompression
+                resourceContent = await response.text();
+            }
+        }
+        else {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        // Remove script, style, form, and link tags from the content if it's HTML
+        if (mimeType.startsWith('text/html')) {
+            resourceContent = sanitizeHtml(resourceContent);
+        }
     }
     catch (error) {
         // Throw exception (MCP protocol requirement)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.1.14",
+  "version": "1.1.15",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",
@@ -38,9 +38,10 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.2",
+    "@modelcontextprotocol/sdk": "^1.15.1",
     "@types/express": "^5.0.2",
     "express": "^5.1.0",
+    "sanitize-html": "^2.17.0",
     "tsx": "^4.7.1",
     "zod": "^3.24.4"
   },
@@ -48,6 +49,7 @@
     "@modelcontextprotocol/inspector": "^0.15.0",
     "@types/mime-types": "^3.0.1",
     "@types/node": "^22.15.27",
+    "@types/sanitize-html": "^2.16.0",
     "shx": "^0.4.0",
     "typescript": "^5.8.3"
   },