@nataliapc/mcp-openmsx 1.2.4 → 1.2.6

package/dist/server_tools.js

@@ -3,12 +3,14 @@ import fs from "fs/promises";
 import path from "path";
 import { openMSXInstance } from "./openmsx.js";
 import { VectorDB } from "./vectordb.js";
-import { encodeTypeText, isErrorResponse, getResponseContent } from "./utils.js";
+import { encodeTypeText, buildKeyComboCommand, isErrorResponse, getResponseContent, parseCpuRegs, is16bitRegister, parseVdpRegs, parsePalette, parseBreakpoints, parseReplayStatus, sleepWithAbort } from "./utils.js";
 import { getRegisteredResourcesList } from "./server_resources.js";
+import { resolveLaunchParams } from "./server_elicitations.js";
 // ============================================================================
 // Tools available in the MCP server
 // https://modelcontextprotocol.io/docs/concepts/tools#tool-definition-structure
 export async function registerTools(server, emuDirectories) {
+    // emu_control
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_control", {
@@ -20,7 +22,7 @@ export async function registerTools(server, emuDirectories) {
             command: z.enum(["launch", "close", "powerOn", "powerOff", "reset", "getEmulatorSpeed", "setEmulatorSpeed",
                 "machineList", "extensionList", "wait"])
                 .describe(`Available 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. " +
+'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, or let them ambiguous and use elicitation. " +
 'close': closes the openMSX emulator.
 'powerOn': powers on the openMSX emulator.
 'powerOff': powers off the openMSX emulator.
@@ -53,14 +55,45 @@ export async function registerTools(server, emuDirectories) {
                 .default(3)
                 .describe("Number of seconds to wait; default is 3. Used by [wait]."),
         },
+        outputSchema: {
+            command: z.string().describe("The command that was executed."),
+            speed: z.number().optional()
+                .describe("Emulator speed percentage. Present for 'getEmulatorSpeed' and 'setEmulatorSpeed'."),
+            machines: z.array(z.object({
+                name: z.string().describe("Machine name."),
+                description: z.string().describe("Machine description."),
+            })).optional()
+                .describe("List of available MSX machines. Present for 'machineList'."),
+            extensions: z.array(z.object({
+                name: z.string().describe("Extension name."),
+                description: z.string().describe("Extension description."),
+            })).optional()
+                .describe("List of available MSX extensions. Present for 'extensionList'."),
+            result: z.string().optional()
+                .describe("Generic result or status message."),
+        },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
-    async ({ command, machine, extensions, emuspeed, seconds }) => {
+    async ({ command, machine, extensions, emuspeed, seconds }, extra) => {
         let result = '';
         switch (command) {
-            case "launch":
-                result = await openMSXInstance.emu_launch(emuDirectories.OPENMSX_EXECUTABLE, machine || "", extensions || []);
+            case "launch": {
+                const resolved = await resolveLaunchParams(server, emuDirectories, machine, extensions);
+                if (resolved.cancelled) {
+                    return { content: [{ type: "text", text: "Launch cancelled by user." }], isError: true };
+                }
+                if (resolved.error) {
+                    return { content: [{ type: "text", text: resolved.error }], isError: true };
+                }
+                result = await openMSXInstance.emu_launch(emuDirectories.OPENMSX_EXECUTABLE, resolved.machine, resolved.extensions);
                 break;
+            }
             case "close":
                 result = await openMSXInstance.emu_close();
                 break;
@@ -90,19 +123,78 @@ export async function registerTools(server, emuDirectories) {
             case "extensionList":
                 result = await openMSXInstance.getExtensionList(emuDirectories.EXTENSIONS_DIR);
                 break;
-            case "wait":
-                await new Promise(resolve => setTimeout(resolve, seconds * 1000));
-                result = `Waited for ${seconds} seconds.`;
+            case "wait": {
+                const total = seconds;
+                const progressToken = extra._meta?.progressToken;
+                let elapsed = 0;
+                try {
+                    for (let i = 1; i <= total; i++) {
+                        await sleepWithAbort(1000, extra.signal);
+                        elapsed = i;
+                        if (progressToken !== undefined) {
+                            await extra.sendNotification({
+                                method: "notifications/progress",
+                                params: { progressToken, progress: i, total, message: `Waited ${i} of ${total} seconds` },
+                            });
+                        }
+                    }
+                    result = `Waited for ${total} seconds.`;
+                }
+                catch {
+                    result = `Wait cancelled after ${elapsed} of ${total} seconds.`;
+                    return { content: [{ type: "text", text: result }], isError: true };
+                }
                 break;
+            }
             default:
                 result = `Error: Unknown command "${command}".`;
                 break;
         }
-        // Return result with proper format for MCP
-        return getResponseContent([
-            result
-        ]);
+        if (isErrorResponse(result)) {
+            return { content: [{ type: "text", text: result }], isError: true };
+        }
+        let structuredContent;
+        switch (command) {
+            case 'getEmulatorSpeed': {
+                const match = result.match(/(\d+)%/);
+                structuredContent = { command, speed: match ? parseInt(match[1]) : undefined, result };
+                break;
+            }
+            case 'setEmulatorSpeed': {
+                structuredContent = { command, speed: emuspeed, result };
+                break;
+            }
+            case 'machineList': {
+                try {
+                    const machines = JSON.parse(result);
+                    structuredContent = { command, machines };
+                }
+                catch {
+                    structuredContent = { command, result };
+                }
+                break;
+            }
+            case 'extensionList': {
+                try {
+                    const extensions = JSON.parse(result);
+                    structuredContent = { command, extensions };
+                }
+                catch {
+                    structuredContent = { command, result };
+                }
+                break;
+            }
+            default: {
+                structuredContent = { command, result };
+            }
+        }
+        return {
+            content: [{ type: "text", text: result }],
+            structuredContent,
+            isError: false,
+        };
     });
+    // emu_info
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_media", {
@@ -142,6 +234,12 @@ export async function registerTools(server, emuDirectories) {
                 .optional()
                 .describe("Absolute Disk folder filename to insert. Used by [diskInsertFolder]"),
         },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, tapefile, romfile, diskfile, diskfolder }) => {
@@ -182,6 +280,7 @@ export async function registerTools(server, emuDirectories) {
             response
         ]);
     });
+    // emu_info
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_info", {
@@ -196,31 +295,60 @@ export async function registerTools(server, emuDirectories) {
 	'getIOPortsMap': shows an overview about the I/O mapped devices.
 `),
         },
+        outputSchema: {
+            command: z.string().describe("The command that was executed."),
+            status: z.record(z.string()).optional()
+                .describe("Machine status key-value pairs (type, manufacturer, year, etc.). Present for 'getStatus'."),
+            result: z.string().optional()
+                .describe("Generic result text. Present for 'getSlotsMap' and 'getIOPortsMap'."),
+        },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command }) => {
-        let tclCommand;
+        let response;
         switch (command) {
             case "getStatus":
-                return getResponseContent([
-                    await openMSXInstance.emu_status()
-                ]);
+                response = await openMSXInstance.emu_status();
+                break;
             case "getSlotsMap":
-                tclCommand = "slotmap";
+                response = await openMSXInstance.sendCommand("slotmap");
                 break;
             case "getIOPortsMap":
-                tclCommand = "iomap";
+                response = await openMSXInstance.sendCommand("iomap");
                 break;
             default:
-                return getResponseContent([
-                    `Error: Unknown emulator info command "${command}".`
-                ]);
+                return { content: [{ type: "text", text: `Error: Unknown emulator info command "${command}".` }], isError: true };
         }
-        const response = await openMSXInstance.sendCommand(tclCommand);
-        return getResponseContent([
-            response
-        ]);
+        if (isErrorResponse(response)) {
+            return { content: [{ type: "text", text: response }], isError: true };
+        }
+        let structuredContent;
+        if (command === "getStatus") {
+            try {
+                const status = JSON.parse(response);
+                structuredContent = { command, status };
+            }
+            catch {
+                structuredContent = { command, result: response };
+            }
+        }
+        else {
+            //TODO: parse the slotmap and iomap responses into structured content
+            structuredContent = { command, result: response };
+        }
+        return {
+            content: [{ type: "text", text: response }],
+            structuredContent,
+            isError: false,
+        };
     });
