c64-debug-mcp 1.0.7 → 1.0.8

package/README.md

@@ -26,6 +26,25 @@ The MCP server accepts C64 addresses in multiple formats for natural interaction
 
 **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
@@ -34,6 +53,24 @@ The MCP server accepts C64 addresses in multiple formats for natural interaction
 - `$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:

package/dist/http.cjs

@@ -153,6 +153,15 @@ var import_zod3 = require("zod");
 var import_zod2 = require("zod");
 var warningSchema = warningItemSchema;
 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([
@@ -215,6 +224,15 @@ function parseAddress16(input) {
 }
 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([
@@ -3636,10 +3654,27 @@ var setRegistersTool = createViceTool({
 });
 var readMemoryTool = createViceTool({
   id: "memory_read",
-  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: 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")
+  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"]
@@ -3719,15 +3754,36 @@ var listBreakpointsTool = createViceTool({
 });
 var breakpointSetTool = createViceTool({
   id: "breakpoint_set",
-  description: "Creates an execution breakpoint or read/write watchpoint. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000).",
+  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: 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(),
     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,

package/dist/http.js

@@ -130,6 +130,15 @@ import { ZodError } from "zod";
 import { z as z2 } from "zod";
 var warningSchema = warningItemSchema;
 function parseAddress16(input) {
+  if (input === void 0) {
+    throw new z2.ZodError([
+      {
+        code: "custom",
+        message: "Address is required",
+        path: []
+      }
+    ]);
+  }
   if (typeof input === "number") {
     if (!Number.isInteger(input) || input < 0 || input > 65535) {
       throw new z2.ZodError([
@@ -192,6 +201,15 @@ function parseAddress16(input) {
 }
 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 (input === void 0) {
+    throw new z2.ZodError([
+      {
+        code: "custom",
+        message: "Byte value is required",
+        path: []
+      }
+    ]);
+  }
   if (typeof input === "number") {
     if (!Number.isInteger(input) || input < 0 || input > 255) {
       throw new z2.ZodError([
@@ -3613,10 +3631,27 @@ var setRegistersTool = createViceTool({
 });
 var readMemoryTool = createViceTool({
   id: "memory_read",
-  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: 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")
+  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: z3.union([
+    z3.object({
+      address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
+      length: z3.number().int().positive().max(65535).describe("Number of bytes to read")
+    }),
+    z3.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"]
@@ -3696,15 +3731,36 @@ var listBreakpointsTool = createViceTool({
 });
 var breakpointSetTool = createViceTool({
   id: "breakpoint_set",
-  description: "Creates an execution breakpoint or read/write watchpoint. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000).",
+  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: z3.object({
     kind: breakpointKindSchema,
-    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(),
     temporary: z3.boolean().default(false),
     enabled: z3.boolean().default(true)
+  }).and(
+    z3.union([
+      z3.object({
+        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")
+      }),
+      z3.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: z3.object({
     breakpoint: breakpointSchema,

package/dist/stdio.cjs

@@ -150,6 +150,15 @@ var import_zod3 = require("zod");
 var import_zod2 = require("zod");
 var warningSchema = warningItemSchema;
 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([
@@ -212,6 +221,15 @@ function parseAddress16(input) {
 }
 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([
@@ -3633,10 +3651,27 @@ var setRegistersTool = createViceTool({
 });
 var readMemoryTool = createViceTool({
   id: "memory_read",
-  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: 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")
+  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"]
@@ -3716,15 +3751,36 @@ var listBreakpointsTool = createViceTool({
 });
 var breakpointSetTool = createViceTool({
   id: "breakpoint_set",
-  description: "Creates an execution breakpoint or read/write watchpoint. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000).",
+  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: 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(),
     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,

package/dist/stdio.js

@@ -127,6 +127,15 @@ import { ZodError } from "zod";
 import { z as z2 } from "zod";
 var warningSchema = warningItemSchema;
 function parseAddress16(input) {
+  if (input === void 0) {
+    throw new z2.ZodError([
+      {
+        code: "custom",
+        message: "Address is required",
+        path: []
+      }
+    ]);
+  }
   if (typeof input === "number") {
     if (!Number.isInteger(input) || input < 0 || input > 65535) {
       throw new z2.ZodError([
@@ -189,6 +198,15 @@ function parseAddress16(input) {
 }
 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 (input === void 0) {
+    throw new z2.ZodError([
+      {
+        code: "custom",
+        message: "Byte value is required",
+        path: []
+      }
+    ]);
+  }
   if (typeof input === "number") {
     if (!Number.isInteger(input) || input < 0 || input > 255) {
       throw new z2.ZodError([
@@ -3610,10 +3628,27 @@ var setRegistersTool = createViceTool({
 });
 var readMemoryTool = createViceTool({
   id: "memory_read",
-  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: 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")
+  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: z3.union([
+    z3.object({
+      address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
+      length: z3.number().int().positive().max(65535).describe("Number of bytes to read")
+    }),
+    z3.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"]
@@ -3693,15 +3728,36 @@ var listBreakpointsTool = createViceTool({
 });
 var breakpointSetTool = createViceTool({
   id: "breakpoint_set",
-  description: "Creates an execution breakpoint or read/write watchpoint. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000).",
+  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: z3.object({
     kind: breakpointKindSchema,
-    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(),
     temporary: z3.boolean().default(false),
     enabled: z3.boolean().default(true)
+  }).and(
+    z3.union([
+      z3.object({
+        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")
+      }),
+      z3.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: z3.object({
     breakpoint: breakpointSchema,

package/package.json

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