@nataliapc/mcp-openmsx 1.1.4 → 1.1.8

package/dist/server.js

@@ -6,7 +6,7 @@
  * through TCL commands via stdio.
  *
  * @package @nataliapc/mcp-openmsx
- * @version 1.1.4
+ * @version 1.1.8
  * @author Natalia Pujol Cremades (@nataliapc)
  * @license GPL2
  */
@@ -18,13 +18,17 @@ import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import express from "express";
 import fs from "fs/promises";
+import mime from "mime-types";
 import path from "path";
 import { openMSXInstance } from "./openmsx.js";
+import { encodeTypeText, isErrorResponse, getResponseContent } from "./utils.js";
 // Version info for CLI
-const PACKAGE_VERSION = "1.1.4";
+const PACKAGE_VERSION = "1.1.8";
+const resourcesDir = path.join(path.dirname(new URL(import.meta.url).pathname), "../resources");
 // Defaults for openMSX paths
 var OPENMSX_EXECUTABLE = 'openmsx';
 var OPENMSX_SHARE_DIR = '/usr/share/openmsx';
+var OPENMSX_REPLAYS_DIR = '';
 var OPENMSX_SCREENSHOT_DIR = '';
 var OPENMSX_SCREENDUMP_DIR = '';
 var MACHINES_DIR = `${OPENMSX_SHARE_DIR}/machines`;
@@ -33,22 +37,24 @@ var EXTENSIONS_DIR = `${OPENMSX_SHARE_DIR}/extensions`;
 // Tools available in the MCP server
 // https://modelcontextprotocol.io/docs/concepts/tools#tool-definition-structure
 //
