@nataliapc/mcp-openmsx 1.2.4 → 1.2.6

package/dist/utils.js

@@ -236,6 +236,93 @@ export function encodeTypeText(text) {
         return char;
     });
 }
+/**
+ * MSX keyboard matrix mapping for International (QWERTY) layout.
+ * Maps key names to [row, mask] coordinates in the MSX keyboard matrix.
+ *
+ * The MSX keyboard matrix is 11 rows × 8 bits. To press a key:
+ * - Use `keymatrixdown <row> <mask>` in openMSX TCL
+ * - Use `keymatrixup <row> <mask>` to release
+ *
+ * Example: CTRL is at row 6, bit 1 (mask 0x02)
+ * - Press: `keymatrixdown 6 0x02`
+ * - Release: `keymatrixup 6 0x02`
+ *
+ * Note: Rows 6-8 (modifier keys, special keys, navigation) are consistent
+ * across all MSX models. Other rows may vary by keyboard layout.
+ *
+ * Reference: mcp-server/resources/others/keyboard_matrices.md
+ */
+export const MSX_KEY_MATRIX = {
+    // Row 6: Modifier and function keys
+    'SHIFT': [6, 0x01], // bit 0
+    'CTRL': [6, 0x02], // bit 1
+    'GRAPH': [6, 0x04], // bit 2
+    'CAPS': [6, 0x08], // bit 3
+    'CODE': [6, 0x10], // bit 4
+    'F1': [6, 0x20], // bit 5
+    'F2': [6, 0x40], // bit 6
+    'F3': [6, 0x80], // bit 7
+    // Row 7: Special keys
+    'F4': [7, 0x01], // bit 0
+    'F5': [7, 0x02], // bit 1
+    'ESC': [7, 0x04], // bit 2
+    'TAB': [7, 0x08], // bit 3
+    'STOP': [7, 0x10], // bit 4
+    'BS': [7, 0x20], // bit 5
+    'SELECT': [7, 0x40], // bit 6
+    'RETURN': [7, 0x80], // bit 7
+    'ENTER': [7, 0x80], // bit 7 (alias for RETURN)
+    // Row 8: Navigation and editing keys
+    'SPACE': [8, 0x01], // bit 0
+    'HOME': [8, 0x02], // bit 1
+    'INS': [8, 0x04], // bit 2
+    'DEL': [8, 0x08], // bit 3
+    'LEFT': [8, 0x10], // bit 4
+    'UP': [8, 0x20], // bit 5
+    'DOWN': [8, 0x40], // bit 6
+    'RIGHT': [8, 0x80], // bit 7
+};
+/**
+ * Build a TCL command to press and release a combination of keys on the MSX keyboard.
+ *
+ * @param keys - Array of key names (e.g., ["CTRL", "STOP"])
+ * @param holdTimeMs - Time in milliseconds to hold keys down (default: 100)
+ * @returns TCL command string for openMSX
+ * @throws Error if any key name is not recognized
+ *
+ * @example
+ * // Press CTRL+STOP for 100ms
+ * buildKeyComboCommand(["CTRL", "STOP"], 100)
+ * // Returns: "keymatrixdown 6 0x02 ; keymatrixdown 7 0x10 ; after time 0.1 { keymatrixup 6 0x02 ; keymatrixup 7 0x10 }"
+ */
+export function buildKeyComboCommand(keys, holdTimeMs = 100) {
+    if (!keys || keys.length === 0) {
+        throw new Error('No keys provided for key combination');
+    }
+    // Validate all keys exist and collect their matrix coordinates
+    const keyCoords = [];
+    for (const key of keys) {
+        const keyUpper = key.toUpperCase();
+        if (!MSX_KEY_MATRIX[keyUpper]) {
+            const validKeys = Object.keys(MSX_KEY_MATRIX).join(', ');
+            throw new Error(`Unknown key "${key}". Valid keys: ${validKeys}`);
+        }
+        keyCoords.push(MSX_KEY_MATRIX[keyUpper]);
+    }
+    // Build press commands: keymatrixdown <row> <mask> for each key
+    const pressCommands = keyCoords
+        .map(([row, mask]) => `keymatrixdown ${row} ${mask}`)
+        .join(' ; ');
+    // Build release commands: keymatrixup <row> <mask> for each key
+    const releaseCommands = keyCoords
+        .map(([row, mask]) => `keymatrixup ${row} ${mask}`)
+        .join(' ; ');
+    // Convert milliseconds to seconds for openMSX 'after time' command
+    const holdTimeSec = holdTimeMs / 1000;
+    // Build full TCL command: press all keys, wait, then release all keys
+    return `${pressCommands} ; after time ${holdTimeSec} { ${releaseCommands} }`;
+}
 /**
  * Check if a response is an error response
  * @param response - The response string to check
@@ -261,6 +348,124 @@ export function getResponseContent(response, isError = false) {
         isError: hasError
     };
 }
+/**
+ * Parse the output of the openMSX 'cpuregs' TCL command into a structured object.
+ * The output format is:
+ *   AF =0044  BC =0000  DE =0000  HL =F380
+ *   AF'=0000  BC'=0000  DE'=0000  HL'=0000
+ *   IX =0000  IY =0000  PC =632F  SP =F37E
+ *   I  =00    R  =5D    IM =01    IFF=01
+ * @param response - Raw text response from the cpuregs command
+ * @returns Record mapping register names to hex values
+ */
+export function parseCpuRegs(response) {
+    const registers = {};
+    const regex = /(\w+'?)\s*=\s*([0-9a-fA-F]+)/g;
+    let match;
+    while ((match = regex.exec(response)) !== null) {
+        registers[match[1]] = match[2];
+    }
+    return registers;
+}
+/**
+ * Check if a CPU register name corresponds to a 16-bit register.
+ * @param register - Register name (e.g. 'pc', 'a', 'ix')
+ * @returns true if the register is 16-bit
+ */
+export function is16bitRegister(register) {
+    return ["pc", "sp", "ix", "iy", "af", "bc", "de", "hl"].includes(register.toLowerCase());
+}
+/**
+ * Parse the output of the openMSX 'vdpregs' TCL command into a structured object.
+ * Output format:
+ *  0 : 0x04    8 : 0x08   16 : 0x00   24 : 0x00
+ *  1 : 0x70    9 : 0x02   17 : 0x18   25 : 0x00
+ *  ...
+ * @param response - Raw text response from the vdpregs command
+ * @returns Record mapping register number (string) to hex value string
+ */
+export function parseVdpRegs(response) {
+    const registers = {};
+    const regex = /(\d+)\s*:\s*(0x[0-9a-fA-F]{2})/g;
+    let match;
+    while ((match = regex.exec(response)) !== null) {
+        registers[match[1]] = match[2];
+    }
+    return registers;
+}
+/**
+ * Parse the output of the openMSX 'palette' TCL command into a structured object.
+ * Output format:
+ *  0:000  4:117  8:711  c:141
+ *  1:000  5:237  9:733  d:625
+ *  ...
+ * @param response - Raw text response from the palette command
+ * @returns Array of 16 palette entries with index, r, g, b values
+ */
+export function parsePalette(response) {
+    const palette = [];
+    const regex = /([0-9a-fA-F]):([0-7])([0-7])([0-7])/g;
+    let match;
+    while ((match = regex.exec(response)) !== null) {
+        palette.push({
+            index: parseInt(match[1], 16),
+            r: parseInt(match[2]),
+            g: parseInt(match[3]),
+            b: parseInt(match[4]),
+            rgb: match[2] + match[3] + match[4],
+        });
+    }
+    palette.sort((a, b) => a.index - b.index);
+    return palette;
+}
+/**
+ * Parse the output of the openMSX 'debug list_bp' TCL command into a structured array.
+ * Output format:
+ *  bp#1 0x4000 {} {debug break}
+ *  bp#2 0x8000 {} {debug break}
+ * @param response - Raw text response from the debug list_bp command
+ * @returns Array of breakpoint objects
+ */
+export function parseBreakpoints(response) {
+    if (!response.trim())
+        return [];
+    const breakpoints = [];
+    const lines = response.trim().split('\n');
+    for (const line of lines) {
+        const match = line.match(/^(\S+)\s+(0x[0-9a-fA-F]{4})\s+\{([^}]*)\}\s+\{([^}]*)\}/);
+        if (match) {
+            breakpoints.push({
+                name: match[1],
+                address: match[2],
+                condition: match[3],
+                command: match[4],
+            });
+        }
+    }
+    return breakpoints;
+}
+/**
+ * Parse the output of the openMSX 'reverse status' TCL command into a structured object.
+ * Output format:
+ *  status enabled begin 0.0 end 294.08 current 294.08 snapshots {...} last_event 0.0
+ * @param response - Raw text response from the reverse status command
+ * @returns Structured replay status object
+ */
+export function parseReplayStatus(response) {
+    const statusMatch = response.match(/status\s+(\w+)/);
+    const beginMatch = response.match(/begin\s+([\d.]+)/);
+    const endMatch = response.match(/end\s+([\d.]+)/);
+    const currentMatch = response.match(/current\s+([\d.]+)/);
+    const snapshotsMatch = response.match(/snapshots\s+\{([^}]*)\}/);
+    const snapshotCount = snapshotsMatch ? snapshotsMatch[1].trim().split(/\s+/).filter(s => s).length : 0;
+    return {
+        enabled: statusMatch ? statusMatch[1] === 'enabled' : false,
+        begin: beginMatch ? parseFloat(beginMatch[1]) : 0,
+        end: endMatch ? parseFloat(endMatch[1]) : 0,
+        current: currentMatch ? parseFloat(currentMatch[1]) : 0,
+        snapshotCount,
+    };
+}
 /*
  * Sleep for a specified number of milliseconds
  * @param ms - Number of milliseconds to sleep
@@ -269,3 +474,27 @@ export function getResponseContent(response, isError = false) {
 export function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/**
+ * Sleep for a specified number of milliseconds, with support for cancellation via AbortSignal.
+ * @param ms - Number of milliseconds to sleep
+ * @param signal - AbortSignal to cancel the sleep early
+ * @returns Promise that resolves after the specified time, or rejects if aborted
+ * @throws {DOMException} If the signal is aborted (with name 'AbortError')
+ */
+export function sleepWithAbort(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",
@@ -38,24 +38,25 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.16.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "@themaximalist/embeddings.js": "^0.1.3",
-    "@types/express": "^5.0.2",
+    "@types/express": "^5.0.6",
+    "@types/mime-types": "^3.0.1",
     "@xenova/transformers": "^2.17.2",
-    "debug": "^4.4.1",
-    "express": "^5.1.0",
+    "debug": "^4.4.3",
+    "express": "^5.2.1",
+    "mime-types": "^3.0.2",
     "sanitize-html": "^2.17.0",
-    "tsx": "^4.7.1",
+    "tsx": "^4.21.0",
     "vectra": "^0.11.1",
-    "zod": "^3.24.4"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@modelcontextprotocol/inspector": "^0.15.0",
-    "@types/mime-types": "^3.0.1",
-    "@types/node": "^24.0.15",
+    "@modelcontextprotocol/inspector": "^0.20.0",
+    "@types/node": "^25.2.3",
     "@types/sanitize-html": "^2.16.0",
     "shx": "^0.4.0",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.3"
   },
   "files": [
     "dist/**/*",

package/resources/programming/basic_wiki/_toc.json

@@ -119,7 +119,7 @@
         },
         {
             "title": "CLOAD? - Verify Cassette Load",
-            "uri": "msxdocs://basic_wiki/CLOAD?",
+            "uri": "msxdocs://basic_wiki/CLOAD_Q",
             "description": "Verifies a BASIC program on cassette tape against the program in memory."
         },
         {