VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:550-592 (registration)

  MCP server.registerTool call that registers the 'setBreakpoint' tool, including its description, input schema, and handler function.
  server.registerTool( "setBreakpoint", { description: `Set an execution breakpoint at a memory address. When the PC reaches this address, execution stops. Use to: - Debug code at specific points - Catch when routines are called - Analyze code flow Returns a breakpoint ID for later management. Related tools: deleteBreakpoint, listBreakpoints, continue, step`, inputSchema: z.object({ address: z.number().min(0).max(0xffff).describe("Address to break at (0x0000-0xFFFF)"), enabled: z.boolean().optional().describe("Whether breakpoint is active (default: true)"), temporary: z.boolean().optional().describe("Auto-delete after hit (default: false)"), }), }, async (args) => { try { const id = await client.setBreakpoint(args.address, { enabled: args.enabled ?? true, temporary: args.temporary ?? false, }); return formatResponse({ success: true, breakpointId: id, address: { value: args.address, hex: `$${args.address.toString(16).padStart(4, "0")}`, }, enabled: args.enabled ?? true, temporary: args.temporary ?? false, message: `Breakpoint ${id} set at $${args.address.toString(16).padStart(4, "0")}`, hint: "Use continue() to run until breakpoint is hit", }); } catch (error) { return formatError(error as ViceError); } } );
• src/index.ts:569-591 (handler)

  The async handler function for the 'setBreakpoint' MCP tool. Validates args, calls ViceClient.setBreakpoint, formats success/error response with metadata.
  async (args) => { try { const id = await client.setBreakpoint(args.address, { enabled: args.enabled ?? true, temporary: args.temporary ?? false, }); return formatResponse({ success: true, breakpointId: id, address: { value: args.address, hex: `$${args.address.toString(16).padStart(4, "0")}`, }, enabled: args.enabled ?? true, temporary: args.temporary ?? false, message: `Breakpoint ${id} set at $${args.address.toString(16).padStart(4, "0")}`, hint: "Use continue() to run until breakpoint is hit", }); } catch (error) { return formatError(error as ViceError); } }
• src/index.ts:563-567 (schema)

  Zod inputSchema for 'setBreakpoint' tool defining required address (0-65535) and optional enabled/temporary booleans.
  inputSchema: z.object({ address: z.number().min(0).max(0xffff).describe("Address to break at (0x0000-0xFFFF)"), enabled: z.boolean().optional().describe("Whether breakpoint is active (default: true)"), temporary: z.boolean().optional().describe("Auto-delete after hit (default: false)"), }),
• src/protocol/client.ts:502-543 (helper)

  ViceClient.setBreakpoint method: the core implementation that sends CheckpointSet command to VICE binary monitor protocol, handles validation, builds request packet, parses response ID, and tracks locally.
  async setBreakpoint( address: number, options: { enabled?: boolean; stop?: boolean; temporary?: boolean; } = {} ): Promise<number> { const { enabled = true, stop = true, temporary = false } = options; if (address < 0 || address > 0xffff) { throw this.makeError( "INVALID_ADDRESS", `Address 0x${address.toString(16)} is outside C64 memory range`, "C64 addresses are 16-bit (0x0000-0xFFFF)" ); } // Build request: start(2) + end(2) + stop(1) + enabled(1) + op(1) + temp(1) const body = Buffer.alloc(8); body.writeUInt16LE(address, 0); body.writeUInt16LE(address, 2); body[4] = stop ? 1 : 0; body[5] = enabled ? 1 : 0; body[6] = CheckpointOp.Exec; body[7] = temporary ? 1 : 0; const response = await this.sendCommand(Command.CheckpointSet, body); const id = response.body.readUInt32LE(0); // Track locally this.checkpoints.set(id, { id, startAddress: address, endAddress: address, enabled, temporary, type: "exec", }); return id; }