@nataliapc/mcp-openmsx 1.1.2 → 1.1.4

package/README.md

@@ -6,8 +6,6 @@ A [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) s
 
 This server provides comprehensive tools for MSX software development, testing, and automation through standardized MCP protocols.
 
-Currently, the MCP server requires Linux to run. It has not been tested on Windows or macOS, although it will likely work on the latter as well.
-
 ## 🎯 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:
@@ -66,6 +64,8 @@ The MCP server translates high-level commands from your Copilot AI into `TCL` co
 
 ## 🚀 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.
+
 ### 🟢 Basic Usage with VSCode
 
 * Install [Github Copilot extension](https://code.visualstudio.com/docs/copilot/overview)
@@ -86,7 +86,8 @@ The MCP server translates high-level commands from your Copilot AI into `TCL` co
   }
 }
 ```
-**Note:** Environment variables are optional.
+
+**Note:** Environment variables are optional. Customize them as you need.
 
 ### Streamed HTTP mode (more advanced)
 
@@ -136,6 +137,8 @@ Add to your `claude_desktop_config.json`:
 
 ## 🧑‍💻 Advanced Manual Usage
 
+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
 
 ```bash

package/dist/openmsx.js

@@ -5,7 +5,7 @@
  * @license GPL2
  */
 import fs from "fs/promises";
-import { extractDescriptionFromXML, decodeHtmlEntities } from "./utils.js";
+import { extractDescriptionFromXML, decodeHtmlEntities, encodeHtmlEntities } from "./utils.js";
 import { spawn } from 'child_process';
 import path from 'path';
 /**
@@ -144,7 +144,7 @@ export class OpenMSX {
     async emu_close() {
         return new Promise((resolve) => {
             if (!this.process) {
-                resolve("No emulator process running");
+                resolve("Error: No emulator process running");
                 return;
             }
             this.process.on('exit', () => {
@@ -153,7 +153,7 @@ export class OpenMSX {
                 resolve("Ok: Emulator process closed successfully");
             });
             this.process.on('error', (error) => {
-                resolve(`Error closing emulator: ${error.message}`);
+                resolve(`Error: error closing emulator: ${error.message}`);
             });
             // Try graceful shutdown first
             if (this.isConnected) {
@@ -184,7 +184,7 @@ export class OpenMSX {
         try {
             const response = await this.sendCommand('machine_info');
             if (response.startsWith('Error:')) {
-                return JSON.stringify({ error: response });
+                return response;
             }
             // Parse machine_info output into key-value pairs
             const parameters = response.trim().split(' ');
@@ -199,9 +199,7 @@ export class OpenMSX {
             return JSON.stringify(machineInfo, null, 2);
         }
         catch (error) {
-            return JSON.stringify({
-                error: `Failed to get machine status: ${error instanceof Error ? error.message : 'Unknown error'}`
-            });
+            return `Error: Failed to get machine status - ${error instanceof Error ? error.message : 'Unknown error'}`;
         }
     }
     /**
@@ -211,7 +209,7 @@ export class OpenMSX {
     async getMachineList(machinesDirectory) {
         // Read the machines directory
         let machines = [];
-        let machinesList = "No machines found.";
+        let machinesList = "Error: No machines found.";
         try {
             const allFiles = await fs.readdir(machinesDirectory);
             machines = await Promise.all(allFiles
@@ -222,14 +220,14 @@ export class OpenMSX {
                     description: await extractDescriptionFromXML(path.join(machinesDirectory, file))
                 };
             }));
+            if (machines.length !== 0) {
+                machinesList = JSON.stringify(machines, null, 2);
+            }
+            return machinesList;
         }
         catch (error) {
-            machinesList = 'Error reading machines directory: ' + error;
-        }
-        if (machines.length !== 0) {
-            machinesList = JSON.stringify(machines, null, 2);
+            return `Error: error reading machines directory - ${error instanceof Error ? error.message : error}`;
         }
-        return machinesList;
     }
     /**
      * Get the list of extensions available in the openMSX emulator
@@ -238,7 +236,7 @@ export class OpenMSX {
     async getExtensionList(extensionDirectory) {
         // Read the extensions directory
         let extensions = [];
-        let extensionsList = "No extensions found.";
+        let extensionsList = "Error: No extensions found.";
         try {
             const allFiles = await fs.readdir(extensionDirectory);
             extensions = await Promise.all(allFiles
@@ -249,14 +247,14 @@ export class OpenMSX {
                     description: await extractDescriptionFromXML(path.join(extensionDirectory, file))
                 };
             }));
+            if (extensions.length !== 0) {
+                extensionsList = JSON.stringify(extensions, null, 2);
+            }
+            return extensionsList;
         }
         catch (error) {
-            extensionsList = 'Error reading extensions directory: ' + error;
-        }
-        if (extensions.length !== 0) {
-            extensionsList = JSON.stringify(extensions, null, 2);
+            return `Error: error reading extensions directory - ${error instanceof Error ? error.message : error}`;
         }
-        return extensionsList;
     }
     ;
     /**
@@ -267,7 +265,7 @@ export class OpenMSX {
     async sendCommand(command) {
         try {
             // Send command
-            this.writeData(`<command>${command}</command>\n`);
+            this.writeData(`<command>${encodeHtmlEntities(command)}</command>\n`);
             // Read response using readData()
             const output = (await this.readData()).trim();
             // Look for reply tags in the output
@@ -285,7 +283,7 @@ export class OpenMSX {
             return decodeHtmlEntities(output.trim());
         }
         catch (error) {
-            return `Error: ${error instanceof Error ? error.message : 'Unknown error'}`;
+            return `Error: ${error instanceof Error ? error.message : error}`;
         }
     }
     /**

package/dist/server.js

@@ -6,7 +6,7 @@
  * through TCL commands via stdio.
  *
  * @package @nataliapc/mcp-openmsx
- * @version 1.1.2
+ * @version 1.1.4
  * @author Natalia Pujol Cremades (@nataliapc)
  * @license GPL2
  */
