@nataliapc/mcp-openmsx 1.0.1 → 1.1.0

package/README.md

@@ -12,13 +12,13 @@ Currently, the MCP server requires Linux to run. It has not been tested on Windo
 
 This project creates a bridge between modern AI-assisted development (e.g. GitHub Copilot, Claude Desktop) and retro computing (MSX systems) by providing:
 
-- **Emulator Control**: Launch, configure, and manage openMSX instances
-- **Media Management**: Handle ROM cartridges, floppy disks, and cassette tapes
-- **Debugging Tools**: Full CPU debugging with breakpoints, memory inspection, and step execution
-- **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
+- **Emulator Control**: Launch, configure, manage openMSX instances, and replay timelines.
+- **Media Management**: Handle ROM cartridges, floppy disks, and cassette tapes.
+- **Debugging Tools**: Full CPU debugging with breakpoints, memory inspection, and step execution.
+- **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.
 
 ## 🏗️ Architecture
 
@@ -44,7 +44,8 @@ The MCP server translates high-level commands from your Copilot AI into `TCL` co
 ## 🛠️ Available MCP Tools
 
 ### Emulator Control Tools
-- `emu_control`: Controls an openMSX emulator: _`launch`, `close`, `powerOn`, `powerOff`, `reset`, `getEmulatorSpeed`, `setEmulatorSpeed`, `machineList`, `extensionList`_.
+- `emu_control`: Controls an openMSX emulator: _`launch`, `close`, `powerOn`, `powerOff`, `reset`, `getEmulatorSpeed`, `setEmulatorSpeed`, `machineList`, `extensionList`, `wait`_.
+- `emu_replay`: Controls emulation timeline: _`start`, `strop`, `status`, `goBack`, `absoluteGoto`, `truncate`, `saveReplay`, `loadReplay`_.
 - `emu_info`: Obtain informacion about the current emulated machine: _`getStatus`, `getSlotsMap`, `getIOPortsMap`_.
 - `emu_media`: Manage ROM, disk, and tape media: _`tapeInsert`, `tapeRewind`, `tapeEject`, `romInsert`, `romEject`, `diskInsert`, `diskInsertFolder`, `diskEject`_.
 - `emu_vdp`: Manage VDP (Video Display Processor): _`getPalette`, `getRegisters`, `getRegisterValue`, `setRegisterValue`, `screenGetMode`, `screenGetFullText`_.
