VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:562-604 (registration)

  MCP tool registration for 'setBreakpoint', including 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:581-603 (handler)

  Handler function for the 'setBreakpoint' MCP tool that validates input, 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:575-579 (schema)

  Zod input schema defining parameters for setBreakpoint: address (required 0-65535), 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:543-584 (helper)

  ViceClient.setBreakpoint method: validates address, builds VICE binary monitor protocol packet for CheckpointSet (execution breakpoint), sends command, parses ID, 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; }