-function registerAllTools(server) {
+async function registerAllTools(server) {
     server.tool(
     // Name of the tool (used to call it)
     "emu_control", 
     // Description of the tool (what it does)
-    "Controls an openMSX emulator. Commands: " +
-        "'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. " +
-        "'reset': resets the current machine. " +
-        "'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. ", 
+    `Controls an openMSX emulator.
+		Commands:
+			'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.
+			'reset': resets the current machine.
+			'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", "wait"]),
@@ -110,15 +116,17 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "emu_media", 
     // Description of the tool (what it does)
-    "Manage tapes, rom cartridges, and floppy disks. Commands: " +
-        "'tapeInsert <tapefile>': insert a valid tape file (*.cas, *.wav, *.tsx). " +
-        "'tapeRewind': rewind the current tape. " +
-        "'tapeEject': remove tape from virtual cassette player. " +
-        "'romInsert <romfile>': insert a valid ROM cartridge file (*.rom) at cartridge slot A. " +
-        "'romEject': remove the current ROM cartridge from cartridge slot A. " +
-        "'diskInsert <diskfile>': insert a valid disk file (*.dsk) in floppy disk A. " +
-        "'diskInsertFolder <diskfolder>': use a host folder as a floppy disk A root directory. " +
-        "'diskEject': remove the current disk from floppy disk A. ", 
+    `Manage tapes, rom cartridges, and floppy disks.
+		Commands:
+			'tapeInsert <tapefile>': insert a valid tape file (*.cas, *.wav, *.tsx).
+			'tapeRewind': rewind the current tape.
+			'tapeEject': remove tape from virtual cassette player.
+			'romInsert <romfile>': insert a valid ROM cartridge file (*.rom) at cartridge slot A.
+			'romEject': remove the current ROM cartridge from cartridge slot A.
+			'diskInsert <diskfile>': insert a valid disk file (*.dsk) in floppy disk A.
+			'diskInsertFolder <diskfolder>': use a host folder as a floppy disk A root directory.
+			'diskEject': remove the current disk from floppy disk A.
+		`, 
     // Schema for the tool (input validation)
     {
         command: z.enum(["tapeInsert", "tapeRewind", "tapeEject", "romInsert", "romEject", "diskInsert", "diskInsertFolder", "diskEject"]),
@@ -170,10 +178,12 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "emu_info", 
     // Description of the tool (what it does)
-    "Obtain informacion about the current emulated machine. Commands: " +
-        "'getStatus': returns the status of the openMSX emulator. " +
-        "'getSlotsMap': shows what devices/ROM/RAM are inserted into which slots. " +
-        "'getIOPortsMap': shows an overview about the I/O mapped devices. ", 
+    `Obtain informacion about the current emulated machine.
+		Commands:
+			'getStatus': returns the status of the openMSX emulator.
+			'getSlotsMap': shows what devices/ROM/RAM are inserted into which slots.
+			'getIOPortsMap': shows an overview about the I/O mapped devices.
+		`, 
     // Schema for the tool (input validation)
     {
         command: z.enum(["getStatus", "getSlotsMap", "getIOPortsMap"]),
@@ -206,13 +216,15 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "emu_vdp", 
     // Description of the tool (what it does)
-    "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. ", 
+    `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"]),
@@ -240,7 +252,7 @@ function registerAllTools(server) {
                 break;
             case "screenGetFullText":
                 const response = await openMSXInstance.sendCommand('get_screen');
-                return response.startsWith('Error:') ?
+                return isErrorResponse(response) ?
                     getResponseContent([response]) :
                     getResponseContent(["The screen text is:", response]);
             default:
@@ -257,16 +269,18 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "debug_run", 
     // Description of the tool (what it does)
-    "Control execution (break, continue, step). Commands: " +
-        "'break': to break CPU at current execution position. " +
-        "'isBreaked': to check if the CPU is currently in break state (1) or not (0). " +
-        "'continue': to continue execution after break. " +
-        "'stepIn': to execute one CPU instruction, go into subroutines. " +
-        "'stepOver': to execute one CPU instruction, but don't go into subroutines. " +
-        "'stepOut': to step out of the current subroutine. " +
-        "'stepBack': to step one instruction back in time. " +
-        "'runTo <address>': to run the CPU until it reaches the specified address. " +
-        "Note: Addresses and values are in hexadecimal format (e.g. 0x0000).", 
+    `Control execution (break, continue, step).
+		Commands:
+			'break': to break CPU at current execution position.
+			'isBreaked': to check if the CPU is currently in break state (1) or not (0).
+			'continue': to continue execution after break.
+			'stepIn': to execute one CPU instruction, go into subroutines.
+			'stepOver': to execute one CPU instruction, but don't go into subroutines.
+			'stepOut': to step out of the current subroutine.
+			'stepBack': to step one instruction back in time.
+			'runTo <address>': to run the CPU until it reaches the specified address.
+		**Important Note**: Addresses and values are in hexadecimal format (e.g. 0x0000).
+		`, 
     // Schema for the tool (input validation)
     {
         command: z.enum(["break", "isBreaked", "continue", "stepIn", "stepOut", "stepOver", "stepBack", "runTo"]),
@@ -314,21 +328,23 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "debug_cpu", 
     // Description of the tool (what it does)
-    "Read/write CPU registers, CPU info, Stack pile, and Disassemble code from memory. Commands: " +
-        "'getCpuRegisters': to get an overview of all the CPU registers. " +
-        "'getRegister <register>': to get the decimal value of a specific CPU register (pc, sp, ix, iy, af, bc, de, hl, ixh, ixl, iyh, iyl, a, f, b, c, d, e, h, l, i, r, im, iff). " +
-        "'setRegister <register> <value>': to set the value of a specific CPU register (pc, sp, ix, iy, af, bc, de, hl, ixh, ixl, iyh, iyl, a, f, b, c, d, e, h, l, i, r, im, iff). " +
-        "'getStackPile': to get an overview of the CPU stack. " +
-        "'disassemble [address] [size]': to print disassembled instructions at the address parameter location or PC register if empty. " +
-        "'getActiveCpu': to return the active cpu: z80 or r800." +
-        "Note: Addresses and values are in hexadecimal format (e.g. 0x0000).", 
+    `Read/write CPU registers, CPU info, Stack pile, and Disassemble code from memory.
+		Commands:
+			'getCpuRegisters': to get an overview of all the CPU registers.
+			'getRegister <register>': to get the decimal value of a specific CPU register (pc, sp, ix, iy, af, bc, de, hl, ixh, ixl, iyh, iyl, a, f, b, c, d, e, h, l, i, r, im, iff).
+			'setRegister <register> <value>': to set the value of a specific CPU register (pc, sp, ix, iy, af, bc, de, hl, ixh, ixl, iyh, iyl, a, f, b, c, d, e, h, l, i, r, im, iff).
+			'getStackPile': to get an overview of the CPU stack.
+			'disassemble [address] [size]': to print disassembled instructions at the address parameter location or PC register if empty.
+			'getActiveCpu': to return the active cpu: z80 or r800.
+		"**Important Note**: Addresses and values are in hexadecimal format (e.g. 0xd2 0x3af2)."
+		`, 
     // Schema for the tool (input validation)
     {
         command: z.enum(["getCpuRegisters", "getRegister", "setRegister", "getStackPile", "disassemble", "getActiveCpu"]),
         register: z.enum(["pc", "sp", "ix", "iy", "af", "bc", "de", "hl", "ixh", "ixl", "iyh", "iyl", "a", "f", "b", "c", "d", "e", "h", "l", "i", "r", "im", "iff"]).optional(),
-        address: z.string().regex(/^0x[0-9a-fA-F]{4}$/), // 4 hex digits for MSX memory address
-        value: z.string().regex(/^0x[0-9a-fA-F]{2-4}$/).optional(), // 2-4 hex digits for byte value for writeByte command
-        size: z.number().min(1).max(50).optional().default(8), // Number of bytes for disassemble command
+        address: z.string().regex(/^0x[0-9a-fA-F]{4}$/).optional(), // 4 hex digits for MSX memory address
+        value: z.string().regex(/^0x[0-9a-fA-F]{2,4}$/).optional(), // 2-4 hex digits for byte value for writeByte command
+        size: z.number().min(8).max(50).optional(), // Number of bytes for disassemble command
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, address, register, value, size }) => {
@@ -338,10 +354,10 @@ function registerAllTools(server) {
                 tclCommand = "cpuregs";
                 break;
             case "getRegister":
-                tclCommand = "reg ${register}";
+                tclCommand = `reg ${register}`;
                 break;
             case "setRegister":
-                tclCommand = "reg ${register} ${value}";
+                tclCommand = `reg ${register} ${value}`;
                 break;
             case "getStackPile":
                 tclCommand = "stack";
@@ -366,18 +382,19 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "debug_memory", 
     // Description of the tool (what it does)
-    "Slots info, and Read/write from/to memory in the openMSX emulator. Commands: " +
-        "'selectedSlots': to get a list of the currently selected memory slots. " +
-        "'getBlock <address> [lines]': to read a block of memory from the specified address. " +
-        "'readByte <address>': to read a BYTE from the specified address. " +
-        "'readWord <address>': to read a WORD from the specified address. " +
-        "'writeByte <address> <value8>': to write a BYTE to the specified address. " +
-        "'writeWord <address> <value16>': to write a WORD to the specified address. " +
-        "'advanced_basic_listing': to list the current BASIC program, with the ram address of each line listed. " +
-        "Note: Addresses and values are in hexadecimal format (e.g. 0x0000).", 
+    `Slots info, and Read/write from/to memory in the openMSX emulator.
+		Commands:
+			'selectedSlots': to get a list of the currently selected memory slots.
+			'getBlock <address> [lines]': to read a block of memory from the specified address.
+			'readByte <address>': to read a BYTE from the specified address.
+			'readWord <address>': to read a WORD from the specified address.
+			'writeByte <address> <value8>': to write a BYTE to the specified address.
+			'writeWord <address> <value16>': to write a WORD to the specified address.
+		**Important Note**: Addresses and values are in hexadecimal format (e.g. 0x0000).
+		`, 
     // Schema for the tool (input validation)
     {
-        command: z.enum(["selectedSlots", "getBlock", "readByte", "readWord", "writeByte", "writeWord", "advanced_basic_listing"]),
+        command: z.enum(["selectedSlots", "getBlock", "readByte", "readWord", "writeByte", "writeWord"]),
         address: z.string().regex(/^0x[0-9a-fA-F]{4}$/).optional(), // 4 hex digits for MSX memory address
         lines: z.number().min(1).max(50).optional().default(8), // Number of lines for getBlock command
         value8: z.string().regex(/^0x[0-9a-fA-F]{2}$/).optional(), // 2 hex digits for byte value for writeByte command
@@ -405,9 +422,6 @@ function registerAllTools(server) {
             case "writeWord":
                 tclCommand = `poke16 ${address} ${value16}`;
                 break;
-            case "advanced_basic_listing":
-                tclCommand = "listing";
-                break;
             default:
                 return getResponseContent([
                     `Error: Unknown memory command "${command}".`
@@ -422,11 +436,13 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "debug_vram", 
     // Description of the tool (what it does)
-    "Read or write from/to VRAM video memory in the openMSX emulator. Commands: " +
-        "'getBlock <address> [lines]': to read a block of VRAM memory from the specified address. " +
-        "'readByte <address>': to read a BYTE from the specified VRAM address. " +
-        "'writeByte <address> <value8>': to write a BYTE to the specified VRAM address. " +
-        "Note: Addresses and values are in hexadecimal format (e.g. 0x0000).", 
+    `Read or write from/to VRAM video memory in the openMSX emulator.
+		Commands:
+			'getBlock <address> [lines]': to read a block of VRAM memory from the specified address.
+			'readByte <address>': to read a BYTE from the specified VRAM address.
+			'writeByte <address> <value8>': to write a BYTE to the specified VRAM address.
+		**Important Note**: Addresses and values are in hexadecimal format (e.g. 0x0000).
+		`, 
     // Schema for the tool (input validation)
     {
         command: z.enum(["getBlock", "readByte", "writeByte"]),
@@ -461,12 +477,14 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "debug_breakpoints", 
     // Description of the tool (what it does)
-    "Create, remove, and list breakpoints. Commands: " +
-        "'create <address>': create a breakpoint at a specified address, and returns its name. " +
-        "'remove <bpname>': remove a breakpoint by name (e.g. bp#1). " +
-        "'list': enumerate the active breakpoints. " +
-        "Note: Addresses and values are in hexadecimal format (e.g. 0x0000). " +
-        "Note: The memory addresses of functions and variables can be previously obtained from *.sym or *.map files.", 
+    `Create, remove, and list breakpoints.
+		Commands:
+			'create <address>': create a breakpoint at a specified address, and returns its name.
+			'remove <bpname>': remove a breakpoint by name (e.g. bp#1).
+			'list': enumerate the active breakpoints.
+		"**Important Note**: Addresses and values are in hexadecimal format (e.g. 0x0000).
+		"**Important Note**: The memory addresses of functions and variables can be previously obtained from *.sym or *.map files.
+		`, 
     // Schema for the tool (input validation)
     {
         command: z.enum(["create", "remove", "list"]),
@@ -500,11 +518,13 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "emu_savestates", 
     // Description of the tool (what it does)
-    "Load, save, and list savestates. Commands: " +
-        "'load <name>': restores a previously created savestate. " +
-        "'save <name>': creates a snapshot of the currently emulated MSX machine specifying a name for the savestate. " +
-        "'list': returns the names of all previously created savestates, separated by spaces. " +
-        "Note: names with spaces are enclosed in {}.", 
+    `Load, save, and list savestates.
+		Commands:
+			'load <name>': restores a previously created savestate.
+			'save <name>': creates a snapshot of the currently emulated MSX machine specifying a name for the savestate.
+			'list': returns the names of all previously created savestates, separated by spaces.
+		**Important Note**: names with spaces are enclosed in {}.
+		`, 
     // Schema for the tool (input validation)
     {
         command: z.enum(["load", "save", "list"]),
@@ -542,15 +562,19 @@ function registerAllTools(server) {
     // 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.", 
+    `When replay is enabled (the default) the emulator collect data while emulating,
+		which enables you to go back and forward in MSX time.
+		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.
+		**Important Note**: consider do a #debug_run 'break' to maintain the timeline before a 'goBack' or 'absoluteGoto'.
+		`, 
     // Schema for the tool (input validation)
     {
         command: z.enum(["start", "stop", "status", "goBack", "absoluteGoto", "truncate", "saveReplay", "loadReplay"]),
@@ -582,12 +606,12 @@ function registerAllTools(server) {
                 break;
             case "saveReplay":
                 if (filename)
-                    filename = `"${filename}"`;
+                    filename = `"${OPENMSX_REPLAYS_DIR}${filename}"`;
                 tclCommand = `reverse savereplay ${filename || ''}`;
                 break;
             case "loadReplay":
                 if (filename)
-                    filename = `"${filename}"`;
+                    filename = `"${OPENMSX_REPLAYS_DIR}${filename}"`;
                 tclCommand = `reverse loadreplay ${filename}`;
                 break;
             default:
@@ -604,10 +628,12 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "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. " +
-        "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...", 
+    `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.
+		**Important Note**: each 'text' sent is limited to 200 characters, and the 'text' is sent as if it was typed in the MSX keyboard.
+		**Important 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"]),
@@ -618,7 +644,7 @@ function registerAllTools(server) {
         let tclCommand;
         switch (command) {
             case "sendText":
-                tclCommand = `type "${text}"`;
+                tclCommand = `type "${encodeTypeText(text)}"`;
                 break;
             default:
                 return getResponseContent([
@@ -634,9 +660,11 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "screen_shot", 
     // Description of the tool (what it does)
-    "Take a screenshot of the openMSX emulator screen. Commands: " +
-        "'as_image': take a screenshot and the image is returned in the response. " +
-        "'to_file': take a screenshot and save it to a file, the file name is returned in the response.", 
+    `Take a screenshot of the openMSX emulator screen.
+		Commands:
+			'as_image': take a screenshot and the image is returned in the response.
+			'to_file': take a screenshot and save it to a file, the file name is returned in the response.
+		`, 
     // Schema for the tool (input validation)
     {
         command: z.enum(["as_image", "to_file"]),
@@ -648,8 +676,16 @@ function registerAllTools(server) {
         switch (command) {
             case "as_image":
                 try {
+                    // Check if the response is a file path
+                    if (!response || !response.startsWith(OPENMSX_SCREENSHOT_DIR) || !response.endsWith('.png')) {
+                        throw new Error(`Invalid screenshot "${response}"`);
+                    }
+                    // Read the screenshot file
                     const imageBuffer = await fs.readFile(response);
                     const base64image = imageBuffer.toString('base64');
+                    // Remove the file after reading it
+                    await fs.unlink(response);
+                    // Return the image in the response
                     return {
                         content: [{
                                 type: "text",
@@ -669,7 +705,7 @@ function registerAllTools(server) {
                 }
             case "to_file":
                 return getResponseContent([
-                    response.startsWith('Error:') ? response : 'Screenshot taken in file: ' + response
+                    isErrorResponse(response) ? response : 'Screenshot taken in file: ' + response
                 ]);
         }
         return getResponseContent([
@@ -680,7 +716,9 @@ function registerAllTools(server) {
     // Name of the tool (used to call it)
     "screen_dump", 
     // Description of the tool (what it does)
-    "Take a screendump of the openMSX emulator screen as SC?. The parameter scrbasename is the name of the filename (without path) to save the screendump, default is 'screendump'. ", 
+    `Take a screendump of the openMSX emulator screen as SC?.
+		The parameter scrbasename is the name of the filename (without path) to save the screendump, default is 'screendump'.
+		`, 
     // Schema for the tool (input validation)
     {
         scrbasename: z.string().min(1).max(100).default("screendump"),
@@ -690,21 +728,200 @@ function registerAllTools(server) {
         const openmsxCommand = `save_msx_screen "${OPENMSX_SCREENDUMP_DIR + scrbasename}"`;
         const response = await openMSXInstance.sendCommand(openmsxCommand);
         return getResponseContent([
-            response.startsWith('Error:') ? 'Fail:' : 'Screendump file saved as:',
+            isErrorResponse(response) ? 'Fail:' : 'Screendump file saved as:',
             response
         ]);
     });
+    server.tool(
+    // Name of the tool (used to call it)
+    "basic_programming", 
+    // Description of the tool (what it does)
+    `Tool helper to develop BASIC programs.
+		Commands:
+			'newProgram': clears the current BASIC program.
+			'setProgram <program>': sets/updates the current BASIC program to the specified string.
+			'runProgram': runs the current BASIC program.
+			'getFullProgram': returns the current BASIC program as a plain text string.
+			'getFullProgramAdvanced': returns the current BASIC program with the ram address where each line is coded.
+			'listProgramLines <startLine> [endLine]': lists at the emulator screen the selected range lines of the current BASIC program.
+			'deleteProgramLines <startLine> [endline]': deletes a specific line range from the current BASIC program, if endline is not specified, only the startLine is deleted.
+		**Important Note**: priorize this tools to develop BASIC programs, it's more efficient than using the 'sendText' tool.
+		**Important Note**: all the program lines must be ended with a carriage return (\\r) to be correctly processed, even the last one.
+		**Important Note**: if you have doubts about MSX BASIC, use the resources provided by this MCP.
+		`, 
+    // Schema for the tool (input validation)
+    {
+        command: z.enum(["newProgram", "runProgram", "setProgram", "getFullProgram", "getFullProgramAdvanced", "listProgramLines", "deleteProgramLines"]),
+        program: z.string().min(1).max(10000).optional(), // BASIC program to set
+        startLine: z.number().min(0).max(9999).optional(),
+        endLine: z.number().min(0).max(9999).optional(),
+    }, 
+    // Handler for the tool (function to be executed when the tool is called)
+    async ({ command, program, startLine, endLine }) => {
+        const CTRL_L_TEMPLATE = 'keymatrixdown 6 2 ; keymatrixdown 4 2 ; after time 0.1 { keymatrixup 6 2 ; keymatrixup 4 2 ; type_via_keybuf "%s" }';
+        let tclCommand = undefined;
+        let response = undefined;
+        switch (command) {
+            case "newProgram":
+                response = await openMSXInstance.sendCommand(CTRL_L_TEMPLATE.replace('%s', encodeTypeText('new\r')));
+                if (response.startsWith('after#'))
+                    response = '';
+                break;
+            case "runProgram":
+                response = await openMSXInstance.sendCommand(CTRL_L_TEMPLATE.replace('%s', encodeTypeText('run\r')));
+                if (response.startsWith('after#'))
+                    response = '';
+                break;
+            case "deleteProgramLines":
+                if (startLine === undefined) {
+                    response = 'Error: No startLine number provided to delete BASIC program lines.';
+                    break;
+                }
+                response = await openMSXInstance.sendCommand(CTRL_L_TEMPLATE.replace('%s', encodeTypeText(`delete ${startLine}-${endLine || startLine}\r`)));
+                break;
+            case "setProgram":
+                if (!program) {
+                    response = 'Error: No BASIC program provided to set.';
+                    break;
+                }
+                // Get current speed to restore it later
+                let speed = '100';
+                if (isErrorResponse(speed = await openMSXInstance.sendCommand('set speed'))) {
+                    response = speed;
+                    break;
+                }
+                // Set speed to fast for program input
+                if (isErrorResponse(response = await openMSXInstance.sendCommand('set speed 10000')))
+                    break;
+                // Clear the screen and type the program
+                if (isErrorResponse(response = await openMSXInstance.sendCommand(`type_via_keybuf "${encodeTypeText(program)}"`)))
+                    break;
+                // Restore the original speed
+                if (isErrorResponse(response = await openMSXInstance.sendCommand(`set speed ${speed}`)))
+                    break;
+                // Success response
+                response = '';
+                break;
+            case "getFullProgram":
+                // Source: https://www.msx.org/forum/msx-talk/openmsx/export-basic-listing#comment-407392
+                tclCommand = 'regsub -all -line {^[0-9a-f]x[0-9a-f]{4} > } [ listing ] ""';
+                break;
+            case "getFullProgramAdvanced":
+                tclCommand = "listing";
+                break;
+            case "listProgramLines":
+                if (startLine === undefined) {
+                    response = 'Error: No start line provided to list BASIC program lines.';
+                    break;
+                }
+                tclCommand = `type_via_keybuf \"${encodeTypeText(`list ${startLine}-${endLine || startLine}\r`)}\"`;
+                break;
+            default:
+                response = `Error: Unknown command "${command}".`;
+                break;
+        }
+        if (response === undefined && tclCommand) {
+            response = await openMSXInstance.sendCommand(tclCommand);
+        }
+        return getResponseContent([
+            response !== undefined ? response : `Error: No response for command "${command}".`
+        ]);
+    });
+    // ============================================================================
+    // MSX Documentation resources
+    const resdocs = (await listResourcesDirectory()).sort();
+    for (let index = 0; index < resdocs.length; index++) {
+        const sectionName = resdocs[index];
+        const tocFile = path.join(resourcesDir, `${sectionName}/toc.json`);
+        const tocContent = JSON.parse(await fs.readFile(tocFile, 'utf8'));
+        tocContent.toc.forEach((item, itemIndex) => {
+            const itemName = item.uri.split('/').pop() || '';
+            server.resource(
+            // Name of the resource (used to call it)
+            `msxdocs_${sectionName}_${itemName}`, 
+            // Resource URI template
+            item.uri, 
+            // Metadata for the resource
+            {
+                title: item.title || `MSX Documentation '${sectionName}' - ${itemName}`,
+                description: item.description || `Documentation for MSX resource '${sectionName}' - ${itemName}`,
+                mimeType: item.mimeType || 'text/markdown',
+            }, 
+            // Handler for the resource (function to be executed when the resource is called)
+            async (uri) => {
+                let resourceContent;
+                let mimeType;
+                if (uri.href.startsWith('http://') || uri.href.startsWith('https://')) {
+                    // Fetch the resource from the URL
+                    try {
+                        resourceContent = await fetch(uri.href).then(response => {
+                            mimeType = response.headers.get('content-type') || 'text/plain';
+                            return response.text();
+                        }) || 'Error downloading resource content';
+                    }
+                    catch (error) {
+                        // Throw exception (MCP protocol requirement)
+                        throw new Error(`Error fetching resource from ${uri.href}: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+                else {
+                    // Read the resource from the local MCP server resources directory
+                    try {
+                        let resourceFile;
+                        [mimeType, resourceFile] = await addFileExtension(path.join(resourcesDir, `${sectionName}/${itemName}`));
+                        resourceContent = await fs.readFile(resourceFile, 'utf8');
+                    }
+                    catch (error) {
+                        // Throw exception (MCP protocol requirement)
+                        throw new Error(`Error reading resource ${sectionName}/${item.uri}: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+                return {
+                    contents: [{
+                            uri: uri.href,
+                            text: resourceContent,
+                            mimeType: mimeType || 'text/plain',
+                        }],
+                };
+            });
+        });
+    }
+    ;
+}
+async function addFileExtension(filePath) {
+    // Get directory and filename
+    const directory = path.dirname(filePath);
+    const filename = path.basename(filePath);
+    try {
+        // Get all files in directory that start with our filename
+        const files = await fs.readdir(directory);
+        const matchingFiles = files.filter(file => file.startsWith(filename));
+        if (matchingFiles.length > 0) {
+            const fileFound = path.join(directory, matchingFiles[0]);
+            return [
+                mime.lookup(fileFound) || 'text/plain',
+                fileFound
+            ];
+        }
+    }
+    catch (error) {
+        console.error('Error reading directory:', error);
+    }
+    // Return original if no matches found
+    return ['text/plain', filePath];
 }
-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
-    };
+async function listResourcesDirectory() {
+    try {
+        const directories = await fs.readdir(resourcesDir, { withFileTypes: true });
+        const folderNames = directories
+            .filter(dirent => dirent.isDirectory())
+            .map(dirent => dirent.name);
+        return folderNames;
+    }
+    catch (error) {
+        console.error("Error reading resources directory:", error);
+        return [];
+    }
 }
 // ============================================================================
 // Cleanup handlers for graceful shutdown of MCP server
@@ -803,7 +1020,7 @@ async function startHttpServer() {
                 }
             };
             // Create a new server instance for this session
-            const httpServer = createServerInstance();
+            const httpServer = await createServerInstance();
             await httpServer.connect(transport);
         }
         else {
@@ -831,14 +1048,14 @@ async function startHttpServer() {
         console.log(`MCP Server listening on port ${port}`);
     });
 }
-function createServerInstance() {
+async function createServerInstance() {
     // Create a new server instance (you might want to extract server creation logic)
     const newServer = new McpServer({
         name: "mcp-openmsx",
         version: PACKAGE_VERSION,
     });
     // Re-register all tools (you might want to extract this to a separate function)
-    registerAllTools(newServer);
+    await registerAllTools(newServer);
     return newServer;
 }
 // ============================================================================
@@ -865,6 +1082,9 @@ async function main() {
     if (process.env.OPENMSX_SCREENDUMP_DIR && process.env.OPENMSX_SCREENDUMP_DIR !== '') {
         OPENMSX_SCREENDUMP_DIR = process.env.OPENMSX_SCREENDUMP_DIR + path.sep;
     }
+    if (process.env.OPENMSX_REPLAYS_DIR && process.env.OPENMSX_REPLAYS_DIR !== '') {
+        OPENMSX_REPLAYS_DIR = process.env.OPENMSX_REPLAYS_DIR + path.sep;
+    }
     if (process.env.OPENMSX_SHARE_DIR) {
         OPENMSX_SHARE_DIR = process.env.OPENMSX_SHARE_DIR + path.sep;
         MACHINES_DIR = `${OPENMSX_SHARE_DIR}machines`;
@@ -879,7 +1099,7 @@ async function main() {
     else {
         // Default to stdio
         const transport = new StdioServerTransport();
-        await createServerInstance().connect(transport);
+        (await createServerInstance()).connect(transport);
     }
 }
 main().catch((error) => {