+    // emu_vdp
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_vdp", {
@@ -249,6 +377,37 @@ export async function registerTools(server, emuDirectories) {
                 .optional()
                 .describe("2 hexadecimal digits for a VDP register value (e.g. 0x1f). Used by [setRegisterValue]"),
         },
+        // Structured output schema (MCP protocol 2025-11-25)
+        outputSchema: {
+            command: z.string()
+                .describe("The executed command name."),
+            registers: z.record(z.string()).optional()
+                .describe("VDP register values as hex strings keyed by register number (0-31). Present for 'getRegisters'."),
+            register: z.number().optional()
+                .describe("VDP register number queried/modified. Present for 'getRegisterValue' and 'setRegisterValue'."),
+            decimalValue: z.number().optional()
+                .describe("Register value in decimal. Present for 'getRegisterValue'."),
+            hexValue: z.string().optional()
+                .describe("Register value in hexadecimal (e.g. '0x1F'). Present for 'getRegisterValue'."),
+            newValue: z.string().optional()
+                .describe("Value written to the register. Present for 'setRegisterValue'."),
+            palette: z.array(z.object({
+                index: z.number(), r: z.number(), g: z.number(), b: z.number(), rgb: z.string()
+            })).optional()
+                .describe("Color palette as array of 16 RGB333 entries. Present for 'getPalette'."),
+            screenMode: z.string().optional()
+                .describe("Current screen mode name (e.g. 'TEXT80', 'GRAPHIC2'). Present for 'screenGetMode'."),
+            screenText: z.string().optional()
+                .describe("Full text content of the MSX screen. Present for 'screenGetFullText'."),
+            result: z.string().optional()
+                .describe("Generic result or status message."),
+        },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, register, value }) => {
@@ -269,21 +428,60 @@ export async function registerTools(server, emuDirectories) {
             case "screenGetMode":
                 tclCommand = "get_screen_mode";
                 break;
-            case "screenGetFullText":
-                const response = await openMSXInstance.sendCommand('get_screen');
-                return isErrorResponse(response) ?
-                    getResponseContent([response]) :
-                    getResponseContent(["The screen text is:", response]);
+            case "screenGetFullText": {
+                const textResp = await openMSXInstance.sendCommand('get_screen');
+                if (isErrorResponse(textResp)) {
+                    return { content: [{ type: "text", text: textResp }], isError: true };
+                }
+                return {
+                    content: [{ type: "text", text: `The screen text is:\n${textResp}` }],
+                    structuredContent: { command, screenText: textResp },
+                    isError: false,
+                };
+            }
             default:
-                return getResponseContent([
-                    `Error: Unknown emulator vdp command "${command}".`
-                ]);
+                return { content: [{ type: "text", text: `Error: Unknown emulator vdp command "${command}".` }], isError: true };
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return getResponseContent([
-            response
-        ]);
+        if (isErrorResponse(response)) {
+            return { content: [{ type: "text", text: response }], isError: true };
+        }
+        let structuredContent;
+        switch (command) {
+            case "getPalette": {
+                const pal = parsePalette(response);
+                structuredContent = { command, palette: pal };
+                break;
+            }
+            case "getRegisters": {
+                const regs = parseVdpRegs(response);
+                structuredContent = { command, registers: regs };
+                break;
+            }
+            case "getRegisterValue": {
+                const dec = parseInt(response.trim(), 10);
+                const hex = `0x${dec.toString(16).toUpperCase().padStart(2, '0')}`;
+                structuredContent = { command, register, decimalValue: dec, hexValue: hex };
+                break;
+            }
+            case "setRegisterValue": {
+                structuredContent = { command, register, newValue: value, result: response || "Ok" };
+                break;
+            }
+            case "screenGetMode": {
+                structuredContent = { command, screenMode: response.trim() };
+                break;
+            }
+            default:
+                structuredContent = { command, result: response };
+        }
+        return {
+            content: [{ type: "text", text: response || "Ok" }],
+            structuredContent,
+            isError: false,
+        };
     });
