VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:492-527 (handler)

  MCP tool handler for 'step': executes client.step(), fetches updated registers to extract and report new PC
  async (args) => { try { await client.step(args.count || 1, args.stepOver || false); // Get registers after step const regResponse = await client.getRegisters(); const count = regResponse.body.readUInt16LE(0); let offset = 2; let pc = 0; for (let i = 0; i < count && offset < regResponse.body.length; i++) { const id = regResponse.body[offset]; const size = regResponse.body[offset + 1]; offset += 2; if (id === 3 && size === 2) { // PC pc = regResponse.body.readUInt16LE(offset); } offset += size; } return formatResponse({ stepped: true, count: args.count || 1, stepOver: args.stepOver || false, pc: { value: pc, hex: `$${pc.toString(16).padStart(4, "0")}`, }, message: `Stepped ${args.count || 1} instruction(s)`, hint: "Use getRegisters() for full CPU state, or readMemory at PC for next instruction", }); } catch (error) { return formatError(error as ViceError); } }
• src/index.ts:487-490 (schema)

  Zod input schema defining parameters: count (optional number >=1, default 1), stepOver (optional boolean, default false)
  inputSchema: z.object({ count: z.number().min(1).optional().describe("Number of instructions to step (default: 1)"), stepOver: z.boolean().optional().describe("Step over JSR calls instead of into them (default: false)"), }),
• src/index.ts:473-528 (registration)

  Registers the 'step' MCP tool with server.registerTool including full description, input schema, and handler reference
  server.registerTool( "step", { description: `Execute one or more instructions, then stop. Single-stepping is essential for understanding code flow and debugging. Options: - count: Number of instructions to execute (default: 1) - stepOver: If true, treat JSR as single instruction (don't step into subroutines) After stepping, use getRegisters to see the new CPU state. Related tools: getRegisters, continue, setBreakpoint, status`, inputSchema: z.object({ count: z.number().min(1).optional().describe("Number of instructions to step (default: 1)"), stepOver: z.boolean().optional().describe("Step over JSR calls instead of into them (default: false)"), }), }, async (args) => { try { await client.step(args.count || 1, args.stepOver || false); // Get registers after step const regResponse = await client.getRegisters(); const count = regResponse.body.readUInt16LE(0); let offset = 2; let pc = 0; for (let i = 0; i < count && offset < regResponse.body.length; i++) { const id = regResponse.body[offset]; const size = regResponse.body[offset + 1]; offset += 2; if (id === 3 && size === 2) { // PC pc = regResponse.body.readUInt16LE(offset); } offset += size; } return formatResponse({ stepped: true, count: args.count || 1, stepOver: args.stepOver || false, pc: { value: pc, hex: `$${pc.toString(16).padStart(4, "0")}`, }, message: `Stepped ${args.count || 1} instruction(s)`, hint: "Use getRegisters() for full CPU state, or readMemory at PC for next instruction", }); } catch (error) { return formatError(error as ViceError); } } );
• src/protocol/client.ts:518-526 (handler)

  ViceClient.step(): core implementation sending VICE binary monitor AdvanceInstructions (0x71) command with stepOver flag and count
  async step(count = 1, stepOver = false): Promise<ViceResponse> { // Uses AdvanceInstructions (0x71) - there is no separate Step command in VICE const body = Buffer.alloc(3); body[0] = stepOver ? 1 : 0; body.writeUInt16LE(count, 1); const response = await this.sendCommand(Command.AdvanceInstructions, body); this.state.running = false; return response; }
• src/protocol/client.ts:528-535 (helper)

  advanceInstructions(): alias for step() method in ViceClient for backward compatibility
  async advanceInstructions(count: number, stepOver = false): Promise<ViceResponse> { // Alias for step() - kept for API compatibility const body = Buffer.alloc(3); body[0] = stepOver ? 1 : 0; body.writeUInt16LE(count, 1); const response = await this.sendCommand(Command.AdvanceInstructions, body); return response; }