c64bridge 0.9.0 → 0.9.2

package/mcp/schemas/c64_graphics.schema.json

@@ -8,7 +8,8 @@
         "render_petscii_art",
         "render_petscii_text",
         "render_sprite",
-        "render_bitmap"
+        "render_bitmap",
+        "get_display_state"
       ],
       "description": "Selects the operation."
     },
@@ -228,6 +229,417 @@
   "required": [
     "op"
   ],
-  "description": "Graphics operations available via the c64_graphics tool.\n\nOperations:\n- capture_frame: Capture one or more complete video frames from the active backend.\n- render_petscii_art: Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64.\n- render_petscii_text: Display PETSCII text with optional border and background colours.\n- render_sprite: Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly.\n- render_bitmap: Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it.",
-  "additionalProperties": false
+  "description": "Graphics operations available via the c64_graphics tool.\n\nOperations:\n- capture_frame: Capture one or more complete video frames from the active backend. Required inputs: none. Optional inputs: count, includePixels, encoding.\n- render_petscii_art: Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64. Required inputs: none. Optional inputs: prompt, text, maxWidth, maxHeight, borderColor, backgroundColor, foregroundColor, dryRun, bitmap.\n- render_petscii_text: Display PETSCII text with optional border and background colours. Required inputs: text. Optional inputs: borderColor, backgroundColor.\n- render_sprite: Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly. Required inputs: sprite. Optional inputs: index, x, y, color, multicolour.\n- render_bitmap: Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it. Required inputs: imagePath, format. Optional inputs: bitmapAddress, screenAddress, borderColor, backgroundColor, preserveAspect.\n- get_display_state: Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical. Required inputs: none.",
+  "additionalProperties": false,
+  "x-c64bridge-operations": [
+    {
+      "op": "capture_frame",
+      "description": "Capture one or more complete video frames from the active backend.",
+      "required": [],
+      "optional": [
+        "count",
+        "includePixels",
+        "encoding"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Capture one or more complete video frames from the active backend.",
+        "properties": {
+          "op": {
+            "const": "capture_frame"
+          },
+          "count": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Number of frames to capture.",
+            "minimum": 1,
+            "maximum": 32,
+            "default": 1
+          },
+          "includePixels": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Include pixel payload bytes in the response.",
+            "default": true
+          },
+          "encoding": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Encoding used for the pixel payload when included.",
+            "enum": [
+              "base64",
+              "hex"
+            ],
+            "default": "base64"
+          }
+        },
+        "required": [
+          "op"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "op": "render_petscii_art",
+      "description": "Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64.",
+      "required": [],
+      "optional": [
+        "prompt",
+        "text",
+        "maxWidth",
+        "maxHeight",
+        "borderColor",
+        "backgroundColor",
+        "foregroundColor",
+        "dryRun",
+        "bitmap"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64.",
+        "properties": {
+          "prompt": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Natural language prompt describing the desired PETSCII art.",
+            "minLength": 1
+          },
+          "text": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Exact text to render in PETSCII (overrides prompt derivation).",
+            "minLength": 1
+          },
+          "maxWidth": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Maximum bitmap width in pixels (1-320).",
+            "minimum": 1,
+            "maximum": 320
+          },
+          "maxHeight": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Maximum bitmap height in pixels (1-200).",
+            "minimum": 1,
+            "maximum": 200
+          },
+          "borderColor": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Border colour index (0-15).",
+            "minimum": 0,
+            "maximum": 15
+          },
+          "backgroundColor": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Background colour index (0-15).",
+            "minimum": 0,
+            "maximum": 15
+          },
+          "foregroundColor": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Foreground colour index (0-15).",
+            "minimum": 0,
+            "maximum": 15
+          },
+          "dryRun": {
+            "type": "boolean",
+            "description": "When true, skip uploading the generated BASIC program to the C64.",
+            "default": false
+          },
+          "bitmap": {
+            "description": "Explicit bitmap definition for PETSCII rendering.",
+            "type": [
+              "object",
+              "null"
+            ],
+            "properties": {
+              "width": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 320
+              },
+              "height": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 200
+              },
+              "pixels": {
+                "type": "array",
+                "items": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 1
+                }
+              }
+            },
+            "required": [
+              "width",
+              "height",
+              "pixels"
+            ],
+            "additionalProperties": false
+          },
+          "op": {
+            "const": "render_petscii_art"
+          }
+        },
+        "additionalProperties": false,
+        "required": [
+          "op"
+        ]
+      }
+    },
+    {
+      "op": "render_petscii_text",
+      "description": "Display PETSCII text with optional border and background colours.",
+      "required": [
+        "text"
+      ],
+      "optional": [
+        "borderColor",
+        "backgroundColor"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Display PETSCII text with optional border and background colours.",
+        "properties": {
+          "text": {
+            "type": "string",
+            "description": "The PETSCII text to print after clearing the screen.",
+            "minLength": 1
+          },
+          "borderColor": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Border colour index (0-15).",
+            "minimum": 0,
+            "maximum": 15
+          },
+          "backgroundColor": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Background colour index (0-15).",
+            "minimum": 0,
+            "maximum": 15
+          },
+          "op": {
+            "const": "render_petscii_text"
+          }
+        },
+        "required": [
+          "text",
+          "op"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "op": "render_sprite",
+      "description": "Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly.",
+      "required": [
+        "sprite"
+      ],
+      "optional": [
+        "index",
+        "x",
+        "y",
+        "color",
+        "multicolour"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly.",
+        "properties": {
+          "sprite": {
+            "description": "63-byte sprite definition provided as base64/hex string or array of bytes.",
+            "type": [
+              "string",
+              "array"
+            ],
+            "items": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 255
+            },
+            "minItems": 63,
+            "maxItems": 63
+          },
+          "index": {
+            "type": "integer",
+            "description": "Sprite index (0-7) to configure in screen memory.",
+            "minimum": 0,
+            "maximum": 7,
+            "default": 0
+          },
+          "x": {
+            "type": "integer",
+            "description": "Sprite X position (0-511).",
+            "minimum": 0,
+            "maximum": 511,
+            "default": 100
+          },
+          "y": {
+            "type": "integer",
+            "description": "Sprite Y position (0-255).",
+            "minimum": 0,
+            "maximum": 255,
+            "default": 100
+          },
+          "color": {
+            "type": "integer",
+            "description": "Sprite colour index (0-15).",
+            "minimum": 0,
+            "maximum": 15,
+            "default": 1
+          },
+          "multicolour": {
+            "type": "boolean",
+            "description": "Enable multicolour mode for the sprite.",
+            "default": false
+          },
+          "op": {
+            "const": "render_sprite"
+          }
+        },
+        "required": [
+          "sprite",
+          "op"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "op": "render_bitmap",
+      "description": "Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it.",
+      "required": [
+        "imagePath",
+        "format"
+      ],
+      "optional": [
+        "bitmapAddress",
+        "screenAddress",
+        "borderColor",
+        "backgroundColor",
+        "preserveAspect"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it.",
+        "properties": {
+          "imagePath": {
+            "type": "string",
+            "description": "Filesystem path of the source image (PNG, JPEG, BMP, GIF, TIFF, and other Jimp-supported formats).",
+            "minLength": 1
+          },
+          "format": {
+            "description": "Bitmap encoding mode to generate for the VIC-II display.",
+            "type": "string",
+            "enum": [
+              "hires",
+              "multicolor"
+            ]
+          },
+          "bitmapAddress": {
+            "description": "Absolute C64 memory address, provided as an integer or hex string such as $2000.",
+            "type": [
+              "integer",
+              "string",
+              "null"
+            ],
+            "default": 8192
+          },
+          "screenAddress": {
+            "description": "Absolute C64 memory address, provided as an integer or hex string such as $2000.",
+            "type": [
+              "integer",
+              "string",
+              "null"
+            ],
+            "default": 1024
+          },
+          "borderColor": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Border colour index (0-15).",
+            "minimum": 0,
+            "maximum": 15,
+            "default": 0
+          },
+          "backgroundColor": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Background colour index (0-15). Used for multicolor mode and aspect-ratio padding.",
+            "minimum": 0,
+            "maximum": 15,
+            "default": 0
+          },
+          "preserveAspect": {
+            "type": "boolean",
+            "description": "Preserve the source image aspect ratio and pad with the background colour.",
+            "default": true
+          },
+          "op": {
+            "const": "render_bitmap"
+          }
+        },
+        "required": [
+          "imagePath",
+          "format",
+          "op"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "op": "get_display_state",
+      "description": "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical.",
+      "required": [],
+      "optional": [],
+      "inputSchema": {
+        "type": "object",
+        "description": "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical.",
+        "properties": {
+          "op": {
+            "const": "get_display_state"
+          }
+        },
+        "required": [
+          "op"
+        ],
+        "additionalProperties": false
+      }
+    }
+  ]
 }

