@nataliapc/mcp-openmsx 1.1.14 → 1.2.2

package/README.md

@@ -2,6 +2,13 @@
 
 *"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.
@@ -17,7 +24,8 @@ This project creates a bridge between modern AI-assisted development (e.g. GitHu
 - **Video Control**: VDP register manipulation and screen capture.
 - **Memory Operations**: Read/write RAM, VRAM, and I/O port access.
 - **Automation**: Keyboard input simulation and savestate management.
-- **Dual Transport**: Support for both stdio and HTTP transports.
+- **Vector DB Integration**: Query an embedded vector database with MSX resources for development support.
+- **Hybrid Mode**: This MCP server supports hybrid access mode (_STDIO_ and _HTTP_ transports).
 
 ## 🏗️ Architecture
 
@@ -64,6 +72,11 @@ 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.
+
+### Documentation Tools
+- `vector_db_query`: Query the Vector DB resources to obtain information about MSX systems, cartridges, and other development resources.
+- `msxdocs_resource_get`: Retrieve MCP resources for MCP clients that don't support MCP resources.
 
 ## 📚 Available MCP Resources
 
@@ -85,10 +98,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 +112,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.
 
@@ -107,12 +122,16 @@ The rights to these resources belong to their respective authors and are distrib
 
 ## 🚀 Quick Start
 
-You can use this MCP server in this basic way with the [precompiled NPM package](https://www.npmjs.com/package/@nataliapc/mcp-openmsx). You may need to have `nodejs` installed for this to work.
+You can use this MCP server in this basic way with the [precompiled NPM package](https://www.npmjs.com/package/@nataliapc/mcp-openmsx).
+
+### 🟢 Quick installation with VSCode
 
-### 🟢 Basic Usage with VSCode
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?style=flat&logo=visualstudiocode&logoColor=ffffff)](vscode:mcp/install?%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)
-* Add to your workspace a file `.vscode/mcp.json` with:
+* Use the **Install in VS Code** button above to install the MCP server in your VSCode workspace.
+* Or add to your workspace a file `.vscode/mcp.json` with the json configuration below.
 
 ### STDIO mode (recommended)
 
@@ -123,7 +142,7 @@ You can use this MCP server in this basic way with the [precompiled NPM package]
       "command": "npx",
       "args": ["@nataliapc/mcp-openmsx"],
       "env": {
-        "OPENMSX_SHARE_DIR": "/usr/share/openmsx"
+        "OPENMSX_SHARE_DIR": "C:\the\location\of\your\openmsx\share\folder"
       }
     }
   }
@@ -150,7 +169,9 @@ You can use this MCP server in this basic way with the [precompiled NPM package]
 
 ### 🟢 Basic Usage with Claude Desktop
 
-Add to your `claude_desktop_config.json`:
+Follow [these instrutions](https://modelcontextprotocol.io/quickstart/user#for-claude-desktop-users) to access Claude's `claude_desktop_config.json` file.
+
+Edit it to include the following JSON entry:
 
 ```json
 {
@@ -159,13 +180,15 @@ Add to your `claude_desktop_config.json`:
       "command": "npx",
       "args": ["@nataliapc/mcp-openmsx"],
       "env": {
-        "OPENMSX_SHARE_DIR": "/usr/share/openmsx"
+        "OPENMSX_SHARE_DIR": "C:\the\location\of\your\openmsx\share\folder"
       }
     }
   }
 }
 ```
 
+**Note:** Environment variables are optional. Customize them as you need.
+
 ### 🟢 Environment Variables
 
 | Variable | Description | Default Value | Example |
@@ -181,6 +204,8 @@ Add to your `claude_desktop_config.json`:
 
 ## 🧑‍💻 Advanced Manual Usage
 
+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.
 
 ### Manual installation
@@ -216,10 +241,11 @@ MCP_TRANSPORT=http mcp-openmsx
 mcp-openmsx http
 ```
 
-
 ## 💡 Development
 
-### Prerequisites
+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
 
 - Node.js >= 18.0.0
 - TypeScript
@@ -240,7 +266,6 @@ npm run build
 npm run dev
 ```
 
-
 ## 🪪 License
 
 GPL2 License - see [LICENSE](LICENSE) file for details.

package/dist/server.js

@@ -6,7 +6,6 @@
  * through TCL commands via stdio.
  *
  * @package @nataliapc/mcp-openmsx
- * @version 1.1.14
  * @author Natalia Pujol Cremades (@nataliapc)
  * @license GPL2
  */
@@ -20,10 +19,14 @@ import express from "express";
 import fs from "fs/promises";
 import path from "path";
 import { openMSXInstance } from "./openmsx.js";
+import { VectorDB } from "./vectordb.js";
 import { fetchCleanWebpage, addFileExtension, listResourcesDirectory, encodeTypeText, isErrorResponse, getResponseContent } from "./utils.js";
-// Version info for CLI
-const PACKAGE_VERSION = "1.1.14";
+import { createRequire } from 'module';
+// 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");
 // Defaults for openMSX paths
 var OPENMSX_EXECUTABLE = 'openmsx';
 var OPENMSX_SHARE_DIR = '/usr/share/openmsx';
@@ -861,96 +864,152 @@ The parameter scrbasename is the name of the filename (without path) to save the
             response !== undefined ? response : `Error: No response for command "${command}".`
         ]);
     });
