@nataliapc/mcp-openmsx 1.1.15 → 1.2.3

package/README.md

@@ -9,12 +9,27 @@
 [![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.
 
-## 🎯 Project Overview
+## 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 installation with **VSCode**](#quick-installation-with-vscode)
+  - [Basic installation with **Claude Desktop**](#basic-installation-with-claude-desktop)
+  - [Environment Variables](#environment-variables)
+- [Advanced manual usage](#advanced-manual-usage)
+- [Development](#development)
+- [License](#license)
+- [Support](#support)
+- [Contributing](#contributing)
+
+## Project Overview
 
 This project creates a bridge between modern AI-assisted development (e.g. GitHub Copilot, Claude Desktop) and retro computing (MSX systems) by providing:
 
@@ -25,30 +40,51 @@ 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
+## Architecture
 
 ```mermaid
 flowchart TB
-  subgraph subGraph0["Your computer for develop"]
-    HOST["Your AI dev companion<br>(mcp client support)"]
-    MCP(["mcp-openmsx<br>(mcp server)"])
+  %%{init: {'flowchart': {'curve':'monotoneX' }}}%%
+
+  subgraph yourComputerGroup[" "]
+    HOST["Your AI dev companion<br>(MCP Client support)"]
     EMU["openMSX emulator<br>(local instance)"]
-    HOST <--&nbsp;MCP&nbsp;<br>&nbsp;protocol&nbsp;--> MCP
-    MCP <--&nbsp;stdio&nbsp;--> EMU
+
+    subgraph mcpGroup["**mcp-openmsx**"]
+      MCP["MCP Server<br>stdio / http"]
+      TOOLS["MCP Tools"]
+      VECTORDB[("Embeddings RAG<br>(Vector Database)")]
+      RESOURCES["MCP Resources"]
+      LOCALDATA["Local data<br>(inner documentation)"]
+    end
+    EXTDATA["External data<br>(webpages)"]
+
+    HOST <--"_MCP<br>&nbsp;protocol&nbsp;_"--> MCP
+    MCP <--> TOOLS & RESOURCES
+    TOOLS <--"_&nbsp;Query&nbsp;_"--> VECTORDB
+    TOOLS <--"_&nbsp;Console commands&nbsp;_"---> EMU
+    RESOURCES <--_&nbsp;http&nbsp;_---> EXTDATA
+    RESOURCES <--> LOCALDATA
   end
-    HOST@{ shape: rounded}
-    EMU@{ shape: rounded}
-    style subGraph0 color:#fff,fill:#5555
-    style HOST color:#000000,fill:#BBDEFB,stroke-width:4px,stroke-dasharray:0
-    style MCP color:#000000,fill:#FFF9C4
-    style EMU color:#FFFFFF,fill:#0000FF,stroke-width:4px,stroke-dasharray:0
+
+  HOST@{ shape: rounded }
+  MCP@{ shape: rounded }
+  EMU@{ shape: rounded }
+  LOCALDATA@{ shape: docs }
+  EXTDATA@{ shape: docs }
+  style yourComputerGroup color:#fff,fill:#4444,text-align:left
+  style mcpGroup color:#fff,fill:#4444
+  style HOST color:#000000,fill:#BBDEFB,stroke-width:4px,stroke-dasharray:0
+  style MCP color:#000000,fill:#FFF9C4
+  style EMU color:#FFFFFF,fill:#0000FF,stroke-width:4px,stroke-dasharray:0
 ```
 
-The MCP server translates high-level commands from your Copilot AI into `TCL` commands to control `openMSX`, enabling automated MSX software _testing_ and _debugging_.
+The MCP server translates high-level natural language commands from your Copilot AI into `TCL` commands to control `openMSX`, enabling automated MSX software testing and debugging.
 
-## 🛠️ Available MCP Tools
+## Available MCP Tools
 
 ### Emulator Control Tools
 - `emu_control`: Controls an openMSX emulator: _`launch`, `close`, `powerOn`, `powerOff`, `reset`, `getEmulatorSpeed`, `setEmulatorSpeed`, `machineList`, `extensionList`, `wait`_.
@@ -74,7 +110,11 @@ The MCP server translates high-level commands from your Copilot AI into `TCL` co
 - `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
+### 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
 
 ### What are MCP Resources?
 
@@ -116,20 +156,21 @@ Thanks to the authors of these resources, who have made them available under var
 
 The rights to these resources belong to their respective authors and are distributed under the licenses they have defined.
 
-## 🚀 Quick Start
+## 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).
 
-### 🟢 Basic Usage with VSCode
+### Quick installation with VSCode
 
+[![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)
-* Add to your workspace a file `.vscode/mcp.json` with:
+* 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.
 
 ### 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": {
@@ -137,7 +178,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"
       }
     }
   }
@@ -162,9 +203,11 @@ You can use this MCP server in this basic way with the [precompiled NPM package]
 
 **Note:** The MCP HTTP Server must be running standalone in the same computer or in another (`make run_http`).
 
-### 🟢 Basic Usage with Claude Desktop
+### Basic Installation 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
 {
@@ -173,14 +216,16 @@ 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"
       }
     }
   }
 }
 ```
 
-### 🟢 Environment Variables
+**Note:** Environment variables are optional. Customize them as you need.
+
+### Environment Variables
 
 | Variable | Description | Default Value | Example |
 |----------|-------------|---------------|---------|
@@ -193,7 +238,9 @@ Add to your `claude_desktop_config.json`:
 | `MCP_HTTP_PORT` | Port number for HTTP transport mode | `3000` | `8080` |
 
 
-## 🧑‍💻 Advanced Manual Usage
+## 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.
 
@@ -230,10 +277,11 @@ MCP_TRANSPORT=http mcp-openmsx
 mcp-openmsx http
 ```
 
+## Development
 
-## 💡 Development
+This is not needed for using the MCP server, but if you want to contribute or modify the code, follow these steps.
 
-### Prerequisites
+### Prerequisites to build
 
 - Node.js >= 18.0.0
 - TypeScript
@@ -254,18 +302,17 @@ npm run build
 npm run dev
 ```
 
-
-## 🪪 License
+## License
 
 GPL2 License - see [LICENSE](LICENSE) file for details.
 
 
-## 🆘 Support
+## Support
 
 If you need help, or have questions or suggestions, please open an issue on the [GitHub Issues](https://github.com/nataliapc/mcp-openmsx/issues) page or check the project discussions.
 
 
-## 🤝 Contributing
+## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 

package/dist/server.js

@@ -6,7 +6,6 @@
  * through TCL commands via stdio.
  *
  * @package @nataliapc/mcp-openmsx
- * @version 1.1.15
  * @author Natalia Pujol Cremades (@nataliapc)
  * @license GPL2
  */
@@ -20,18 +19,22 @@ import express from "express";
 import fs from "fs/promises";
 import path from "path";
 import { openMSXInstance } from "./openmsx.js";
-import { fetchCleanWebpage, addFileExtension, listResourcesDirectory, encodeTypeText, isErrorResponse, getResponseContent } from "./utils.js";
-// Version info for CLI
-export const PACKAGE_VERSION = "1.1.15";
+import { VectorDB } from "./vectordb.js";
+import { createRequire } from 'module';
+import { detectOpenMSXShareDir, fetchCleanWebpage, addFileExtension, listResourcesDirectory, encodeTypeText, isErrorResponse, getResponseContent } from "./utils.js";
+// Dynamically obtain PACKAGE_VERSION from package.json at runtime
+const require = createRequire(import.meta.url);
+export const PACKAGE_VERSION = require('../package.json').version;
 const resourcesDir = path.join(path.dirname(new URL(import.meta.url).pathname), "../resources");
+const vectorDbDir = path.join(path.dirname(new URL(import.meta.url).pathname), "../vector-db");
 // Defaults for openMSX paths
 var OPENMSX_EXECUTABLE = 'openmsx';
-var OPENMSX_SHARE_DIR = '/usr/share/openmsx';
+var OPENMSX_SHARE_DIR = '';
 var OPENMSX_REPLAYS_DIR = '';
 var OPENMSX_SCREENSHOT_DIR = '';
 var OPENMSX_SCREENDUMP_DIR = '';
-var MACHINES_DIR = `${OPENMSX_SHARE_DIR}/machines`;
-var EXTENSIONS_DIR = `${OPENMSX_SHARE_DIR}/extensions`;
+var MACHINES_DIR = '';
+var EXTENSIONS_DIR = '';
 // ============================================================================
 // Tools available in the MCP server
 // https://modelcontextprotocol.io/docs/concepts/tools#tool-definition-structure
@@ -625,12 +628,12 @@ async function registerAllTools(server) {
                 break;
             case "saveReplay":
                 if (filename)
-                    filename = `"${OPENMSX_REPLAYS_DIR}${filename}"`;
+                    filename = path.join(OPENMSX_REPLAYS_DIR, filename);
                 tclCommand = `reverse savereplay ${filename || ''}`;
                 break;
             case "loadReplay":
                 if (filename)
-                    filename = `"${OPENMSX_REPLAYS_DIR}${filename}"`;
+                    filename = path.join(OPENMSX_REPLAYS_DIR, filename);
                 tclCommand = `reverse loadreplay ${filename}`;
                 break;
             default:
@@ -692,7 +695,7 @@ async function registerAllTools(server) {
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command }) => {
-        const openmsxCommand = `screenshot -raw -prefix "${OPENMSX_SCREENSHOT_DIR}mcp_"`;
+        const openmsxCommand = `screenshot -raw -prefix "${path.join(OPENMSX_SCREENSHOT_DIR, 'mcp_')}"`;
         const response = await openMSXInstance.sendCommand(openmsxCommand);
         switch (command) {
             case "as_image":
@@ -748,7 +751,7 @@ The parameter scrbasename is the name of the filename (without path) to save the
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ scrbasename }) => {
-        const openmsxCommand = `save_msx_screen "${OPENMSX_SCREENDUMP_DIR + scrbasename}"`;
+        const openmsxCommand = `save_msx_screen "${path.join(OPENMSX_SCREENDUMP_DIR, scrbasename)}"`;
         const response = await openMSXInstance.sendCommand(openmsxCommand);
         return getResponseContent([
             isErrorResponse(response) ? 'Fail:' : 'Screendump file saved as:',
@@ -861,16 +864,61 @@ 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 || '';
+            const itemName = path.parse(item.uri.split('/').pop()).base || '';
             let resource = {
                 uri: item.uri,
                 filename: '',
@@ -926,18 +974,18 @@ The parameter scrbasename is the name of the filename (without path) to save the
     ;
     // 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"
+        "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,
@@ -949,19 +997,19 @@ The parameter scrbasename is the name of the filename (without path) to save the
         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: [{
@@ -1101,7 +1149,8 @@ Environment variables:
   OPENMSX_SHARE_DIR       openMSX share directory
   OPENMSX_SCREENSHOT_DIR  Screenshot output directory
   OPENMSX_SCREENDUMP_DIR  Screen dump output directory
-  MCP_HTTP_PORT          HTTP server port (default: 3000)
+  OPENMSX_REPLAYS_DIR     Replay output directory
+  MCP_HTTP_PORT           HTTP server port (default: 3000)
 
 Examples:
   mcp-openmsx                    # stdio transport
@@ -1201,19 +1250,31 @@ async function main() {
         OPENMSX_EXECUTABLE = process.env.OPENMSX_EXECUTABLE;
     }
     if (process.env.OPENMSX_SCREENSHOT_DIR && process.env.OPENMSX_SCREENSHOT_DIR !== '') {
-        OPENMSX_SCREENSHOT_DIR = process.env.OPENMSX_SCREENSHOT_DIR + path.sep;
+        OPENMSX_SCREENSHOT_DIR = process.env.OPENMSX_SCREENSHOT_DIR;
     }
     if (process.env.OPENMSX_SCREENDUMP_DIR && process.env.OPENMSX_SCREENDUMP_DIR !== '') {
-        OPENMSX_SCREENDUMP_DIR = process.env.OPENMSX_SCREENDUMP_DIR + path.sep;
+        OPENMSX_SCREENDUMP_DIR = process.env.OPENMSX_SCREENDUMP_DIR;
     }
     if (process.env.OPENMSX_REPLAYS_DIR && process.env.OPENMSX_REPLAYS_DIR !== '') {
-        OPENMSX_REPLAYS_DIR = process.env.OPENMSX_REPLAYS_DIR + path.sep;
+        OPENMSX_REPLAYS_DIR = process.env.OPENMSX_REPLAYS_DIR;
+    }
+    if (process.env.OPENMSX_SHARE_DIR && process.env.OPENMSX_SHARE_DIR !== '') {
+        OPENMSX_SHARE_DIR = process.env.OPENMSX_SHARE_DIR;
     }
-    if (process.env.OPENMSX_SHARE_DIR) {
-        OPENMSX_SHARE_DIR = process.env.OPENMSX_SHARE_DIR + path.sep;
-        MACHINES_DIR = `${OPENMSX_SHARE_DIR}machines`;
-        EXTENSIONS_DIR = `${OPENMSX_SHARE_DIR}extensions`;
+    else {
+        // Auto-detect openMSX share directory if not set
+        const detectedShareDir = detectOpenMSXShareDir();
+        if (detectedShareDir) {
+            OPENMSX_SHARE_DIR = detectedShareDir;
+            console.warn(`Auto-detected openMSX share folder: ${OPENMSX_SHARE_DIR}`);
+        }
+        else {
+            console.error("Error: OPENMSX_SHARE_DIR environment variable is not set and could not be auto-detected.");
+        }
     }
+    MACHINES_DIR = path.join(OPENMSX_SHARE_DIR, 'machines');
+    EXTENSIONS_DIR = path.join(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

@@ -10,6 +10,38 @@ import mime from 'mime-types';
 import { gunzipSync } from 'zlib';
 import { PACKAGE_VERSION } from "./server.js";
 import sanitizeHtml from 'sanitize-html';
+import { existsSync } from "fs";
+import os from "os";
+/**
+ * Detect the openMSX share directory by checking various methods
+ * @returns string - The detected share directory or an empty string if not found
+ */
+export function detectOpenMSXShareDir() {
+    try {
+        // Check standard locations
+        const possiblePaths = [
+            // Linux paths
+            path.join(os.homedir(), '.openMSX', 'share'),
+            '/usr/local/share/openmsx',
+            '/usr/share/openmsx',
+            // Windows paths
+            path.join(os.homedir(), 'Documents', 'openMSX', 'share'),
+            path.join(process.env.PROGRAMFILES || 'C:\\Program Files', 'openMSX', 'share'),
+            // macOS paths
+            path.join(os.homedir(), 'Library', 'Application Support', 'openMSX', 'share'),
+            '/Applications/openMSX.app/Contents/Resources/share',
+        ];
+        for (const dirPath of possiblePaths) {
+            if (existsSync(dirPath) && existsSync(path.join(dirPath, 'machines'))) {
+                return dirPath;
+            }
+        }
+    }
+    catch (error) {
+        console.error('Error detecting openMSX share directory:', error);
+    }
+    return '';
+}
 /**
  * Extract description from XML file
  * @param filePath - Full path to the XML file
@@ -54,13 +86,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);
@@ -229,3 +261,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,61 @@
+/**
+ * Vector Database wrapper class
+ *
+ * @author Natalia Pujol Cremades (@nataliapc)
+ * @license GPL2
+ */
+import path from 'path';
+import { LocalIndex } from 'vectra';
+import embeddings from '@themaximalist/embeddings.js';
+export class VectorDB {
+    static instance;
+    static vectorDbDir = path.join('..', '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;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.1.15",
+  "version": "1.2.3",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",
@@ -38,17 +38,21 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.15.1",
+    "@modelcontextprotocol/sdk": "^1.16.0",
+    "@themaximalist/embeddings.js": "^0.1.3",
     "@types/express": "^5.0.2",
+    "@xenova/transformers": "^2.17.2",
+    "debug": "^4.4.1",
     "express": "^5.1.0",
     "sanitize-html": "^2.17.0",
     "tsx": "^4.7.1",
+    "vectra": "^0.11.1",
     "zod": "^3.24.4"
   },
   "devDependencies": {
     "@modelcontextprotocol/inspector": "^0.15.0",
     "@types/mime-types": "^3.0.1",
-    "@types/node": "^22.15.27",
+    "@types/node": "^24.0.15",
     "@types/sanitize-html": "^2.16.0",
     "shx": "^0.4.0",
     "typescript": "^5.8.3"
@@ -56,6 +60,7 @@
   "files": [
     "dist/**/*",
     "resources/**/*",
+    "vector-db/**/*",
     "README.md",
     "LICENSE"
   ],