@nataliapc/mcp-openmsx 1.1.15 → 1.2.2

package/README.md

@@ -9,7 +9,6 @@
 [![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.
@@ -25,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
 
@@ -74,6 +74,10 @@ 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.
 
+### 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?
@@ -118,18 +122,19 @@ 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).
 
-### 🟢 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)](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)
 
-[![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 +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"
       }
     }
   }
@@ -164,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
 {
@@ -173,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 |
@@ -195,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
@@ -230,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
@@ -254,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.15
  * @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
-export const PACKAGE_VERSION = "1.1.15";
+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,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: [{
@@ -1214,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

@@ -54,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);
@@ -229,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;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.1.15",
+  "version": "1.2.2",
   "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"
   ],