@nataliapc/mcp-openmsx 1.0.0 → 1.0.2

package/README.md

@@ -62,49 +62,19 @@ The MCP server translates high-level commands from your Copilot AI into `TCL` co
 - `screen_shot`: Capture emulator screen: _`as_image`, `to_file`_.
 - `screen_dump`: Export screen data as BASIC BSAVE.
 
-## 🚀 Quick Start
-
-### Manual installation
-
-```bash
-npm install -g @nataliapc/mcp-openmsx
-```
-
-### Configuration
-
-Set optional environment variables to customize the server:
-
-```bash
-export OPENMSX_EXECUTABLE="openmsx"
-export OPENMSX_SHARE_DIR="/usr/share/openmsx"
-export OPENMSX_SCREENSHOT_DIR="/my_project/screenshots"
-export OPENMSX_SCREENDUMP_DIR="/my_project/screendumps"
-export MCP_HTTP_PORT=3000
-```
-
-### Manuel usage
-
-#### As MCP Server (stdio)
 
-```bash
-mcp-openmsx
-```
+## 🚀 Quick Start
 
-#### As HTTP Server
+### 🟢 Basic Usage with VSCode
 
-```bash
-MCP_TRANSPORT=http mcp-openmsx
-# or
-mcp-openmsx http
-```
-
-### Basic Usage with Claude Desktop
+* Install [Github Copilot extension](https://code.visualstudio.com/docs/copilot/overview)
+* Add to your workspace a file `.vscode/mcp.json` with:
 
-Add to your `claude_desktop_config.json`:
+### STDIO mode (recommended)
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "mcp-openmsx": {
       "command": "npx",
       "args": ["@nataliapc/mcp-openmsx"],
@@ -115,44 +85,87 @@ Add to your `claude_desktop_config.json`:
   }
 }
 ```
+**Note:** Environment variables are optional.
 
-### Basic Usage with VSCode
-
-* Install [Github Copilot extension](https://code.visualstudio.com/docs/copilot/overview)
-* Add to your workspace a file `.vscode/mcp.json` with:
-
-#### stdio mode
+### Streamed HTTP mode (more advanced)
 
 ```json
 {
   "servers": {
     "mcp-openmsx": {
-      "command": "npx",
-      "args": ["@nataliapc/mcp-openmsx"],
-      "env": {
-        "OPENMSX_SHARE_DIR": "/usr/share/openmsx"
-      }
+      "type": "http",
+      "url": "http://localhost:3000/mcp",
+      "headers": { }
     }
   }
 }
 ```
-**Note:** Environment variables are optional.
 
-#### http mode
+**Note:** The MCP HTTP Server must be running standalone in the same computer or in another (`make run_http`).
+
+### 🟢 Basic Usage with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
 
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "mcp-openmsx": {
-      "type": "http",
-      "url": "http://localhost:3000/mcp",
-      "headers": { }
+      "command": "npx",
+      "args": ["@nataliapc/mcp-openmsx"],
+      "env": {
+        "OPENMSX_SHARE_DIR": "/usr/share/openmsx"
+      }
     }
   }
 }
 ```
 
-**Note:** The MCP HTTP Server must be running standalone in the same computer or in another (`make run_http`).
+### 🟢 Environment Variables
+
+| Variable | Description | Default Value | Example |
+|----------|-------------|---------------|---------|
+| `OPENMSX_EXECUTABLE` | Path or command to the openMSX executable | `openmsx` | `/usr/local/bin/openmsx` |
+| `OPENMSX_SHARE_DIR` | Directory containing openMSX data files (machines, extensions, etc.) | System dependent | `/home/myuser/.openmsx/share` |
+| `OPENMSX_SCREENSHOT_DIR` | Directory where screenshots will be saved | Current working directory | `/myproject/screenshots` |
+| `OPENMSX_SCREENDUMP_DIR` | Directory where screen dumps will be saved | Current working directory | `/myproject/screendumps` |
+| `MCP_TRANSPORT` | Transport mode (`stdio` or `http`) | `stdio` | `http` |
+| `MCP_HTTP_PORT` | Port number for HTTP transport mode | `3000` | `8080` |
+
+
+## 🧑‍💻 Advanced Manual Usage
+
+### Manual installation
+
+```bash
+npm install -g @nataliapc/mcp-openmsx
+```
+
+### Manual set of Environment Variables
+
+Set optional environment variables to customize the server:
+
+```bash
+export OPENMSX_EXECUTABLE="openmsx"
+export OPENMSX_SHARE_DIR="/usr/share/openmsx"
+export OPENMSX_SCREENSHOT_DIR="/my_project/screenshots"
+export OPENMSX_SCREENDUMP_DIR="/my_project/screendumps"
+export MCP_HTTP_PORT=3000
+```
+
+### As MCP Server (stdio)
+
+```bash
+mcp-openmsx
+```
+
+### As HTTP Server
+
+```bash
+MCP_TRANSPORT=http mcp-openmsx
+# or
+mcp-openmsx http
+```
 
 
 ## 💡 Development