+    // debug_run
     server.registerTool(
     // Name of the tool (used to call it)
     "debug_run", {
@@ -310,6 +508,12 @@ export async function registerTools(server, emuDirectories) {
                 .optional()
                 .describe("4 hexadecimal digits for a memory address (e.g. 0x4af3). Used by [runTo]"),
         },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, address }) => {
@@ -345,10 +549,12 @@ export async function registerTools(server, emuDirectories) {
                 ]);
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
+        //TODO: parse disassembly command response into structured content
         return getResponseContent([
             response
         ]);
     });
+    // debug_cpu
     server.registerTool(
     // Name of the tool (used to call it)
     "debug_cpu", {
@@ -369,6 +575,7 @@ export async function registerTools(server, emuDirectories) {
 "**Important Note**: Addresses and values are in hexadecimal format (e.g. 0xd2 0x3af2)."
 `),
             register: z.enum(["pc", "sp", "ix", "iy", "af", "bc", "de", "hl", "ixh", "ixl", "iyh", "iyl",
+                "af'", "bc'", "de'", "hl'",
                 "a", "f", "b", "c", "d", "e", "h", "l", "i", "r", "im", "iff"])
                 .optional()
                 .describe("CPU register to read/write. Used by [getRegister, setRegister]"),
@@ -386,6 +593,35 @@ export async function registerTools(server, emuDirectories) {
                 .optional()
                 .describe("Number of bytes to disassemble. Used by [disassemble]"),
         },
+        // Structured output schema (MCP protocol 2025-11-25)
+        outputSchema: {
+            command: z.string()
+                .describe("The executed command name."),
+            registers: z.record(z.string()).optional()
+                .describe("All CPU register values as hex strings, keyed by register name (AF, BC, DE, HL, AF', BC', DE', HL', IX, IY, PC, SP, I, R, IM, IFF). Present for 'getCpuRegisters'."),
+            register: z.string().optional()
+                .describe("CPU register name queried/modified. Present for 'getRegister' and 'setRegister'."),
+            decimalValue: z.number().optional()
+                .describe("Register value in decimal. Present for 'getRegister'."),
+            hexValue: z.string().optional()
+                .describe("Register value in hexadecimal (e.g. '0x1A3F'). Present for 'getRegister'."),
+            newValue: z.string().optional()
+                .describe("Value written to the register. Present for 'setRegister'."),
+            activeCpu: z.string().optional()
+                .describe("Active CPU type: 'z80' or 'r800'. Present for 'getActiveCpu'."),
+            stack: z.string().optional()
+                .describe("Stack pile dump content. Present for 'getStackPile'."),
+            disassembly: z.string().optional()
+                .describe("Disassembled code listing. Present for 'disassemble'."),
+            result: z.string().optional()
+                .describe("Generic result or status message."),
+        },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, address, register, value, size }) => {
@@ -410,15 +646,62 @@ export async function registerTools(server, emuDirectories) {
                 tclCommand = "get_active_cpu";
                 break;
             default:
-                return getResponseContent([
-                    `Error: Unknown memory command "${command}".`
-                ]);
+                return {
+                    content: [{ type: "text", text: `Error: Unknown command "${command}".` }],
+                    isError: true,
+                };
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return getResponseContent([
-            response
-        ]);
+        // On error, return unstructured content only (SDK skips outputSchema validation on errors)
+        if (isErrorResponse(response)) {
+            return {
+                content: [{ type: "text", text: response }],
+                isError: true,
+            };
+        }
+        // Build structuredContent based on the command
+        let structuredContent;
+        switch (command) {
+            case "getCpuRegisters": {
+                const regs = parseCpuRegs(response);
+                structuredContent = { command, registers: regs };
+                break;
+            }
+            case "getRegister": {
+                const decValue = parseInt(response.trim(), 10);
+                const padLen = is16bitRegister(register) ? 4 : 2;
+                const hexVal = `0x${decValue.toString(16).toUpperCase().padStart(padLen, '0')}`;
+                structuredContent = { command, register, decimalValue: decValue, hexValue: hexVal };
+                break;
+            }
+            case "setRegister": {
+                structuredContent = { command, register, newValue: value, result: response || "Ok" };
+                break;
+            }
+            case "getStackPile": {
+                //TODO: parse the stack pile response into structured content (e.g. an array of stack entries with address and value)
+                structuredContent = { command, stack: response };
+                break;
+            }
+            case "disassemble": {
+                //TODO: parse the disassembly response into a structured format (e.g. an array of instructions with address, opcode, and assembly)
+                structuredContent = { command, disassembly: response };
+                break;
+            }
+            case "getActiveCpu": {
+                structuredContent = { command, activeCpu: response.trim() };
+                break;
+            }
+            default:
+                structuredContent = { command, result: response };
+        }
+        return {
+            content: [{ type: "text", text: response || "Ok" }],
+            structuredContent,
+            isError: false,
+        };
     });
+    // debug_memory
     server.registerTool(
     // Name of the tool (used to call it)
     "debug_memory", {
@@ -427,7 +710,7 @@ export async function registerTools(server, emuDirectories) {
         description: "Slots info, and Read/write from/to memory in the openMSX emulator.",
         // Schema for the tool (input validation)
         inputSchema: {
-            command: z.enum(["selectedSlots", "getBlock", "readByte", "readWord", "writeByte", "writeWord"])
+            command: z.enum(["selectedSlots", "getBlock", "readByte", "readWord", "writeByte", "writeWord", "searchBytes"])
                 .describe(`Available 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.
@@ -435,6 +718,7 @@ export async function registerTools(server, emuDirectories) {
 	'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.
+	'searchBytes <address> <length> <values>': to search a sequence of bytes in RAM memory starting from the specified address and within the specified length.
 **Important Note**: Addresses and values are in hexadecimal format (e.g. 0x0000).
 `),
             address: z.string()
@@ -455,10 +739,46 @@ export async function registerTools(server, emuDirectories) {
                 .regex(/^0x[0-9a-fA-F]{4}$/, 'Must be a 4 digits hexadecimal number')
                 .optional()
                 .describe("4 hexadecimal digits for a word value (e.g. 0xa5b1). Used by [writeWord]"),
+            values: z.string()
+                .regex(/^(\s*0x[0-9a-fA-F]{2}\s*)+$/, "Values must be a space-separated string of 2 digits hexadecimal numbers (e.g. '0x1A 0xFF 0x00')")
+                .optional()
+                .describe("Space-separated string of 2 hexadecimal digits for byte values to search (e.g. '0x1A 0xFF 0x00'). Used by [searchBytes]"),
+            length: z.number()
+                .min(1, 'Minimum search length too low. Min: 1')
+                .max(65536, 'Maximum search length too high. Max: 65536')
+                .optional()
+                .describe("Decimal number of bytes to search within. Used by [searchBytes]"),
+        },
+        // Structured output schema (MCP protocol 2025-11-25)
+        outputSchema: {
+            command: z.string()
+                .describe("The executed command name."),
+            address: z.string().optional()
+                .describe("Memory address queried/modified."),
+            decimalValue: z.number().optional()
+                .describe("Memory value in decimal. Present for 'readByte' and 'readWord'."),
+            hexValue: z.string().optional()
+                .describe("Memory value in hexadecimal. Present for 'readByte' and 'readWord'."),
+            hexDump: z.string().optional()
+                .describe("Hex dump block of memory. Present for 'getBlock'."),
+            slots: z.string().optional()
+                .describe("Currently selected memory slots info. Present for 'selectedSlots'."),
+            length: z.number().optional()
+                .describe("Length of bytes searched. Present for 'searchBytes'."),
+            values: z.string().optional()
+                .describe("Values searched for. Present for 'searchBytes'."),
+            result: z.string().optional()
+                .describe("Generic result or status message."),
+        },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": false,
+            "openWorldHint": false,
         },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
-    async ({ command, address, lines, value8, value16 }) => {
+    async ({ command, address, lines, value8, value16, length, values }) => {
         let tclCommand;
         switch (command) {
             case "selectedSlots":
@@ -479,16 +799,73 @@ export async function registerTools(server, emuDirectories) {
             case "writeWord":
                 tclCommand = `poke16 ${address} ${value16}`;
                 break;
+            case "searchBytes":
+                length = parseInt(address, 16) + length > 0x10000 ? 0x10000 - parseInt(address, 16) : length;
+                tclCommand = `set pattern { ${values} }
+								set len [llength $pattern]
+								set results ""
+								for {set i ${address}} {$i \<= [expr {${address} + ${length} - $len}]} {incr i} {
+									set match 1
+									for {set j 0} {$j \< $len} {incr j} {
+										if {[peek [expr {$i + $j}]] != [lindex $pattern $j]} {
+											set match 0; break
+										}
+									}
+									if {$match} { append results [format "Found at 0x%04X\n" $i] }
+								}
+								if {$results eq ""} { return "No matches found" }
+								return $results`;
+                break;
             default:
-                return getResponseContent([
-                    `Error: Unknown memory command "${command}".`
-                ]);
+                return { content: [{ type: "text", text: `Error: Unknown memory command "${command}".` }], isError: true };
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return getResponseContent([
-            response
-        ]);
+        if (isErrorResponse(response)) {
+            return { content: [{ type: "text", text: response }], isError: true };
+        }
+        let structuredContent;
+        switch (command) {
+            case "selectedSlots": {
+                //TODO: parse the slotselect response into structured content (e.g. an array of selected slots with slot number and content info)
+                structuredContent = { command, slots: response };
+                break;
+            }
+            case "getBlock": {
+                structuredContent = { command, address, hexDump: response };
+                break;
+            }
+            case "readByte": {
+                const dec = parseInt(response.trim(), 10);
+                structuredContent = { command, address, decimalValue: dec, hexValue: `0x${dec.toString(16).toUpperCase().padStart(2, '0')}` };
+                break;
+            }
+            case "readWord": {
+                const dec = parseInt(response.trim(), 10);
+                structuredContent = { command, address, decimalValue: dec, hexValue: `0x${dec.toString(16).toUpperCase().padStart(4, '0')}` };
+                break;
+            }
+            case "writeByte": {
+                structuredContent = { command, address, result: response || "Ok" };
+                break;
+            }
+            case "writeWord": {
+                structuredContent = { command, address, result: response || "Ok" };
+                break;
+            }
+            case "searchBytes": {
+                structuredContent = { command, address, length, values, result: response };
+                break;
+            }
+            default:
+                structuredContent = { command, result: response };
+        }
+        return {
+            content: [{ type: "text", text: response || "Ok" }],
+            structuredContent,
+            isError: false,
+        };
     });
+    // debug_vram
     server.registerTool(
     // Name of the tool (used to call it)
     "debug_vram", {
@@ -497,11 +874,12 @@ export async function registerTools(server, emuDirectories) {
         description: "Read or write from/to VRAM video memory from the openMSX emulator.",
         // Schema for the tool (input validation)
         inputSchema: {
-            command: z.enum(["getBlock", "readByte", "writeByte"])
+            command: z.enum(["getBlock", "readByte", "writeByte", "searchBytes"])
                 .describe(`Available 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.
+	'searchBytes <address> <length> <values>': to search a sequence of bytes in VRAM memory starting from the specified address and within the specified length.
 **Important Note**: Addresses and values are in hexadecimal format (e.g. 0x0000).
 `),
             address: z.string()
@@ -515,10 +893,44 @@ export async function registerTools(server, emuDirectories) {
                 .default(8)
                 .describe("Number of lines to obtain. Used by [getBlock]"),
             value8: z.string().regex(/^0x[0-9a-fA-F]{2}$/).optional().describe("2 hexadecimal digits for a byte value (e.g. 0xa5). Used by [writeByte]"),
+            values: z.string()
+                .regex(/^(\s*0x[0-9a-fA-F]{2}\s*)+$/, "Values must be a space-separated string of 2 digits hexadecimal numbers (e.g. '0x1A 0xFF 0x00')")
+                .optional()
+                .describe("Space-separated string of 2 hexadecimal digits for byte values to search (e.g. '0x1A 0xFF 0x00'). Used by [searchBytes]"),
+            length: z.number()
+                .min(1, 'Minimum search length too low. Min: 1')
+                .max(65536, 'Maximum search length too high. Max: 65536')
+                .optional()
+                .describe("Decimal number of bytes to search within. Used by [searchBytes]"),
+        },
+        // Structured output schema (MCP protocol 2025-11-25)
+        outputSchema: {
+            command: z.string()
+                .describe("The executed command name."),
+            address: z.string().optional()
+                .describe("VRAM address queried/modified."),
+            decimalValue: z.number().optional()
+                .describe("VRAM byte value in decimal. Present for 'readByte'."),
+            hexValue: z.string().optional()
+                .describe("VRAM byte value in hexadecimal. Present for 'readByte'."),
+            hexDump: z.string().optional()
+                .describe("Hex dump block of VRAM. Present for 'getBlock'."),
+            length: z.number().optional()
+                .describe("Length of bytes searched. Present for 'searchBytes'."),
+            values: z.string().optional()
+                .describe("Values searched for. Present for 'searchBytes'."),
+            result: z.string().optional()
+                .describe("Generic result or status message."),
+        },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": false,
+            "openWorldHint": false,
         },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
-    async ({ command, address, lines, value8 }) => {
+    async ({ command, address, lines, value8, values, length }) => {
         let tclCommand;
         switch (command) {
             case "getBlock":
@@ -530,16 +942,59 @@ export async function registerTools(server, emuDirectories) {
             case "writeByte":
                 tclCommand = `vpoke ${address} ${value8}`;
                 break;
+            case "searchBytes":
+                length = parseInt(address, 16) + length > 0x20000 ? 0x20000 - parseInt(address, 16) : length;
+                tclCommand = `set pattern { ${values} }
+								set len [llength $pattern]
+								set results ""
+								for {set i ${address}} {$i \<= [expr {${address} + ${length} - $len}]} {incr i} {
+									set match 1
+									for {set j 0} {$j \< $len} {incr j} {
+										if {[vpeek [expr {$i + $j}]] != [lindex $pattern $j]} {
+											set match 0; break
+										}
+									}
+									if {$match} { append results [format "Found at 0x%04X\n" $i] }
+								}
+								if {$results eq ""} { return "No matches found" }
+								return $results`;
+                break;
             default:
-                return getResponseContent([
-                    `Error: Unknown video memory command "${command}".`
-                ]);
+                return { content: [{ type: "text", text: `Error: Unknown video memory command "${command}".` }], isError: true };
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return getResponseContent([
-            response
-        ]);
+        if (isErrorResponse(response)) {
+            return { content: [{ type: "text", text: response }], isError: true };
+        }
+        let structuredContent;
+        switch (command) {
+            case "getBlock": {
+                structuredContent = { command, address, hexDump: response };
+                break;
+            }
+            case "readByte": {
+                const dec = parseInt(response.trim(), 10);
+                structuredContent = { command, address, decimalValue: dec, hexValue: `0x${dec.toString(16).toUpperCase().padStart(2, '0')}` };
+                break;
+            }
+            case "writeByte": {
+                structuredContent = { command, address, result: response || "Ok" };
+                break;
+            }
+            case "searchBytes": {
+                structuredContent = { command, address, length, values, result: response };
+                break;
+            }
+            default:
+                structuredContent = { command, result: response };
+        }
+        return {
+            content: [{ type: "text", text: response || "Ok" }],
+            structuredContent,
+            isError: false,
+        };
     });
+    // debug_breakpoints
     server.registerTool(
     // Name of the tool (used to call it)
     "debug_breakpoints", {
@@ -566,6 +1021,29 @@ export async function registerTools(server, emuDirectories) {
                 .optional()
                 .describe("Breakpoint name (e.g. bp#1). Used by [remove]"),
         },
+        // Structured output schema (MCP protocol 2025-11-25)
+        outputSchema: {
+            command: z.string()
+                .describe("The executed command name."),
+            createdName: z.string().optional()
+                .describe("Name assigned to the newly created breakpoint (e.g. 'bp#1'). Present for 'create'."),
+            createdAddress: z.string().optional()
+                .describe("Address of the newly created breakpoint. Present for 'create'."),
+            removedName: z.string().optional()
+                .describe("Name of the removed breakpoint. Present for 'remove'."),
+            breakpoints: z.array(z.object({
+                name: z.string(), address: z.string(), condition: z.string(), command: z.string()
+            })).optional()
+                .describe("List of active breakpoints. Present for 'list'."),
+            result: z.string().optional()
+                .describe("Generic result or status message."),
+        },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, address, bpname }) => {
@@ -581,15 +1059,37 @@ export async function registerTools(server, emuDirectories) {
                 tclCommand = 'debug list_bp';
                 break;
             default:
-                return getResponseContent([
-                    `Error: Unknown breakpoint command "${command}".`
-                ]);
+                return { content: [{ type: "text", text: `Error: Unknown breakpoint command "${command}".` }], isError: true };
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return getResponseContent([
-            response
-        ]);
+        if (isErrorResponse(response)) {
+            return { content: [{ type: "text", text: response }], isError: true };
+        }
+        let structuredContent;
+        switch (command) {
+            case "create": {
+                structuredContent = { command, createdName: response.trim(), createdAddress: address };
+                break;
+            }
+            case "remove": {
+                structuredContent = { command, removedName: bpname, result: response || "Ok" };
+                break;
+            }
+            case "list": {
+                const bps = parseBreakpoints(response);
+                structuredContent = { command, breakpoints: bps };
+                break;
+            }
+            default:
+                structuredContent = { command, result: response };
+        }
+        return {
+            content: [{ type: "text", text: response || "Ok" }],
+            structuredContent,
+            isError: false,
+        };
     });
+    // emu_savestates
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_savestates", {
@@ -611,6 +1111,12 @@ export async function registerTools(server, emuDirectories) {
                 .optional()
                 .describe("Name of the savestate to load/save. Used by [load, save]"),
         },
+        annotations: {
+            "readOnlyHint": false,
+            "destructiveHint": true,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, name }) => {
@@ -640,6 +1146,7 @@ export async function registerTools(server, emuDirectories) {
             response
         ]);
     });
+    // emu_replay
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_replay", {
@@ -684,6 +1191,31 @@ export async function registerTools(server, emuDirectories) {
                 .optional()
                 .describe("Filename to save/load replay. Used by [saveReplay, loadReplay]"),
         },
+        // Structured output schema (MCP protocol 2025-11-25)
+        outputSchema: {
+            command: z.string()
+                .describe("The executed command name."),
+            enabled: z.boolean().optional()
+                .describe("Whether replay is currently enabled. Present for 'status'."),
+            beginTime: z.number().optional()
+                .describe("Replay begin time in seconds. Present for 'status'."),
+            endTime: z.number().optional()
+                .describe("Replay end time in seconds. Present for 'status'."),
+            currentTime: z.number().optional()
+                .describe("Current replay time in seconds. Present for 'status'."),
+            snapshotCount: z.number().optional()
+                .describe("Number of snapshots collected. Present for 'status'."),
+            filename: z.string().optional()
+                .describe("Replay filename saved/loaded. Present for 'saveReplay' and 'loadReplay'."),
+            result: z.string().optional()
+                .describe("Generic result or status message."),
+        },
+        annotations: {
+            "readOnlyHint": false,
+            "destructiveHint": true,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, seconds, time, frames, filename }) => {
@@ -724,43 +1256,110 @@ export async function registerTools(server, emuDirectories) {
                 tclCommand = `reverse loadreplay ${filename}`;
                 break;
             default:
-                return getResponseContent([
-                    `Error: Unknown replay command "${command}".`
-                ]);
+                return { content: [{ type: "text", text: `Error: Unknown replay command "${command}".` }], isError: true };
         }
         const response = await openMSXInstance.sendCommand(tclCommand);
-        return getResponseContent([
-            response
-        ]);
+        if (isErrorResponse(response)) {
+            return { content: [{ type: "text", text: response }], isError: true };
+        }
+        let structuredContent;
+        switch (command) {
+            case "status": {
+                const status = parseReplayStatus(response);
+                structuredContent = {
+                    command,
+                    enabled: status.enabled,
+                    beginTime: status.begin,
+                    endTime: status.end,
+                    currentTime: status.current,
+                    snapshotCount: status.snapshotCount,
+                };
+                break;
+            }
+            case "saveReplay":
+            case "loadReplay": {
+                structuredContent = { command, filename: filename || response.trim(), result: response || "Ok" };
+                break;
+            }
+            default: {
+                structuredContent = { command, result: response || "Ok" };
+            }
+        }
+        return {
+            content: [{ type: "text", text: response || "Ok" }],
+            structuredContent,
+            isError: false,
+        };
     });
+    // emu_keyboard
     server.registerTool(
     // Name of the tool (used to call it)
     "emu_keyboard", {
         title: "Keyboard tools",
         // Description of the tool (what it does)
-        description: "Send a text to the openMSX emulator.",
+        description: "Send text or key combinations to the openMSX emulator.",
         // Schema for the tool (input validation)
         inputSchema: {
-            command: z.enum(["sendText"])
+            command: z.enum(["sendText", "sendKeyCombo"])
                 .describe(`Available commands:
 	'sendText <text>': type a string in the emulated MSX, this command automatically press and release keys in the MSX keyboard matrix.
+	'sendKeyCombo <keys> [holdTime]': press a combination of keys (e.g., CTRL+STOP to break a program).
 **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...
+**Important Note**: valid key names for sendKeyCombo include: SHIFT, CTRL, GRAPH, CAPS, CODE, F1-F5, ESC, TAB, STOP, BS, SELECT, RETURN/ENTER, SPACE, HOME, INS, DEL, LEFT, UP, DOWN, RIGHT.
+**Important Note**: MSX keyboards can experience key ghosting with 3+ simultaneous keys due to hardware limitations.
 `),
             text: z.string()
                 .min(1, 'Text to send is too short')
                 .max(200, 'Text to send is too long')
                 .optional()
-                .default('').describe("Text to send to the emulator via emulated keyboard"),
+                .describe("Text to send to the emulator via emulated keyboard"),
+            keys: z.array(z.string())
+                .min(1, 'At least one key must be specified')
+                .max(10, 'Too many keys (max 10)')
+                .optional()
+                .describe("Array of key names to press simultaneously (e.g., ['CTRL', 'STOP'])"),
+            holdTime: z.number()
+                .min(10, 'Hold time too short (min 10ms)')
+                .max(5000, 'Hold time too long (max 5000ms)')
+                .optional()
+                .default(100)
+                .describe("Time in milliseconds to hold keys down (default: 100)"),
+        },
+        annotations: {
+            "readOnlyHint": false,
+            "destructiveHint": true,
+            "idempotentHint": false,
+            "openWorldHint": false,
         },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
-    async ({ command, text }) => {
+    async ({ command, text, keys, holdTime }) => {
         let tclCommand;
         switch (command) {
             case "sendText":
+                if (!text) {
+                    return getResponseContent([
+                        'Error: No text provided for sendText command.'
+                    ]);
+                }
                 tclCommand = `type "${encodeTypeText(text)}"`;
                 break;
+            case "sendKeyCombo":
+                if (!keys || keys.length === 0) {
+                    return getResponseContent([
+                        'Error: No keys provided for sendKeyCombo command.'
+                    ]);
+                }
+                try {
+                    tclCommand = buildKeyComboCommand(keys, holdTime || 100);
+                }
+                catch (error) {
+                    return getResponseContent([
+                        `Error: ${error instanceof Error ? error.message : String(error)}`
+                    ]);
+                }
+                break;
             default:
                 return getResponseContent([
                     `Error: Unknown keyboard command "${command}".`
@@ -771,6 +1370,7 @@ export async function registerTools(server, emuDirectories) {
             response
         ]);
     });
+    // screen_shot
     server.registerTool(
     // Name of the tool (used to call it)
     "screen_shot", {
@@ -785,10 +1385,16 @@ export async function registerTools(server, emuDirectories) {
 	'to_file': take a screenshot and save it to a file, the file name is returned in the response.
 `),
         },
+        annotations: {
+            "readOnlyHint": false,
+            "destructiveHint": false,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command }) => {
-        const openmsxCommand = `screenshot -raw -prefix "${path.join(emuDirectories.OPENMSX_SCREENSHOT_DIR, 'mcp_')}"`;
+        const openmsxCommand = `screenshot -raw -doublesize -prefix "${path.join(emuDirectories.OPENMSX_SCREENSHOT_DIR, 'mcp_')}"`;
         const response = await openMSXInstance.sendCommand(openmsxCommand);
         switch (command) {
             case "as_image":
@@ -829,6 +1435,7 @@ export async function registerTools(server, emuDirectories) {
             `Error: Unknown screen_shot command "${command}".`
         ]);
     });
