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;
  }