package/mcp/schemas/c64_input.schema.json

@@ -0,0 +1,254 @@
+{
+  "type": "object",
+  "properties": {
+    "op": {
+      "type": "string",
+      "enum": [
+        "write_text",
+        "key",
+        "joystick"
+      ],
+      "description": "Selects the operation."
+    },
+    "text": {
+      "type": "string",
+      "description": "Text to type. Use {RETURN}, {CLR}, {F1}…{F8}, {UP/DOWN/LEFT/RIGHT}, colour names, etc.",
+      "minLength": 1,
+      "maxLength": 512
+    },
+    "delayMs": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "description": "Delay in ms after sending (default 0).",
+      "minimum": 0,
+      "maximum": 10000,
+      "default": 0
+    },
+    "key": {
+      "type": "string",
+      "description": "Key to press: a printable character, or a PETSCII token name (RETURN, F1…F8, UP, etc.).",
+      "minLength": 1,
+      "maxLength": 32
+    },
+    "durationMs": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "description": "Delay in ms after each queued key press before the next press (default 0 = no delay).",
+      "minimum": 0,
+      "maximum": 5000,
+      "default": 0
+    },
+    "count": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "description": "Number of times to press the key (default 1).",
+      "minimum": 1,
+      "maximum": 100,
+      "default": 1
+    },
+    "port": {
+      "type": "integer",
+      "description": "Joystick port (1 = $DC01, 2 = $DC00).",
+      "minimum": 1,
+      "maximum": 2
+    },
+    "controls": {
+      "type": "array",
+      "description": "List of controls to activate simultaneously.",
+      "items": {
+        "type": "string",
+        "description": "Control to activate.",
+        "enum": [
+          "up",
+          "down",
+          "left",
+          "right",
+          "fire"
+        ]
+      },
+      "minItems": 0
+    },
+    "action": {
+      "type": "string",
+      "description": "press = hold until a release call; release = restore all bits; tap = press then release after durationMs.",
+      "enum": [
+        "press",
+        "release",
+        "tap"
+      ]
+    }
+  },
+  "required": [
+    "op"
+  ],
+  "description": "Input operations: write_text, key, joystick.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input by writing directly to CIA1 Port A/B registers. Required inputs: port, controls, action. Optional inputs: durationMs.",
+  "additionalProperties": false,
+  "x-c64bridge-operations": [
+    {
+      "op": "write_text",
+      "description": "Send a text string to the keyboard buffer, with PETSCII token expansion.",
+      "required": [
+        "text"
+      ],
+      "optional": [
+        "delayMs"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Send a text string to the keyboard buffer, with PETSCII token expansion.",
+        "properties": {
+          "op": {
+            "const": "write_text"
+          },
+          "text": {
+            "type": "string",
+            "description": "Text to type. Use {RETURN}, {CLR}, {F1}…{F8}, {UP/DOWN/LEFT/RIGHT}, colour names, etc.",
+            "minLength": 1,
+            "maxLength": 512
+          },
+          "delayMs": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Delay in ms after sending (default 0).",
+            "minimum": 0,
+            "maximum": 10000,
+            "default": 0
+          }
+        },
+        "required": [
+          "op",
+          "text"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "op": "key",
+      "description": "Tap a single key or hold it for a duration.",
+      "required": [
+        "key"
+      ],
+      "optional": [
+        "durationMs",
+        "count"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Tap a single key or hold it for a duration.",
+        "properties": {
+          "op": {
+            "const": "key"
+          },
+          "key": {
+            "type": "string",
+            "description": "Key to press: a printable character, or a PETSCII token name (RETURN, F1…F8, UP, etc.).",
+            "minLength": 1,
+            "maxLength": 32
+          },
+          "durationMs": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Delay in ms after each queued key press before the next press (default 0 = no delay).",
+            "minimum": 0,
+            "maximum": 5000,
+            "default": 0
+          },
+          "count": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Number of times to press the key (default 1).",
+            "minimum": 1,
+            "maximum": 100,
+            "default": 1
+          }
+        },
+        "required": [
+          "op",
+          "key"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "op": "joystick",
+      "description": "Simulate joystick input by writing directly to CIA1 Port A/B registers.",
+      "required": [
+        "port",
+        "controls",
+        "action"
+      ],
+      "optional": [
+        "durationMs"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Simulate joystick input by writing directly to CIA1 Port A/B registers.",
+        "properties": {
+          "op": {
+            "const": "joystick"
+          },
+          "port": {
+            "type": "integer",
+            "description": "Joystick port (1 = $DC01, 2 = $DC00).",
+            "minimum": 1,
+            "maximum": 2
+          },
+          "controls": {
+            "type": "array",
+            "description": "List of controls to activate simultaneously.",
+            "items": {
+              "type": "string",
+              "description": "Control to activate.",
+              "enum": [
+                "up",
+                "down",
+                "left",
+                "right",
+                "fire"
+              ]
+            },
+            "minItems": 0
+          },
+          "action": {
+            "type": "string",
+            "description": "press = hold until a release call; release = restore all bits; tap = press then release after durationMs.",
+            "enum": [
+              "press",
+              "release",
+              "tap"
+            ]
+          },
+          "durationMs": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Duration to hold for tap action in ms (default 80).",
+            "minimum": 10,
+            "maximum": 5000,
+            "default": 80
+          }
+        },
+        "required": [
+          "op",
+          "port",
+          "controls",
+          "action"
+        ],
+        "additionalProperties": false
+      }
+    }
+  ]
+}