+    // screen_dump
     server.registerTool(
     // Name of the tool (used to call it)
     "screen_dump", {
@@ -845,6 +1452,12 @@ The parameter scrbasename is the name of the filename (without path) to save the
                 .default("screendump")
                 .describe("Screendump filename (without path nor extension) to save the screendump; default is 'screendump'"),
         },
+        annotations: {
+            "readOnlyHint": false,
+            "destructiveHint": true,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ scrbasename }) => {
@@ -855,6 +1468,7 @@ The parameter scrbasename is the name of the filename (without path) to save the
             response
         ]);
     });
+    // basic_programming
     server.registerTool(
     // Name of the tool (used to call it)
     "basic_programming", {
@@ -893,6 +1507,21 @@ The parameter scrbasename is the name of the filename (without path) to save the
                 .optional()
                 .describe("End line number to list/delete BASIC program lines. Used by [listProgramLines, deleteProgramLines]"),
         },
+        outputSchema: {
+            command: z.string().describe("The command that was executed."),
+            available: z.boolean().optional()
+                .describe("Whether BASIC mode is available. Present for 'isBasicAvailable'."),
+            program: z.string().optional()
+                .describe("BASIC program text. Present for 'getFullProgram' and 'getFullProgramAdvanced'."),
+            result: z.string().optional()
+                .describe("Generic result or status message."),
+        },
+        annotations: {
+            "readOnlyHint": false,
+            "destructiveHint": true,
+            "idempotentHint": false,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ command, program, startLine, endLine }) => {
@@ -978,10 +1607,34 @@ The parameter scrbasename is the name of the filename (without path) to save the
         if (response === undefined && tclCommand) {
             response = await openMSXInstance.sendCommand(tclCommand);
         }
-        return getResponseContent([
-            response !== undefined ? response : `Error: No response for command "${command}".`
-        ]);
+        if (response === undefined) {
+            return { content: [{ type: "text", text: `Error: No response for command "${command}".` }], isError: true };
+        }
+        if (isErrorResponse(response)) {
+            return { content: [{ type: "text", text: response }], isError: true };
+        }
+        let structuredContent;
+        switch (command) {
+            case "isBasicAvailable": {
+                structuredContent = { command, available: response === "true" };
+                break;
+            }
+            case "getFullProgram":
+            case "getFullProgramAdvanced": {
+                structuredContent = { command, program: response };
+                break;
+            }
+            default: {
+                structuredContent = { command, result: response || "Ok" };
+            }
+        }
+        return {
+            content: [{ type: "text", text: response || "Ok" }],
+            structuredContent,
+            isError: false,
+        };
     });