+    server.registerTool(
+    // Name of the tool (used to call it)
+    "vector_db_query", {
+        title: "Vector DB query from resources",
+        // Description of the tool (what it does)
+        description: `Query the Vector DB resources to obtain information about MSX system, cartridges, programming, and other development resources.
+The query is a string used to search within the Vector DB resources; it is case-insensitive and may contain spaces.
+The response is the list of the top 10 result resources that match the query, including their score, title, and resource URI, and are sorted in descending order by proximity score to the query.
+**Important Note**: The Vector DB resources are in english, japanese, or dutch.
+`,
+        // Schema for the tool (input validation)
+        inputSchema: {
+            query: z.string().min(2).max(100).describe("Query string to search in the Vector DB resources, case-insensitive and may contain spaces."),
+        },
+        // outputSchema: {
+        // 	results: z.array(z.object({
+        // 		score: z.number().describe("Proximity score of the result to the query, higher is better."),
+        // 		title: z.string().describe("Title of the resource."),
+        // 		uri: z.string().describe("URI of the resource, which can be used to access the resource."),
+        // 		document: z.string().describe("Document chunk of the resource, retrieved from the Vector DB."),
+        // 		id: z.string().describe("Unique resource chunk ID, used internally by the Vector DB."),
+        // 	}))
+        // },
+    }, 
+    // Handler for the tool (function to be executed when the tool is called)
+    async ({ query }) => {
+        const results = await VectorDB.getInstance().query(query);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(results),
+                }],
+            results: results,
+            isError: false,
+        };
+    });
     // ============================================================================
     // MSX Documentation resources
     const resdocs = (await listResourcesDirectory(resourcesDir)).sort();
+    const regResources = [];
     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`);
-        const tocContent = JSON.parse(await fs.readFile(tocFile, 'utf8'));
+        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()).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);
+            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',
+                }, 
+                // 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 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"
+    ];
     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 url = `https://www.msx.org/wiki/${instruction}`;
+        let instruction = variables.instruction;
         let resourceContent;
         let mimeType;
+        // urldecode the instruction to avoid issues with special characters
+        instruction = decodeURIComponent(instruction).replaceAll(' ', '_');
         try {
-            [resourceContent, mimeType] = await fetchCleanWebpage(url);
+            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 error;
+            throw new Error(`Error reading resource programming/basic_wiki/${instruction}: ${error instanceof Error ? error.message : String(error)}`);
         }
         return {
             contents: [{
@@ -960,6 +1019,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 +1197,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 +1206,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}`);
@@ -1134,6 +1262,7 @@ async function main() {
         MACHINES_DIR = `${OPENMSX_SHARE_DIR}machines`;
         EXTENSIONS_DIR = `${OPENMSX_SHARE_DIR}extensions`;
     }
+    VectorDB.setIndexDirectory(vectorDbDir);
     // Detect transport type from environment or command line
     const transportType = process.env.MCP_TRANSPORT || process.argv[2] || 'stdio';
     if (transportType === 'http') {

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
@@ -51,13 +54,13 @@ export async function addFileExtension(filePath) {
     return ['text/plain', filePath];
 }
 /**
- * List all folders in the resources directory
+ * List all folders and subfolders in the resources directory
  * @param resourcesDir - Path to the resources directory
  * @returns Promise<string[]> - List of folder names in the resources directory
  */
 export async function listResourcesDirectory(resourcesDir) {
     try {
-        const directories = await fs.readdir(resourcesDir, { withFileTypes: true });
+        const directories = await fs.readdir(resourcesDir, { withFileTypes: true, recursive: true });
         const folderNames = directories
             .filter(dirent => dirent.isDirectory())
             .map(dirent => dirent.name);
@@ -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)
@@ -190,3 +229,11 @@ export function getResponseContent(response, isError = false) {
         isError: hasError
     };
 }
+/*
+ * Sleep for a specified number of milliseconds
+ * @param ms - Number of milliseconds to sleep
+ * @returns Promise that resolves after the specified time
+ */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/dist/vectordb.js

@@ -0,0 +1,60 @@
+/**
+ * Vector Database wrapper class
+ *
+ * @author Natalia Pujol Cremades (@nataliapc)
+ * @license GPL2
+ */
+import { LocalIndex } from 'vectra';
+import embeddings from '@themaximalist/embeddings.js';
+export class VectorDB {
+    static instance;
+    static vectorDbDir = '../vector-db';
+    index;
+    static getInstance() {
+        if (!VectorDB.instance) {
+            VectorDB.instance = new VectorDB();
+        }
+        return VectorDB.instance;
+    }
+    static setIndexDirectory(dbDir) {
+        VectorDB.vectorDbDir = dbDir;
+    }
+    constructor(dbDir = VectorDB.vectorDbDir) {
+        this.index = new LocalIndex(dbDir);
+        if (!this.initDatabase()) {
+            throw new Error('Failed to initialize VectorDB: Index does not exist');
+        }
+    }
+    async initDatabase() {
+        return await this.index.isIndexCreated();
+    }
+    async getVector(text) {
+        const response = await embeddings(text);
+        if (!response || !Array.isArray(response) || response.length === 0) {
+            throw new Error('Failed to generate embedding vector');
+        }
+        return response;
+    }
+    async query(text) {
+        const vector = await this.getVector(text);
+        let results = [];
+        try {
+            results = await this.index.queryItems(vector, text, 10);
+            if (results.length > 0) {
+                return results.map(result => {
+                    return {
+                        score: result.score.toFixed(4),
+                        uri: result.item.metadata?.uri || 'unknown',
+                        title: result.item.metadata?.title || 'unknown',
+                        document: String(result.item.metadata?.document || ''),
+                        id: result.item.metadata?.id || 'unknown',
+                    };
+                });
+            }
+        }
+        catch (error) {
+            throw new Error(`Query failed: ${error}`);
+        }
+        return results;
+    }
+}