VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:995-1008 (handler)

  MCP tool handler for 'loadSnapshot' that extracts filename argument, calls ViceClient.loadSnapshot, and formats success/error response with metadata.

    async (args) => {
      try {
        await client.loadSnapshot(args.filename);
        return formatResponse({
          success: true,
          filename: args.filename,
          message: `Snapshot loaded from ${args.filename}`,
          hint: "Machine state restored. Use getRegisters() to verify state.",
        });
      } catch (error) {
        return formatError(error as ViceError);
      }
    }
  );

• src/index.ts:983-994 (schema)

  Input schema and description for the 'loadSnapshot' tool, requiring a 'filename' string parameter.

    {
      description: `Load a previously saved machine state from a file.
  
  Restores complete machine state including memory, registers, and peripheral states.
  
  Warning: This completely replaces the current state!
  
  Related tools: saveSnapshot`,
      inputSchema: z.object({
        filename: z.string().describe("Filename of the snapshot to load"),
      }),
    },

• src/index.ts:981-1008 (registration)

  Registration of the 'loadSnapshot' MCP tool using McpServer.registerTool, including schema, description, and handler.

  server.registerTool(
    "loadSnapshot",
    {
      description: `Load a previously saved machine state from a file.
  
  Restores complete machine state including memory, registers, and peripheral states.
  
  Warning: This completely replaces the current state!
  
  Related tools: saveSnapshot`,
      inputSchema: z.object({
        filename: z.string().describe("Filename of the snapshot to load"),
      }),
    },
    async (args) => {
      try {
        await client.loadSnapshot(args.filename);
        return formatResponse({
          success: true,
          filename: args.filename,
          message: `Snapshot loaded from ${args.filename}`,
          hint: "Machine state restored. Use getRegisters() to verify state.",
        });
      } catch (error) {
        return formatError(error as ViceError);
      }
    }
  );

• src/protocol/client.ts:702-708 (helper)

  ViceClient.loadSnapshot helper method that encodes the filename and sends the VICE 'Undump' binary monitor command to load the snapshot.

  async loadSnapshot(filename: string): Promise<void> {
    const filenameBuffer = Buffer.from(filename, "utf8");
    const body = Buffer.alloc(1 + filenameBuffer.length);
    body[0] = filenameBuffer.length;
    filenameBuffer.copy(body, 1);
    await this.sendCommand(Command.Undump, body);
  }