@@ -62,49 +63,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
-```
-
-### Manual 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 +86,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 | Default for openmsx | `/myproject/screenshots` |
+| `OPENMSX_SCREENDUMP_DIR` | Directory where screen dumps will be saved | Default for openmsx | `/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 +192,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
@@ -89,8 +89,21 @@ export class OpenMSX {
                                     this.sendCommand('set renderer SDLGL-PP');
                                     // set machine on
                                     this.sendCommand('set power on');
+                                    // start reverse replay mode
+                                    this.sendCommand('reverse start');
                                     // Return success message
-                                    safeResolve('Ok: openMSX emulator launched successfully');
+                                    let result = 'Ok: openMSX emulator launched successfully';
+                                    if (machine) {
+                                        result += ` with machine "${machine}"`;
+                                    }
+                                    if (extensions && extensions.length > 0) {
+                                        if (machine) {
+                                            result += ' and';
+                                        }
+                                        result += ` with extensions: "${extensions.join('", "')}"`;
+                                    }
+                                    result += ', is powered on, and replay mode is started.';
+                                    safeResolve(result);
                                 }
                                 catch (error) {
                                     safeResolve(`Error: Failed to send control commands - ${error instanceof Error ? error.message : 'Unknown error'}`);
@@ -179,7 +192,7 @@ export class OpenMSX {
                 const trimmedLine = param.trim();
                 if (trimmedLine) {
                     const value = await this.sendCommand(`machine_info ${trimmedLine}`);
-                    machineInfo[trimmedLine] = value;
+                    machineInfo[trimmedLine] = value.trim();
                 }
             }
             return JSON.stringify(machineInfo, null, 2);
@@ -259,14 +272,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.1
+ * @version 1.1.0
  * @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.1";
+const PACKAGE_VERSION = "1.1.0";
 // Defaults for openMSX paths
 var OPENMSX_EXECUTABLE = 'openmsx';
 var OPENMSX_SHARE_DIR = '/usr/share/openmsx';
@@ -39,41 +39,30 @@ 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 could be specified, always use 'machine_list' and 'extension_list' resources to obtain valid values. " +
+        "'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. " +
         "'close': closes the openMSX emulator. " +
         "'powerOn': powers on the openMSX emulator. " +
         "'powerOff': powers off the openMSX emulator. " +
         "'reset': resets the current machine. " +
-        "'getEmulatorSpeed': get current emulator speed in percentage, default is 100. " +
-        "'setEmulatorSpeed <emuspeed>': set the emulator speed in percentage, valid values are 1-10000, default is 100. " +
-        "'machineList': get a list of all available MSX machines that can be emulated with openMSX. " +
-        "'extensionList': get a list of all available MSX extensions that can be used with openMSX. ", 
+        "'getEmulatorSpeed': gets the current emulator speed as a percentage, default is 100. " +
+        "'setEmulatorSpeed <emuspeed>': sets the emulator speed as a percentage, valid values are 1-10000, default is 100. " +
+        "'machineList': gets a list of all available MSX machines that can be emulated with openMSX. " +
+        "'extensionList': gets a list of all available MSX extensions that can be used with openMSX. " +
+        "'wait <seconds>': performs a wait for the specified number of seconds, default is 2. ", 
     // Schema for the tool (input validation)
     {
-        command: z.enum(["launch", "close", "powerOn", "powerOff", "reset", "getEmulatorSpeed", "setEmulatorSpeed", "machineList", "extensionList"]),
+        command: z.enum(["launch", "close", "powerOn", "powerOff", "reset", "getEmulatorSpeed", "setEmulatorSpeed", "machineList", "extensionList", "wait"]),
         machine: z.string().min(1).max(100).optional(),
         extensions: z.array(z.string().min(1).max(100)).optional(),
         emuspeed: z.number().min(1).max(10000).optional().default(100),
+        seconds: z.number().min(1).max(10).optional().default(2), // Seconds to wait
     }, 
     // Handler for the tool (function to be executed when the tool is called)
-    async ({ command, machine, extensions, emuspeed }) => {
+    async ({ command, machine, extensions, emuspeed, seconds }) => {
         let result = "Error";
         switch (command) {
             case "launch":
                 result = await openMSXInstance.emu_launch(OPENMSX_EXECUTABLE, machine || "", extensions || []);
-                // Check if launch was successful
-                if (result === "Ok") {
-                    result = "openMSX emulator launched";
-                    if (machine) {
-                        result += ` with machine "${machine}"`;
-                    }
-                    if (extensions && extensions.length > 0) {
-                        if (machine) {
-                            result += ' and ';
-                        }
-                        result += ` with extensions: ${extensions.join(', ')}`;
-                    }
-                }
                 break;
             case "close":
                 result = await openMSXInstance.emu_close();
@@ -104,17 +93,18 @@ function registerAllTools(server) {
             case "extensionList":
                 result = await openMSXInstance.getExtensionList(EXTENSIONS_DIR);
                 break;
+            case "wait":
+                await new Promise(resolve => setTimeout(resolve, seconds * 1000));
+                result = `Waited for ${seconds} seconds.`;
+                break;
             default:
                 result = `Error: Unknown command "${command}".`;
                 break;
         }
         // Return result with proper format for MCP
-        return {
-            content: [{
-                    type: "text",
-                    text: result === '' ? 'Ok' : result,
-                }],
-        };
+        return getResponseContent([
+            result
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -166,21 +156,15 @@ function registerAllTools(server) {
                 tclCommand = "diska eject";
                 break;
             default:
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Error: Unknown emulator media command "${command}".`,
-                        }],
-                };
+                return getResponseContent([
+                    `Error: Unknown emulator media command "${command}".`
+                ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
         // Return the response from openMSX
-        return {
-            content: [{
-                    type: "text",
-                    text: response === '' ? 'Ok' : response,
-                }],
-        };
+        return getResponseContent([
+            response
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -199,12 +183,9 @@ function registerAllTools(server) {
         let tclCommand;
         switch (command) {
             case "getStatus":
-                return {
-                    content: [{
-                            type: "text",
-                            text: await openMSXInstance.emu_status(),
-                        }],
-                };
+                return getResponseContent([
+                    await openMSXInstance.emu_status()
+                ]);
             case "getSlotsMap":
                 tclCommand = "slotmap";
                 break;
@@ -212,20 +193,14 @@ function registerAllTools(server) {
                 tclCommand = "iomap";
                 break;
             default:
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Error: Unknown emulator info command "${command}".`,
-                        }],
-                };
+                return getResponseContent([
+                    `Error: Unknown emulator info command "${command}".`
+                ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return {
-            content: [{
-                    type: "text",
-                    text: response,
-                }],
-        };
+        return getResponseContent([
+            response
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -265,35 +240,18 @@ function registerAllTools(server) {
                 break;
             case "screenGetFullText":
                 const response = await openMSXInstance.sendCommand('get_screen');
-                return response.startsWith('Error:') ? {
-                    content: [{
-                            type: "text",
-                            text: response,
-                        }]
-                } : {
-                    content: [{
-                            type: "text",
-                            text: "The screen text is:",
-                        }, {
-                            type: "text",
-                            text: response,
-                        }],
-                };
+                return response.startsWith('Error:') ?
+                    getResponseContent([response]) :
+                    getResponseContent(["The screen text is:", response]);
             default:
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Error: Unknown emulator vdp command "${command}".`,
-                        }],
-                };
+                return getResponseContent([
+                    `Error: Unknown emulator vdp command "${command}".`
+                ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return {
-            content: [{
-                    type: "text",
-                    text: response === "" ? "Ok" : response,
-                }],
-        };
+        return getResponseContent([
+            response
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -343,20 +301,14 @@ function registerAllTools(server) {
                 tclCommand = `run_to ${address}`;
                 break;
             default:
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Error: Unknown debug command "${command}".`,
-                        }],
-                };
+                return getResponseContent([
+                    `Error: Unknown debug command "${command}".`
+                ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return {
-            content: [{
-                    type: "text",
-                    text: response === '' ? 'Ok' : response,
-                }],
-        };
+        return getResponseContent([
+            response
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -401,20 +353,14 @@ function registerAllTools(server) {
                 tclCommand = "get_active_cpu";
                 break;
             default:
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Error: Unknown memory command "${command}".`,
-                        }],
-                };
+                return getResponseContent([
+                    `Error: Unknown memory command "${command}".`
+                ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return {
-            content: [{
-                    type: "text",
-                    text: response === '' ? 'Ok' : response,
-                }],
-        };
+        return getResponseContent([
+            response
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -463,20 +409,14 @@ function registerAllTools(server) {
                 tclCommand = "listing";
                 break;
             default:
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Error: Unknown memory command "${command}".`,
-                        }],
-                };
+                return getResponseContent([
+                    `Error: Unknown memory command "${command}".`
+                ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return {
-            content: [{
-                    type: "text",
-                    text: response === '' ? 'Ok' : response,
-                }],
-        };
+        return getResponseContent([
+            response
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -508,20 +448,14 @@ function registerAllTools(server) {
                 tclCommand = `vpoke ${address} ${value8}`;
                 break;
             default:
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Error: Unknown video memory command "${command}".`,
-                        }],
-                };
+                return getResponseContent([
+                    `Error: Unknown video memory command "${command}".`
+                ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return {
-            content: [{
-                    type: "text",
-                    text: response === '' ? 'Ok' : response,
-                }],
-        };
+        return getResponseContent([
+            response
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -553,20 +487,14 @@ function registerAllTools(server) {
                 tclCommand = 'debug list_bp';
                 break;
             default:
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Error: Unknown breakpoint command "${command}".`,
-                        }],
-                };
+                return getResponseContent([
+                    `Error: Unknown breakpoint command "${command}".`
+                ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return {
-            content: [{
-                    type: "text",
-                    text: response,
-                }],
-        };
+        return getResponseContent([
+            response
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -600,23 +528,77 @@ function registerAllTools(server) {
                 tclCommand = 'list_savestates';
                 break;
             default:
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Error: Unknown savestate command "${command}".`,
-                        }],
-                };
+                return getResponseContent([
+                    `Error: Unknown savestate command "${command}".`
+                ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return {
-            content: [{
-                    type: "text",
-                    text: textResponse,
-                }, {
-                    type: "text",
-                    text: response,
-                }],
-        };
+        return getResponseContent([
+            textResponse,
+            response
+        ]);
+    });
+    server.tool(
+    // Name of the tool (used to call it)
+    "emu_replay", 
+    // Description of the tool (what it does)
+    "When replay is enabled (the default) the emulator collect data while emulating, which enables you to go back and forward in MSX time; consider do a 'pause' to maintain the the timeline before a 'goBack' or 'absoluteGoto'. Commands: " +
+        "'start': starts the replay mode (enabled by default when emulator is launched). " +
+        "'stop': stops the replay mode. " +
+        "'status': gives information about the replay feature and the data that is collected. " +
+        "'goBack <seconds>': go back specified seconds (1-60) in the timeline, you cannot go back to a time before the time the replay started. " +
+        "'absoluteGoto <time>': go to the indicated absolute time in seconds in the MSX timeline, if time is before replay started it will jump to the time when is started. " +
+        "'truncate': stop replaying and wipe all the future replay data after now. " +
+        "'saveReplay [filename]': saves the current replay data to a file (extension .omr), filename is returned in the response. " +
+        "'loadReplay <filename>': loads a previously saved replay file (extension .omr), starts replaying from the begin, and starts replay mode.", 
+    // Schema for the tool (input validation)
+    {
+        command: z.enum(["start", "stop", "status", "goBack", "absoluteGoto", "truncate", "saveReplay", "loadReplay"]),
+        seconds: z.number().min(1).max(60).optional(), // Seconds to go back
+        time: z.string().regex(/^\d+$/).optional(), // Time in seconds to go to
+        filename: z.string().min(1).max(200).optional(), // Filename to save/load replay
+    }, 
+    // Handler for the tool (function to be executed when the tool is called)
+    async ({ command, seconds, time, filename }) => {
+        let tclCommand;
+        switch (command) {
+            case "start":
+                tclCommand = "reverse start";
+                break;
+            case "stop":
+                tclCommand = "reverse stop";
+                break;
+            case "status":
+                tclCommand = "reverse status";
+                break;
+            case "goBack":
+                tclCommand = `reverse goback ${seconds}`;
+                break;
+            case "absoluteGoto":
+                tclCommand = `reverse goto ${time}`;
+                break;
+            case "truncate":
+                tclCommand = "reverse truncatereplay";
+                break;
+            case "saveReplay":
+                if (filename)
+                    filename = `"${filename}"`;
+                tclCommand = `reverse savereplay ${filename || ''}`;
+                break;
+            case "loadReplay":
+                if (filename)
+                    filename = `"${filename}"`;
+                tclCommand = `reverse loadreplay ${filename}`;
+                break;
+            default:
+                return getResponseContent([
+                    `Error: Unknown replay command "${command}".`
+                ]);
+        }
+        const response = await openMSXInstance.sendCommand(tclCommand);
+        return getResponseContent([
+            response
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -637,20 +619,14 @@ function registerAllTools(server) {
                 tclCommand = `type "${text}"`;
                 break;
             default:
-                return {
-                    content: [{
-                            type: "text",
-                            text: `Error: Unknown keyboard command "${command}".`,
-                        }],
-                };
+                return getResponseContent([
+                    `Error: Unknown keyboard command "${command}".`
+                ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return {
-            content: [{
-                    type: "text",
-                    text: response === '' ? 'Ok' : response,
-                }],
-        };
+        return getResponseContent([
+            response
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -684,30 +660,19 @@ function registerAllTools(server) {
                     };
                 }
                 catch (error) {
-                    return {
-                        content: [{
-                                type: "text",
-                                text: 'Error creating screenshot: ' + response,
-                            }, {
-                                type: "text",
-                                text: error instanceof Error ? error.message : String(error),
-                            }],
-                    };
+                    return getResponseContent([
+                        'Error creating screenshot: ' + response,
+                        error instanceof Error ? error.message : String(error)
+                    ]);
                 }
             case "to_file":
-                return {
-                    content: [{
-                            type: "text",
-                            text: response.startsWith('Error:') ? response : 'Screenshot taken in file: ' + response,
-                        }],
-                };
+                return getResponseContent([
+                    response.startsWith('Error:') ? response : 'Screenshot taken in file: ' + response
+                ]);
         }
-        return {
-            content: [{
-                    type: "text",
-                    text: `Error: Unknown screen_shot command "${command}".`,
-                }],
-        };
+        return getResponseContent([
+            `Error: Unknown screen_shot command "${command}".`
+        ]);
     });
     server.tool(
     // Name of the tool (used to call it)
@@ -722,17 +687,20 @@ function registerAllTools(server) {
     async ({ scrbasename }) => {
         const openmsxCommand = `save_msx_screen "${OPENMSX_SCREENDUMP_DIR + scrbasename}"`;
         const response = await openMSXInstance.sendCommand(openmsxCommand);
-        return {
-            content: [{
-                    type: "text",
-                    text: response.startsWith('Error:') ? 'Fail:' : 'Screendump file saved as:',
-                }, {
-                    type: "text",
-                    text: response,
-                }],
-        };
+        return getResponseContent([
+            response.startsWith('Error:') ? 'Fail:' : 'Screendump file saved as:',
+            response
+        ]);
     });
 }
+function getResponseContent(response) {
+    return {
+        content: response.map(line => ({
+            type: "text",
+            text: line == '' ? "Ok" : line,
+        })),
+    };
+}
 // ============================================================================
 // Cleanup handlers for graceful shutdown of MCP server
 // Ensure openMSX emulator is closed when MCP server stops

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,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",