c64-debug-mcp 1.0.6 → 1.0.8

package/README.md

@@ -14,6 +14,101 @@ Debug Commodore 64 programs through conversation - AI-powered control of the VIC
 - 📸 **Display Capture**: Capture screen state and text content
 - ⌨️ **Input Control**: Send keyboard and joystick input
 - 📝 **Program Loading**: Load PRG files and manage execution
+- 🔢 **Flexible Formats**: Use C64 notation ($D000, $FF, %11111111) or standard formats (0xD000, 255, 0b11111111)
+
+## Address Formats
+
+The MCP server accepts C64 addresses in multiple formats for natural interaction:
+
+- **C64 style**: `$D000` (dollar sign prefix - classic 6502 assembler notation)
+- **C style**: `0xD000` (0x prefix - standard programming hex notation)
+- **Decimal**: `53248` (traditional decimal format)
+
+**Note**: Bare hex without prefix (e.g., `D000`) is NOT supported to avoid ambiguity with 4-digit decimals.
+
+### Range Support
+
+Tools that read memory or set breakpoints support both **address+length** and **start+end** formats:
+
+**Address + Length format** (original):
+```javascript
+memory_read(address="$D000", length=256)      // Read 256 bytes starting at $D000
+breakpoint_set(kind="exec", address="$1000", length=1)  // Breakpoint at $1000
+```
+
+**Start + End format** (more intuitive for ranges):
+```javascript
+memory_read(start="$D000", end="$D0FF")       // Read from $D000 to $D0FF inclusive
+memory_read(start=198, end=199)                // Read addresses 198-199 (2 bytes)
+breakpoint_set(kind="exec", start="$1000", end="$1000")  // Breakpoint at $1000
+```
+
+Both formats work with all address representations (decimal, $, 0x).
+
+**Common C64 Addresses**:
+- `$D000` - SID chip registers (sound)
+- `$D020` - Border color register
+- `$D021` - Background color register
+- `$0400` - Default screen memory
+- `$0800` - Common program start
+- `$C000` - BASIC ROM start
+
+## Address Ranges
+
+For operations that work with memory ranges (like `memory_read` and `breakpoint_set`), you can specify ranges in two ways:
+
+**Option 1: Address + Length**
+```javascript
+memory_read(address="$0400", length=256)  // Read 256 bytes from $0400
+breakpoint_set(kind="exec", address="$1000", length=16)  // Break on $1000-$100F
+```
+
+**Option 2: Start + End (inclusive)**
+```javascript
+memory_read(start="$0400", end="$04FF")  // Read from $0400 to $04FF (256 bytes)
+breakpoint_set(kind="exec", start="$1000", end="$100F")  // Break on $1000-$100F
+```
+
+Both formats work identically and support all address formats (decimal, hex).
+
+## Byte Value Formats
+
+The MCP server accepts byte values (0-255) in multiple formats for natural C64-style input:
+
+- **C64 hex**: `$FF` (dollar sign prefix - classic 6502 notation)
+- **C hex**: `0xFF` (0x prefix - standard programming notation)
+- **C64 binary**: `%11111111` (percent prefix - classic 6502 bit notation)
+- **C binary**: `0b11111111` (0b prefix - standard programming notation)
+- **Decimal**: `255` (traditional decimal format)
+
+**Note**: Bare hex/binary without prefix (e.g., `FF`, `11111111`) is NOT supported to avoid ambiguity.
+
+**Mixed formats in arrays**:
+```json
+[255, "$FF", "0xFF", "%11111111", "0b11111111"]
+```
+
+**Common C64 Byte Values**:
+- `$00`-`$0F` - Color values (0-15)
+- `$20` - PETSCII space character
+- `$41` - PETSCII 'A' character
+- `%00011011` - VIC-II D011 control register (text mode, 25 rows, screen on)
+- `%11111111` - All bits set (enable all sprites, etc.)
+
+**Use Cases**:
+```javascript
+// Set border to light blue
+memory_write(address="$D020", data=["$0E"])
+
+// Enable all 8 sprites
+memory_write(address="$D015", data=["%11111111"])
+
+// Write " AB" to screen (PETSCII)
+memory_write(address="$0400", data=["$20", "$41", "$42"])
+
+// Set VIC-II control register with bit pattern
+memory_write(address="$D011", data=["%00011011"])
+```
 
 ## Requirements
 