@@ -178,16 +191,19 @@ npm run build
 npm run dev
 ```
 
-## License
+
+## 🪪 License
 
 GPL2 License - see [LICENSE](LICENSE) file for details.
 
-## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+## 🆘 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.
 
-For issues and questions, please use the [GitHub Issues](https://github.com/nataliapc/mcp-openmsx/issues) page.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 ---

package/dist/openmsx.js

@@ -5,7 +5,7 @@
  * @license GPL2
  */
 import fs from "fs/promises";
-import { extractDescriptionFromXML } from "./utils.js";
+import { extractDescriptionFromXML, decodeHtmlEntities } from "./utils.js";
 import { spawn } from 'child_process';
 /**
  * OpenMSX class for controlling the openMSX emulator via TCL commands over TCP socket
@@ -259,14 +259,16 @@ export class OpenMSX {
             // Look for reply tags in the output
             const replyMatch = output.match(/<reply result="(ok|nok)"[^>]*>(.*?)<\/reply>/s);
             if (replyMatch) {
+                const outputContent = decodeHtmlEntities(replyMatch[2].trim());
                 if (replyMatch[1] === 'ok') {
-                    return replyMatch[2];
+                    return outputContent;
                 }
                 else {
-                    return `Error: ${replyMatch[2].trim()}`;
+                    return `Error: ${outputContent}`;
                 }
             }
-            return output.trim(); // Return raw output if no reply tag found
+            // Return raw output with HTML entities decoded
+            return decodeHtmlEntities(output.trim());
         }
         catch (error) {
             return `Error: ${error instanceof Error ? error.message : 'Unknown error'}`;

package/dist/server.js

@@ -6,7 +6,7 @@
  * through TCL commands via stdio.
  *
  * @package @nataliapc/mcp-openmsx
- * @version 1.0.0
+ * @version 1.0.2
  * @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.0.0";
+const PACKAGE_VERSION = "1.0.2";
 // Defaults for openMSX paths
 var OPENMSX_EXECUTABLE = 'openmsx';
 var OPENMSX_SHARE_DIR = '/usr/share/openmsx';
@@ -112,7 +112,7 @@ function registerAllTools(server) {
         return {
             content: [{
                     type: "text",
-                    text: result,
+                    text: result === '' ? 'Ok' : result,
                 }],
         };
     });
@@ -178,7 +178,7 @@ function registerAllTools(server) {
         return {
             content: [{
                     type: "text",
-                    text: response === "" ? "Ok" : response,
+                    text: response === '' ? 'Ok' : response,
                 }],
         };
     });
@@ -354,7 +354,7 @@ function registerAllTools(server) {
         return {
             content: [{
                     type: "text",
-                    text: response,
+                    text: response === '' ? 'Ok' : response,
                 }],
         };
     });
@@ -412,7 +412,7 @@ function registerAllTools(server) {
         return {
             content: [{
                     type: "text",
-                    text: response,
+                    text: response === '' ? 'Ok' : response,
                 }],
         };
     });
@@ -474,7 +474,7 @@ function registerAllTools(server) {
         return {
             content: [{
                     type: "text",
-                    text: response,
+                    text: response === '' ? 'Ok' : response,
                 }],
         };
     });
@@ -519,7 +519,7 @@ function registerAllTools(server) {
         return {
             content: [{
                     type: "text",
-                    text: response,
+                    text: response === '' ? 'Ok' : response,
                 }],
         };
     });
@@ -648,7 +648,7 @@ function registerAllTools(server) {
         return {
             content: [{
                     type: "text",
-                    text: response,
+                    text: response === '' ? 'Ok' : response,
                 }],
         };
     });
@@ -724,6 +724,9 @@ function registerAllTools(server) {
         const response = await openMSXInstance.sendCommand(openmsxCommand);
         return {
             content: [{
+                    type: "text",
+                    text: response.startsWith('Error:') ? 'Fail:' : 'Screendump file saved as:',
+                }, {
                     type: "text",
                     text: response,
                 }],
@@ -858,8 +861,8 @@ async function startHttpServer() {
 function createServerInstance() {
     // Create a new server instance (you might want to extract server creation logic)
     const newServer = new McpServer({
-        name: "mcp-stdio-server",
-        version: "1.0.0"
+        name: "mcp-openmsx",
+        version: PACKAGE_VERSION,
     });
     // Re-register all tools (you might want to extract this to a separate function)
     registerAllTools(newServer);

package/dist/utils.js

@@ -21,3 +21,34 @@ export async function extractDescriptionFromXML(filePath) {
         return 'Error reading description';
     }
 }
+/**
+ * Decode HTML entities in a string to plain text
+ * @param text - String containing HTML entities
+ * @returns string - String with HTML entities decoded
+ */
+export function decodeHtmlEntities(text) {
+    const htmlEntities = {
+        '&lt;': '<',
+        '&gt;': '>',
+        '&amp;': '&',
+        '&quot;': '"',
+        '&#x27;': "'",
+        '&#x2F;': '/',
+        '&#x60;': '`',
+        '&#x3D;': '=',
+        '&#39;': "'",
+        '&#47;': '/',
+        '&#96;': '`',
+        '&#61;': '=',
+        '&apos;': "'",
+        '&nbsp;': ' ',
+        '&#x0a;': '\n',
+        '&#x0A;': '\n',
+        '&#10;': '\n',
+        '&#13;': '\r',
+        '&#9;': '\t'
+    };
+    return text.replace(/&[#\w]+;/g, (entity) => {
+        return htmlEntities[entity] || entity;
+    });
+}

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",
   "bin": {
-    "mcp-openmsx": "./dist/server.js"
+    "mcp-openmsx": "dist/server.js"
   },
   "keywords": [
     "mcp",
-    "model-context-protocol", 
+    "model-context-protocol",
     "openmsx",
     "msx",
     "emulator",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.2",
-    "@types/express": "^5.0.2", 
+    "@types/express": "^5.0.2",
     "express": "^5.1.0",
     "tsx": "^4.7.1",
     "zod": "^3.24.4"