@nataliapc/mcp-openmsx 1.0.2 → 1.1.2

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`_.
@@ -127,8 +128,8 @@ Add to your `claude_desktop_config.json`:
 |----------|-------------|---------------|---------|
 | `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` |
+| `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` |
 

package/dist/openmsx.js

@@ -7,6 +7,7 @@
 import fs from "fs/promises";
 import { extractDescriptionFromXML, decodeHtmlEntities } from "./utils.js";
 import { spawn } from 'child_process';
+import path from 'path';
 /**
  * OpenMSX class for controlling the openMSX emulator via TCL commands over TCP socket
  */
@@ -89,8 +90,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 +193,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);
@@ -205,7 +219,7 @@ export class OpenMSX {
                 .map(async (file) => {
                 return {
                     name: file.replace('.xml', ''),
-                    description: await extractDescriptionFromXML(`${machinesDirectory}+path.sep+${file}`)
+                    description: await extractDescriptionFromXML(path.join(machinesDirectory, file))
                 };
             }));
         }
@@ -232,7 +246,7 @@ export class OpenMSX {
                 .map(async (file) => {
                 return {
                     name: file.replace('.xml', ''),
-                    description: await extractDescriptionFromXML(`${extensionDirectory}+path.sep+${file}`)
+                    description: await extractDescriptionFromXML(path.join(extensionDirectory, file))
                 };
             }));
         }

package/dist/server.js

@@ -6,7 +6,7 @@
  * through TCL commands via stdio.
  *
  * @package @nataliapc/mcp-openmsx
- * @version 1.0.2
+ * @version 1.1.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.2";
+const PACKAGE_VERSION = "1.1.2";
 // 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/package.json

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