VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:1011-1046 (registration)

  MCP tool registration for 'loadProgram', including Zod input schema, description, and handler function that delegates to ViceClient.autostart and formats the response.
  server.registerTool( "loadProgram", { description: `Load and optionally run a program file. Supports PRG, D64, T64, and other C64 file formats. For disk images, can specify which file to run. Options: - run: If true (default), starts execution after loading - fileIndex: For disk images, which file to load (0 = first) Related tools: reset, status, setBreakpoint`, inputSchema: z.object({ filename: z.string().describe("Path to the program file (PRG, D64, T64, etc.)"), run: z.boolean().optional().describe("Run after loading (default: true)"), fileIndex: z.number().optional().describe("File index in disk image (default: 0)"), }), }, async (args) => { try { await client.autostart(args.filename, args.fileIndex ?? 0, args.run ?? true); return formatResponse({ success: true, filename: args.filename, run: args.run ?? true, message: `Loading ${args.filename}${args.run !== false ? " and running" : ""}`, hint: args.run !== false ? "Program is loading. Set breakpoints before it reaches your code of interest." : "Program loaded but not started. Use continue() to run.", }); } catch (error) { return formatError(error as ViceError); } } );
• src/protocol/client.ts:711-720 (handler)

  Core implementation of program loading via VICE Binary Monitor Protocol's AutoStart command. Constructs the protocol body (run flag, file index, filename) and sends it to VICE.
  async autostart(filename: string, fileIndex = 0, runAfterLoad = true): Promise<void> { const filenameBuffer = Buffer.from(filename, "utf8"); // Body: run(1) + index(2) + filename_length(1) + filename const body = Buffer.alloc(4 + filenameBuffer.length); body[0] = runAfterLoad ? 1 : 0; body.writeUInt16LE(fileIndex, 1); body[3] = filenameBuffer.length; filenameBuffer.copy(body, 4); await this.sendCommand(Command.AutoStart, body); }
• src/index.ts:1025-1028 (schema)

  Zod input schema defining parameters for the loadProgram tool: filename (required), run (optional boolean), fileIndex (optional number).
  filename: z.string().describe("Path to the program file (PRG, D64, T64, etc.)"), run: z.boolean().optional().describe("Run after loading (default: true)"), fileIndex: z.number().optional().describe("File index in disk image (default: 0)"), }),
• src/protocol/client.ts:796-802 (helper)

  Factory function providing the singleton ViceClient instance used by the loadProgram handler.
  export function getViceClient(): ViceClient { if (!clientInstance) { clientInstance = new ViceClient(); } return clientInstance; }