@@ -24,7 +119,7 @@ Debug Commodore 64 programs through conversation - AI-powered control of the VIC
 ## Installation
 
 ```bash
-claude mcp add c64debug -- npx -y c64-debug-mcp
+claude mcp add c64-dev-tools -- npx -y c64-debug-mcp@latest
 ```
 
 Or add manually to your MCP client config:
@@ -32,9 +127,9 @@ Or add manually to your MCP client config:
 ```json
 {
   "mcpServers": {
-    "c64debug": {
+    "c64-dev-tools": {
       "command": "npx",
-      "args": ["-y", "c64-debug-mcp"]
+      "args": ["-y", "c64-debug-mcp@latest"]
     }
   }
 }

package/dist/http.cjs

@@ -152,9 +152,211 @@ var import_zod3 = require("zod");
 // src/schemas.ts
 var import_zod2 = require("zod");
 var warningSchema = warningItemSchema;
-var address16Schema = import_zod2.z.number().int().min(0).max(65535);
-var byteValueSchema = import_zod2.z.number().int().min(0).max(255).describe("Single raw byte value");
-var byteArraySchema = import_zod2.z.array(byteValueSchema).describe("Raw bytes as a JSON array");
+function parseAddress16(input) {
+  if (input === void 0) {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: "Address is required",
+        path: []
+      }
+    ]);
+  }
+  if (typeof input === "number") {
+    if (!Number.isInteger(input) || input < 0 || input > 65535) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Address must be an integer between 0 and 65535 (0xFFFF), got ${input}`,
+          path: []
+        }
+      ]);
+    }
+    return input;
+  }
+  if (typeof input !== "string") {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: `Address must be a number or string, got ${typeof input}`,
+        path: []
+      }
+    ]);
+  }
+  const trimmed = input.trim();
+  let hexString;
+  let format;
+  if (trimmed.startsWith("$")) {
+    hexString = trimmed.slice(1);
+    format = "C64 hex ($)";
+  } else if (trimmed.toLowerCase().startsWith("0x")) {
+    hexString = trimmed.slice(2);
+    format = "C hex (0x)";
+  } else {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: `Invalid address format: "${input}". Expected formats: decimal number (53248), hex with $ ($D000), or hex with 0x (0xD000). Bare hex not supported to avoid ambiguity.`,
+        path: []
+      }
+    ]);
+  }
+  if (!/^[0-9A-Fa-f]{1,4}$/.test(hexString)) {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: `Invalid ${format} address: "${input}". Hex portion must be 1-4 hex digits (0-9, A-F)`,
+        path: []
+      }
+    ]);
+  }
+  const parsed = parseInt(hexString, 16);
+  if (isNaN(parsed) || parsed < 0 || parsed > 65535) {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: `Address out of range: "${input}" (${parsed}). Must be 0x0000-0xFFFF (0-65535)`,
+        path: []
+      }
+    ]);
+  }
+  return parsed;
+}
+var address16Schema = import_zod2.z.preprocess(parseAddress16, import_zod2.z.number().int().min(0).max(65535)).describe("16-bit C64 address: decimal (53248) or hex string with prefix ($D000, 0xD000)");
+function parseByte(input) {
+  if (input === void 0) {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: "Byte value is required",
+        path: []
+      }
+    ]);
+  }
+  if (typeof input === "number") {
+    if (!Number.isInteger(input) || input < 0 || input > 255) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Byte value must be an integer between 0 and 255 (0xFF), got ${input}`,
+          path: []
+        }
+      ]);
+    }
+    return input;
+  }
+  if (typeof input !== "string") {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: `Byte value must be a number or string, got ${typeof input}`,
+        path: []
+      }
+    ]);
+  }
+  const trimmed = input.trim();
+  if (trimmed.startsWith("$")) {
+    const hexString = trimmed.slice(1);
+    if (!/^[0-9A-Fa-f]{1,2}$/.test(hexString)) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Invalid C64 hex ($) byte value: "${input}". Hex portion must be 1-2 hex digits (0-9, A-F)`,
+          path: []
+        }
+      ]);
+    }
+    const parsed = parseInt(hexString, 16);
+    if (isNaN(parsed) || parsed < 0 || parsed > 255) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Byte value out of range: "${input}" (${parsed}). Must be 0x00-0xFF (0-255)`,
+          path: []
+        }
+      ]);
+    }
+    return parsed;
+  }
+  if (trimmed.toLowerCase().startsWith("0x")) {
+    const hexString = trimmed.slice(2);
+    if (!/^[0-9A-Fa-f]{1,2}$/.test(hexString)) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Invalid C hex (0x) byte value: "${input}". Hex portion must be 1-2 hex digits (0-9, A-F)`,
+          path: []
+        }
+      ]);
+    }
+    const parsed = parseInt(hexString, 16);
+    if (isNaN(parsed) || parsed < 0 || parsed > 255) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Byte value out of range: "${input}" (${parsed}). Must be 0x00-0xFF (0-255)`,
+          path: []
+        }
+      ]);
+    }
+    return parsed;
+  }
+  if (trimmed.startsWith("%")) {
+    const binString = trimmed.slice(1);
+    if (!/^[01]{1,8}$/.test(binString)) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Invalid C64 binary (%) byte value: "${input}". Binary portion must be 1-8 binary digits (0-1)`,
+          path: []
+        }
+      ]);
+    }
+    const parsed = parseInt(binString, 2);
+    if (isNaN(parsed) || parsed < 0 || parsed > 255) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Byte value out of range: "${input}" (${parsed}). Must be 0b00000000-0b11111111 (0-255)`,
+          path: []
+        }
+      ]);
+    }
+    return parsed;
+  }
+  if (trimmed.toLowerCase().startsWith("0b")) {
+    const binString = trimmed.slice(2);
+    if (!/^[01]{1,8}$/.test(binString)) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Invalid C binary (0b) byte value: "${input}". Binary portion must be 1-8 binary digits (0-1)`,
+          path: []
+        }
+      ]);
+    }
+    const parsed = parseInt(binString, 2);
+    if (isNaN(parsed) || parsed < 0 || parsed > 255) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Byte value out of range: "${input}" (${parsed}). Must be 0b00000000-0b11111111 (0-255)`,
+          path: []
+        }
+      ]);
+    }
+    return parsed;
+  }
+  throw new import_zod2.z.ZodError([
+    {
+      code: "custom",
+      message: `Invalid byte format: "${input}". Expected formats: decimal (255), hex with prefix ($FF, 0xFF), or binary with prefix (%11111111, 0b11111111). Bare hex/binary not supported to avoid ambiguity.`,
+      path: []
+    }
+  ]);
+}
+var byteValueSchema = import_zod2.z.preprocess(parseByte, import_zod2.z.number().int().min(0).max(255)).describe("8-bit byte value: decimal (255), hex with prefix ($FF, 0xFF), or binary with prefix (%11111111, 0b11111111)");
+var byteArraySchema = import_zod2.z.array(byteValueSchema).describe('Array of byte values in mixed formats: [255, "$FF", "%11111111", 42]');
 var c64RegisterValueSchema = import_zod2.z.object(
   Object.fromEntries(
     C64_REGISTER_DEFINITIONS.map((register) => [
@@ -2437,9 +2639,21 @@ var ViceSession = class {
   async #withAutoResumeForInput(commandName, operation) {
     await this.#ensureReady();
     this.#syncMonitorRuntimeState();
+    if (this.#executionState === "unknown") {
+      throw new ViceMcpError(
+        "emulator_state_unknown",
+        `${commandName} requires a known execution state (running or stopped)`,
+        "session_state",
+        false,
+        {
+          executionState: this.#executionState,
+          lastStopReason: this.#lastStopReason
+        }
+      );
+    }
     const wasRunning = this.#executionState === "running";
     const wasPaused = this.#explicitPauseActive;
-    if (!wasRunning) {
+    if (this.#executionState === "stopped") {
       this.#writeProcessLogLine(`[${commandName}] auto-resuming for input operation`);
       await this.#client.continueExecution();
       await this.waitForState("running", 5e3, INPUT_RUNNING_STABLE_MS);
@@ -3440,10 +3654,27 @@ var setRegistersTool = createViceTool({
 });
 var readMemoryTool = createViceTool({
   id: "memory_read",
-  description: "Reads a memory chunk by start address and length and returns raw bytes as a JSON array.",
-  inputSchema: import_zod4.z.object({
-    address: address16Schema.describe("Start address in the 16-bit C64 address space"),
-    length: import_zod4.z.number().int().positive().max(65535).describe("Size of the data chunk to read in bytes")
+  description: "Reads a memory chunk. Use either (address, length) or (start, end) format. Addresses can be decimal (53248) or hex string with prefix ($D000, 0xD000). Returns byte values as decimal numbers.",
+  inputSchema: import_zod4.z.union([
+    import_zod4.z.object({
+      address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
+      length: import_zod4.z.number().int().positive().max(65535).describe("Number of bytes to read")
+    }),
+    import_zod4.z.object({
+      start: address16Schema.describe("Start address (inclusive): decimal (53248) or hex string with prefix ($D000, 0xD000)"),
+      end: address16Schema.describe("End address (inclusive): decimal (53248) or hex string with prefix ($D000, 0xD000)")
+    })
+  ]).transform((input) => {
+    if ("start" in input && "end" in input) {
+      if (input.end < input.start) {
+        throw new Error("End address must be greater than or equal to start address");
+      }
+      return {
+        address: input.start,
+        length: input.end - input.start + 1
+      };
+    }
+    return input;
   }).refine((input) => input.address + input.length <= 65536, {
     message: "address + length must stay within the 64K address space",
     path: ["length"]
@@ -3464,10 +3695,10 @@ var readMemoryTool = createViceTool({
 });
 var writeMemoryTool = createViceTool({
   id: "memory_write",
-  description: 'Writes raw byte values into the active C64 memory space. Requires emulator to be stopped - call execute(action="pause") first if running.',
+  description: "Writes raw byte values into C64 memory. Address and byte values support decimal, hex ($FF, 0xFF), and binary (%11111111, 0b11111111) formats. Requires emulator to be stopped.",
   inputSchema: import_zod4.z.object({
-    address: address16Schema.describe("Start address in the 16-bit C64 address space"),
-    data: byteArraySchema.min(1).describe("Raw bytes to write into memory")
+    address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
+    data: byteArraySchema.min(1).describe("Bytes to write: decimal (255), hex ($FF, 0xFF), or binary (%11111111, 0b11111111). Mixed formats allowed.")
   }).refine((input) => input.address + input.data.length - 1 <= 65535, {
     message: "address + data.length must stay within the 16-bit address space",
     path: ["data"]
@@ -3523,15 +3754,36 @@ var listBreakpointsTool = createViceTool({
 });
 var breakpointSetTool = createViceTool({
   id: "breakpoint_set",
-  description: "Creates an execution breakpoint or read/write watchpoint.",
+  description: "Creates an execution breakpoint or read/write watchpoint. Use either (address, length) or (start, end) format. Addresses can be decimal (53248) or hex string with prefix ($D000, 0xD000).",
   inputSchema: import_zod4.z.object({
     kind: breakpointKindSchema,
-    address: address16Schema.describe("Start address of the breakpoint range"),
-    length: import_zod4.z.number().int().positive().default(1).describe("Size of the breakpoint range in bytes"),
     condition: import_zod4.z.string().optional(),
     label: import_zod4.z.string().optional(),
     temporary: import_zod4.z.boolean().default(false),
     enabled: import_zod4.z.boolean().default(true)
+  }).and(
+    import_zod4.z.union([
+      import_zod4.z.object({
+        address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
+        length: import_zod4.z.number().int().positive().default(1).describe("Size of the breakpoint range in bytes")
+      }),
+      import_zod4.z.object({
+        start: address16Schema.describe("Start address (inclusive): decimal (53248) or hex string with prefix ($D000, 0xD000)"),
+        end: address16Schema.describe("End address (inclusive): decimal (53248) or hex string with prefix ($D000, 0xD000)")
+      })
+    ])
+  ).transform((input) => {
+    if ("start" in input && "end" in input) {
+      if (input.end < input.start) {
+        throw new Error("End address must be greater than or equal to start address");
+      }
+      return {
+        ...input,
+        address: input.start,
+        length: input.end - input.start + 1
+      };
+    }
+    return input;
   }),
   dataSchema: import_zod4.z.object({
     breakpoint: breakpointSchema,