@@ -21,7 +21,7 @@ import fs from "fs/promises";
 import path from "path";
 import { openMSXInstance } from "./openmsx.js";
 // Version info for CLI
-const PACKAGE_VERSION = "1.1.2";
+const PACKAGE_VERSION = "1.1.4";
 // Defaults for openMSX paths
 var OPENMSX_EXECUTABLE = 'openmsx';
 var OPENMSX_SHARE_DIR = '/usr/share/openmsx';
@@ -39,7 +39,7 @@ function registerAllTools(server) {
     "emu_control", 
     // Description of the tool (what it does)
     "Controls an openMSX emulator. Commands: " +
-        "'launch [machine] [extensions]': opens a powered-on openMSX emulator; machine and extensions parameters can be specified; use 'machineList' and 'extensionList' tools to obtain valid values. " +
+        "'launch [machine] [extensions]': opens a powered-on openMSX emulator; you must wait some time waiting the machine is fully booted; machine and extensions parameters can be specified so use 'machineList' and 'extensionList' commands to obtain valid values. " +
         "'close': closes the openMSX emulator. " +
         "'powerOn': powers on the openMSX emulator. " +
         "'powerOff': powers off the openMSX emulator. " +
@@ -59,7 +59,7 @@ function registerAllTools(server) {
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, machine, extensions, emuspeed, seconds }) => {
-        let result = "Error";
+        let result = '';
         switch (command) {
             case "launch":
                 result = await openMSXInstance.emu_launch(OPENMSX_EXECUTABLE, machine || "", extensions || []);
@@ -69,23 +69,23 @@ function registerAllTools(server) {
                 break;
             case "powerOn":
                 result = await openMSXInstance.sendCommand('set power on');
-                result += result === "Ok" ? ": openMSX emulator powered on" : "";
+                result = result === "true" ? "openMSX emulator powered on" : "Error: " + result;
                 break;
             case "powerOff":
                 result = await openMSXInstance.sendCommand('set power off');
-                result += result === "Ok" ? ": openMSX emulator powered off" : "";
+                result = result === "false" ? "openMSX emulator powered off" : "Error: " + result;
                 break;
             case "reset":
                 result = await openMSXInstance.sendCommand('reset');
-                result += result === "Ok" ? ": openMSX emulator reset" : "";
+                result = result === "" ? "openMSX emulator reset successful" : "Error: " + result;
                 break;
             case 'getEmulatorSpeed':
                 result = await openMSXInstance.sendCommand('set speed');
-                result = !isNaN(Number(result)) ? `Current emulator speed is ${result}%` : result;
+                result = !isNaN(Number(result)) ? `Current emulator speed is ${result}%` : "Error: " + result;
                 break;
             case 'setEmulatorSpeed':
                 result = await openMSXInstance.sendCommand(`set speed ${emuspeed}`);
-                result = !isNaN(Number(result)) ? `Emulator speed set to ${emuspeed}%` : result;
+                result = !isNaN(Number(result)) ? `Emulator speed set to ${emuspeed}%` : "Error: " + result;
                 break;
             case "machineList":
                 result = await openMSXInstance.getMachineList(MACHINES_DIR);
@@ -206,13 +206,13 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "emu_vdp", 
     // Description of the tool (what it does)
-    "Manage VDP (Video Display Processor). Commands: " +
-        "'getPalette': return the current V9938/V9958 colors palette in format RGB333. " +
-        "'getRegisters': return all the VDP register values. " +
-        "'getRegisterValue <register>': return the value of a specific VDP register (0-31) in decimal format. " +
-        "'setRegisterValue <register> <value>': set a hexadecimal value to a specific VDP register (0-31). " +
-        "'screenGetMode': returns the current screen mode (0-12) as a number which would also be used for the basic command SCREEN. " +
-        "'screenGetFullText': return the full content of an MSX text screen (screen 0 or 1) as a string, useful for debugging. ", 
+    "Manage the VDP (Video Display Processor). Commands: " +
+        "'getPalette': returns the current V9938/V9958 color palette in RGB333 format. " +
+        "'getRegisters': returns all VDP register values. " +
+        "'getRegisterValue <register>': returns the value of a specific VDP register (0-31) in decimal format. " +
+        "'setRegisterValue <register> <value>': sets a hexadecimal value to a specific VDP register (0-31). " +
+        "'screenGetMode': returns the current screen mode (0-12) as a number, which matches the BASIC SCREEN command. " +
+        "'screenGetFullText': returns the full content of an MSX text screen (screen 0 or 1) as a string; PRIORITIZE this command to view screen content in text modes. ", 
     // Schema for the tool (input validation)
     {
         command: z.enum(["getPalette", "getRegisters", "getRegisterValue", "setRegisterValue", "screenGetMode", "screenGetFullText"]),
@@ -605,11 +605,13 @@ function registerAllTools(server) {
     "emu_keyboard", 
     // Description of the tool (what it does)
     "Send a text to the openMSX emulator. Commands: " +
-        "'sendText <text>': type a string in the emulated MSX, this command automatically press and release keys in the MSX keyboard matrix, is useful for automating tasks in BASIC, use \\r for Return key. ", 
+        "'sendText <text>': type a string in the emulated MSX, this command automatically press and release keys in the MSX keyboard matrix, is useful for automating tasks in BASIC. " +
+        "Note: each 'text' sent is limited to 200 characters, and the 'text' is sent as if it was typed in the MSX keyboard. " +
+        "Note: escape keys that needs it as Return key (use \\r), double quotes (use \\\"), etc...", 
     // Schema for the tool (input validation)
     {
         command: z.enum(["sendText"]),
-        text: z.string().min(1).max(100).optional().default(''), // Key to send to the emulator
+        text: z.string().min(1).max(200).optional().default(''), // Key to send to the emulator
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, text }) => {
@@ -662,8 +664,8 @@ function registerAllTools(server) {
                 catch (error) {
                     return getResponseContent([
                         'Error creating screenshot: ' + response,
-                        error instanceof Error ? error.message : String(error)
-                    ]);
+                        error instanceof Error ? error.message : String(error),
+                    ], true);
                 }
             case "to_file":
                 return getResponseContent([
@@ -693,12 +695,15 @@ function registerAllTools(server) {
         ]);
     });
 }
-function getResponseContent(response) {
+function getResponseContent(response, isError = false) {
+    // Check if any response line starts with "Error:" to automatically set isError to true
+    const hasError = isError || response.some(line => line.startsWith("Error:"));
     return {
         content: response.map(line => ({
             type: "text",
             text: line == '' ? "Ok" : line,
         })),
+        isError: hasError
     };
 }
 // ============================================================================
@@ -767,7 +772,7 @@ Environment variables:
 
 Examples:
   mcp-openmsx                    # stdio transport
-  mcp-openmsx http              # HTTP transport
+  mcp-openmsx http               # HTTP transport
   MCP_TRANSPORT=http mcp-openmsx # HTTP via environment
 `);
 }

package/dist/utils.js

@@ -32,16 +32,16 @@ export function decodeHtmlEntities(text) {
         '>': '>',
         '&': '&',
         '"': '"',
+        ' ': ' ',
         ''': "'",
         '/': '/',
         '`': '`',
         '=': '=',
+        ''': "'",
         ''': "'",
         '/': '/',
         '`': '`',
         '=': '=',
-        ''': "'",
-        ' ': ' ',
         '
': '\n',
         '
': '\n',
         '
': '\n',
@@ -52,3 +52,29 @@ export function decodeHtmlEntities(text) {
         return htmlEntities[entity] || entity;
     });
 }
+/**
+ * Encode a plain text to HTML entities, also escaping characters with ASCII >= 127
+ * @param text - String to encode
+ * @returns string - String with HTML entities encoded
+ */
+export function encodeHtmlEntities(text) {
+    const htmlEntities = {
+        '<': '&lt;',
+        '>': '&gt;',
+        '&': '&amp;',
+        '"': '&quot;',
+        "'": '&apos;',
+        '=': '&#61;',
+        '/': '&#47;',
+    };
+    return text.replace(/[\u00A0-\uFFFF<>&"'`=\/]/g, (char) => {
+        if (htmlEntities[char]) {
+            return htmlEntities[char];
+        }
+        const code = char.charCodeAt(0);
+        if (code >= 127) {
+            return `&#${code};`;
+        }
+        return char;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",