@nataliapc/mcp-openmsx 1.1.5 → 1.1.8

package/README.md

@@ -65,6 +65,44 @@ The MCP server translates high-level commands from your Copilot AI into `TCL` co
 - `screen_shot`: Capture emulator screen: _`as_image`, `to_file`_.
 - `screen_dump`: Export screen data as BASIC BSAVE instruction.
 
+## 📚 Available MCP Resources
+
+### What are MCP Resources?
+
+MCP resources are structured data sets, documentation, and helper files that extend the capabilities of the MCP server. They provide essential information such as machine definitions, extension lists, media templates, and programming examples, enabling more powerful automation, testing, and development workflows for MSX software within the MCP-openMSX environment.
+
+### Available Resources
+
+There are more than 60 resources available, some included directly in the MCP and others accessible via download when queried. They are organized into the following categories:
+
+- `Processors` (Z80, R800)
+- `Bios` (Bios ROM, DOS ROM, SUBROM, ...)
+- `System`
+- `Audio`
+- `Video`
+- `Programming` (ASM, BASIC, ...)
+- `MSX-DOS`
+- `MSX-UNAPI`
+
+And two books:
+
+- `MSX2 Technical Handbook`
+- `The MSX Red Book`
+
+### Resources from:
+
+- [Grauw MSX Assembly Page](https://map.grauw.nl/)
+- [Z80 Heaven Wiki](http://z80-heaven.wikidot.com/)
+- [The MSX Red Book](https://github.com/gseidler/The-MSX-Red-Book)
+- [MSX2 Technical Handbook](https://github.com/Konamiman/MSX2-Technical-Handbook)
+- [Konamiman MSX-UNAPI-specification](https://github.com/Konamiman/MSX-UNAPI-specification)
+- [BiFi MSX Net](http://bifi.msxnet.org/msxnet/)
+- [MSX Wiki](https://www.msx.org/wiki/Main_Page)
+- [MSX Banzai!](http://msxbanzai.tni.nl/)
+
+Thanks to the authors of these resources, who have made them available under various licenses. This MCP server includes some of these resources to enhance the development experience.
+
+The rights to these resources belong to their respective authors and are distributed under the licenses they have defined.
 
 ## 🚀 Quick Start
 

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,11 +18,13 @@ 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 } from "./utils.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';
@@ -35,7 +37,7 @@ 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", 
@@ -334,15 +336,15 @@ function registerAllTools(server) {
 			'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. 0x0000)."
+		"**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 }) => {
@@ -674,7 +676,7 @@ function registerAllTools(server) {
         switch (command) {
             case "as_image":
                 try {
-                    // Check if the response is a file path using fstat
+                    // Check if the response is a file path
                     if (!response || !response.startsWith(OPENMSX_SCREENSHOT_DIR) || !response.endsWith('.png')) {
                         throw new Error(`Invalid screenshot "${response}"`);
                     }
@@ -745,6 +747,7 @@ function registerAllTools(server) {
 			'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)
     {
@@ -824,17 +827,101 @@ function registerAllTools(server) {
             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',
+                        }],
+                };
+            });
+        });
+    }
+    ;
 }
-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 => isErrorResponse(line));
-    return {
-        content: response.map(line => ({
-            type: "text",
-            text: line == '' ? "Ok" : line,
-        })),
-        isError: hasError
-    };
+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];
+}
+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
@@ -933,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 {
@@ -961,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;
 }
 // ============================================================================
@@ -1012,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) => {

package/dist/utils.js

@@ -104,3 +104,20 @@ export function encodeTypeText(text) {
 export function isErrorResponse(response) {
     return response.startsWith('Error:') || response.startsWith('error:');
 }
+/**
+ * Get the content of a response, formatting it as a CallToolResult
+ * @param response - Array of strings representing the response lines
+ * @param isError - Optional boolean indicating if the response is an error
+ * @returns CallToolResult - Formatted response content
+ */
+export 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 => isErrorResponse(line));
+    return {
+        content: response.map(line => ({
+            type: "text",
+            text: line == '' ? "Ok" : line,
+        })),
+        isError: hasError
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nataliapc/mcp-openmsx",
-  "version": "1.1.5",
+  "version": "1.1.8",
   "description": "Model context protocol server for openMSX automation and control",
   "main": "dist/server.js",
   "type": "module",
@@ -45,12 +45,15 @@
     "zod": "^3.24.4"
   },
   "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.15.0",
+    "@types/mime-types": "^3.0.1",
     "@types/node": "^22.15.27",
     "shx": "^0.4.0",
     "typescript": "^5.8.3"
   },
   "files": [
     "dist/**/*",
+    "resources/**/*",
     "README.md",
     "LICENSE"
   ],

package/resources/audio/toc.json

@@ -0,0 +1,31 @@
+{
+    "title": "MSX Technical Audio info for MSX",
+    "description": "MSX Technical Audio info for MSX",
+    "toc": [
+        {
+            "title": "PSG Registers",
+            "uri": "https://www.msx.org/wiki/PSG_Registers",
+            "description": "Complete reference for MSX PSG (Programmable Sound Generator) registers covering all 16 registers including frequency control, white noise control, voice and I/O port control, amplitude and volume control, envelope form and period control, and I/O parallel port registers. Includes BIOS routines WRTPSG, RDPSG, and GICINI for PSG access and initialization."
+        },
+        {
+            "title": "Konami SCC Sound Chip",
+            "uri": "http://bifi.msxnet.org/msxnet/tech/scc",
+            "description": "Technical documentation for Konami's SCC (Sound Creative Chip) used in MSX cartridges. The SCC provides 5-channel wavetable synthesis with custom waveforms, offering enhanced audio capabilities beyond the standard PSG. Commonly found in Konami game cartridges like Gradius series, providing richer sound effects and music."
+        },
+        {
+            "title": "Konami SCC+ Sound Chip",
+            "uri": "http://bifi.msxnet.org/msxnet/tech/soundcartridge",
+            "description": "Technical documentation for Konami's enhanced SCC+ (Sound Creative Chip Plus) found in later MSX sound cartridges. Improved version of the original SCC providing enhanced wavetable synthesis capabilities, additional sound channels, and better audio quality. Used in advanced Konami cartridges and dedicated sound cartridges for expanded audio functionality."
+        },
+        {
+            "title": "MSX-MIDI",
+            "uri": "https://map.grauw.nl/resources/midi/msx-midi.php",
+            "description": "Complete technical documentation for MSX-MIDI interface covering hardware configuration, MIDI data communication using 8251 IC, baud rate generator with 8253/8254 timer IC, I/O port assignments (0E8H, 0E9H), internal vs external cartridge implementations, and BASIC extensions. Available only for MSX turbo R and later systems with 16K ROM containing MIDI functionality."
+        },
+        {
+            "title": "MGSDRV MML 1.1",
+            "uri": "https://mus.msx.click/index.php?title=MGSDRV_MML_11",
+            "description": "Complete documentation for MGSC MML compiler version 1.11 by Ain (1992-93) that converts MML (Music Macro Language) text files to MGS formatted play data for MGSDRV. Covers control functions, OPLL modes (FM 9 sound/FM 6+rhythm), machine vendor codes (SONY, Panasonic, SANYO), macro definitions, tone definitions, tempo control, and compilation options including real-time playback and debugging features."
+        }
+    ]
+}

package/resources/bios/Calling_BIOS_from_MSX-DOS.md

@@ -0,0 +1,75 @@
+# Calling the BIOS from MSX-DOS  
+
+In the MSX-DOS environment there is no special entry for calling the MSX BIOS, however you can simply use an interslot call to reach it.
+
+You can use this method to call the BIOS:
+```
+CALSLT:      EQU    #001C
+EXPTBL:      EQU    #FCC1
+
+Call\_Slot:   ld     iy,(EXPTBL-1)       ;BIOS slot in iyh
+             ld     ix,nnnn             ;address of BIOS routine
+             call   CALSLT              ;interslot call
+```
+
+## The SUBROM
+
+You can’t call the SUBROM from MSX-DOS as you would normally, the reason for this is that both `EXTROM` and `CALSLT` use the `IX` register to pass parameters. Calling directly to the SUBROM doesn’t work either, because using an interslot call to call the SUBROM is not allowed per the MSX2 standard. The reason for this, according to _Alex Wulms_ in _MCM 48_, is that some DiskROMs couldn’t handle the the SUBROM being in page 0.
+
+The official means to call the SUBROM from MSX-DOS is by using the following routine, provided by ASCII:
+```
+; CALSUB
+;
+; In: IX = address of routine in MSX2 SUBROM
+;     AF, HL, DE, BC = parameters for the routine
+;
+; Out: AF, HL, DE, BC = depending on the routine
+;
+; Changes: IX, IY, AF', BC', DE', HL'
+;
+; Call MSX2 subrom from MSXDOS. Should work with all versions of MSXDOS.
+;
+; Notice: NMI hook will be changed. This should pose no problem as NMI is
+; not supported on the MSX at all.
+;
+CALSLT:  EQU    #001C
+NMI:     EQU    #0066
+EXTROM:  EQU    #015f
+EXPTBL:  EQU    #fcc1
+H\_NMI:   EQU    #fdd6
+;
+CALSUB:  exx
+         ex     af,af'       ; store all registers
+         ld     hl,EXTROM
+         push   hl
+         ld     hl,#C300
+         push   hl           ; push NOP ; JP EXTROM
+         push   ix
+         ld     hl,#21DD
+         push   hl           ; push LD IX,<entry>
+         ld     hl,#3333
+         push   hl           ; push INC SP; INC SP
+         ld     hl,0
+         add    hl,sp        ; HL = offset of routine
+         ld     a,#C3
+         ld     (H\_NMI),a
+         ld     (H\_NMI+1),hl ; JP <routine> in NMI hook
+         ex     af,af'
+         exx                 ; restore all registers
+         ld     ix,NMI
+         ld     iy,(EXPTBL-1)
+         call   CALLSLT      ; call NMI-hook via NMI entry in ROMBIOS
+                             ; NMI-hook will call SUBROM
+         exx
+         ex     af,af'       ; store all returned registers
+         ld     hl,10
+         add    hl,sp
+         ld     sp,hl        ; remove routine from stack
+         ex     af,af'
+         exx                 ; restore all returned registers
+         ret
+```
+
+~Grauw
+
+© 2025 MSX Assembly Page. MSX is a trademark of MSX Licensing Corporation.