+    // vector_db_query
     server.registerTool(
     // Name of the tool (used to call it)
     "vector_db_query", {
@@ -999,15 +1652,21 @@ The response is the list of the top 10 result resources that match the query, in
                 .max(100, 'Query string too long')
                 .describe("Query string to search in the Vector DB resources, case-insensitive and may contain spaces."),
         },
-        // outputSchema: {
-        // 	results: z.array(z.object({
-        // 		score: z.number().describe("Proximity score of the result to the query, higher is better."),
-        // 		title: z.string().describe("Title of the resource."),
-        // 		uri: z.string().describe("URI of the resource, which can be used to access the resource."),
-        // 		document: z.string().describe("Document chunk of the resource, retrieved from the Vector DB."),
-        // 		id: z.string().describe("Unique resource chunk ID, used internally by the Vector DB."),
-        // 	}))
-        // },
+        outputSchema: {
+            results: z.array(z.object({
+                score: z.string().describe("Proximity score of the result to the query, higher is better."),
+                title: z.string().describe("Title of the resource."),
+                uri: z.string().describe("URI of the resource, which can be used to access the resource."),
+                document: z.string().describe("Document chunk of the resource, retrieved from the Vector DB."),
+                id: z.string().describe("Unique resource chunk ID, used internally by the Vector DB."),
+            }))
+        },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": true,
+            "openWorldHint": false,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ query }) => {
@@ -1017,13 +1676,14 @@ The response is the list of the top 10 result resources that match the query, in
                     type: "text",
                     text: JSON.stringify(results),
                 }],
-            results: results,
+            structuredContent: { results },
             isError: false,
         };
     });
     // ============================================================================
     // Register a tool to get a specific MSX documentation resource
     // Retrieve MCP resources for MCP clients that don't support MCP resources.
+    // msxdocs_resource_get
     server.registerTool(
     // Name of the tool (used to call it)
     "msxdocs_resource_get", {
@@ -1035,6 +1695,12 @@ The response is the list of the top 10 result resources that match the query, in
             resourceName: z.enum(getRegisteredResourcesList().map(res => res.resource.name))
                 .describe("Name of the resource to obtain, e.g. 'msxdocs_programming_interrupts'"),
         },
+        annotations: {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": true,
+            "openWorldHint": true,
+        },
     }, 
     // Handler for the tool (function to be executed when the tool is called)
     async ({ resourceName }, extra) => {