c64-debug-mcp 1.0.6 → 1.0.7

package/README.md

@@ -14,6 +14,64 @@ 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.
+
+**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
+
+## 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 +82,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 +90,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,193 @@ 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 (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 (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 +2621,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,9 +3636,9 @@ 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.",
+  description: "Reads a memory chunk by start address and length. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000). Returns byte values as decimal numbers.",
   inputSchema: import_zod4.z.object({
-    address: address16Schema.describe("Start address in the 16-bit C64 address space"),
+    address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
     length: import_zod4.z.number().int().positive().max(65535).describe("Size of the data chunk to read in bytes")
   }).refine((input) => input.address + input.length <= 65536, {
     message: "address + length must stay within the 64K address space",
@@ -3464,10 +3660,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,10 +3719,10 @@ 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. Address 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"),
+    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"),
     condition: import_zod4.z.string().optional(),
     label: import_zod4.z.string().optional(),

package/dist/http.js

@@ -129,9 +129,193 @@ import { ZodError } from "zod";
 // src/schemas.ts
 import { z as z2 } from "zod";
 var warningSchema = warningItemSchema;
-var address16Schema = z2.number().int().min(0).max(65535);
-var byteValueSchema = z2.number().int().min(0).max(255).describe("Single raw byte value");
-var byteArraySchema = z2.array(byteValueSchema).describe("Raw bytes as a JSON array");
+function parseAddress16(input) {
+  if (typeof input === "number") {
+    if (!Number.isInteger(input) || input < 0 || input > 65535) {
+      throw new z2.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 z2.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 z2.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 z2.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 z2.ZodError([
+      {
+        code: "custom",
+        message: `Address out of range: "${input}" (${parsed}). Must be 0x0000-0xFFFF (0-65535)`,
+        path: []
+      }
+    ]);
+  }
+  return parsed;
+}
+var address16Schema = z2.preprocess(parseAddress16, z2.number().int().min(0).max(65535)).describe("16-bit C64 address: decimal (53248) or hex string with prefix ($D000, 0xD000)");
+function parseByte(input) {
+  if (typeof input === "number") {
+    if (!Number.isInteger(input) || input < 0 || input > 255) {
+      throw new z2.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 z2.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 z2.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 z2.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 z2.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 z2.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 z2.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 z2.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 z2.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 z2.ZodError([
+        {
+          code: "custom",
+          message: `Byte value out of range: "${input}" (${parsed}). Must be 0b00000000-0b11111111 (0-255)`,
+          path: []
+        }
+      ]);
+    }
+    return parsed;
+  }
+  throw new z2.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 = z2.preprocess(parseByte, z2.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 = z2.array(byteValueSchema).describe('Array of byte values in mixed formats: [255, "$FF", "%11111111", 42]');
 var c64RegisterValueSchema = z2.object(
   Object.fromEntries(
     C64_REGISTER_DEFINITIONS.map((register) => [
@@ -2414,9 +2598,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);
@@ -3417,9 +3613,9 @@ 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.",
+  description: "Reads a memory chunk by start address and length. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000). Returns byte values as decimal numbers.",
   inputSchema: z3.object({
-    address: address16Schema.describe("Start address in the 16-bit C64 address space"),
+    address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
     length: z3.number().int().positive().max(65535).describe("Size of the data chunk to read in bytes")
   }).refine((input) => input.address + input.length <= 65536, {
     message: "address + length must stay within the 64K address space",
@@ -3441,10 +3637,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: z3.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"]
@@ -3500,10 +3696,10 @@ 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. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000).",
   inputSchema: z3.object({
     kind: breakpointKindSchema,
-    address: address16Schema.describe("Start address of the breakpoint range"),
+    address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
     length: z3.number().int().positive().default(1).describe("Size of the breakpoint range in bytes"),
     condition: z3.string().optional(),
     label: z3.string().optional(),

package/dist/stdio.cjs

@@ -149,9 +149,193 @@ 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 (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 (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) => [
@@ -2434,9 +2618,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);
@@ -3437,9 +3633,9 @@ 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.",
+  description: "Reads a memory chunk by start address and length. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000). Returns byte values as decimal numbers.",
   inputSchema: import_zod4.z.object({
-    address: address16Schema.describe("Start address in the 16-bit C64 address space"),
+    address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
     length: import_zod4.z.number().int().positive().max(65535).describe("Size of the data chunk to read in bytes")
   }).refine((input) => input.address + input.length <= 65536, {
     message: "address + length must stay within the 64K address space",
@@ -3461,10 +3657,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"]
@@ -3520,10 +3716,10 @@ 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. Address 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"),
+    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"),
     condition: import_zod4.z.string().optional(),
     label: import_zod4.z.string().optional(),

package/dist/stdio.js

@@ -126,9 +126,193 @@ import { ZodError } from "zod";
 // src/schemas.ts
 import { z as z2 } from "zod";
 var warningSchema = warningItemSchema;
-var address16Schema = z2.number().int().min(0).max(65535);
-var byteValueSchema = z2.number().int().min(0).max(255).describe("Single raw byte value");
-var byteArraySchema = z2.array(byteValueSchema).describe("Raw bytes as a JSON array");
+function parseAddress16(input) {
+  if (typeof input === "number") {
+    if (!Number.isInteger(input) || input < 0 || input > 65535) {
+      throw new z2.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 z2.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 z2.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 z2.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 z2.ZodError([
+      {
+        code: "custom",
+        message: `Address out of range: "${input}" (${parsed}). Must be 0x0000-0xFFFF (0-65535)`,
+        path: []
+      }
+    ]);
+  }
+  return parsed;
+}
+var address16Schema = z2.preprocess(parseAddress16, z2.number().int().min(0).max(65535)).describe("16-bit C64 address: decimal (53248) or hex string with prefix ($D000, 0xD000)");
+function parseByte(input) {
+  if (typeof input === "number") {
+    if (!Number.isInteger(input) || input < 0 || input > 255) {
+      throw new z2.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 z2.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 z2.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 z2.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 z2.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 z2.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 z2.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 z2.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 z2.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 z2.ZodError([
+        {
+          code: "custom",
+          message: `Byte value out of range: "${input}" (${parsed}). Must be 0b00000000-0b11111111 (0-255)`,
+          path: []
+        }
+      ]);
+    }
+    return parsed;
+  }
+  throw new z2.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 = z2.preprocess(parseByte, z2.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 = z2.array(byteValueSchema).describe('Array of byte values in mixed formats: [255, "$FF", "%11111111", 42]');
 var c64RegisterValueSchema = z2.object(
   Object.fromEntries(
     C64_REGISTER_DEFINITIONS.map((register) => [
@@ -2411,9 +2595,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);
@@ -3414,9 +3610,9 @@ 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.",
+  description: "Reads a memory chunk by start address and length. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000). Returns byte values as decimal numbers.",
   inputSchema: z3.object({
-    address: address16Schema.describe("Start address in the 16-bit C64 address space"),
+    address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
     length: z3.number().int().positive().max(65535).describe("Size of the data chunk to read in bytes")
   }).refine((input) => input.address + input.length <= 65536, {
     message: "address + length must stay within the 64K address space",
@@ -3438,10 +3634,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: z3.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"]
@@ -3497,10 +3693,10 @@ 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. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000).",
   inputSchema: z3.object({
     kind: breakpointKindSchema,
-    address: address16Schema.describe("Start address of the breakpoint range"),
+    address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
     length: z3.number().int().positive().default(1).describe("Size of the breakpoint range in bytes"),
     condition: z3.string().optional(),
     label: z3.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c64-debug-mcp",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Model Context Protocol server for C64 debugging via VICE emulator",
   "type": "module",
   "keywords": [