VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:944-978 (registration)

  MCP server registration of the 'saveSnapshot' tool, including full description, Zod input schema requiring a filename string, and the handler function.

  server.registerTool(
    "saveSnapshot",
    {
      description: `Save the complete machine state to a file.
  
  Creates a VICE snapshot file containing:
  - All memory (RAM, I/O states)
  - CPU registers
  - VIC-II, SID, CIA states
  - Disk drive state (if attached)
  
  Use to:
  - Save state before risky debugging
  - Create restore points
  - Share exact machine state
  
  Related tools: loadSnapshot`,
      inputSchema: z.object({
        filename: z.string().describe("Filename for the snapshot (e.g., 'debug-state.vsf')"),
      }),
    },
    async (args) => {
      try {
        await client.saveSnapshot(args.filename);
        return formatResponse({
          success: true,
          filename: args.filename,
          message: `Snapshot saved to ${args.filename}`,
          hint: "Use loadSnapshot() to restore this state later",
        });
      } catch (error) {
        return formatError(error as ViceError);
      }
    }
  );

• src/index.ts:965-977 (handler)

  The handler function for the saveSnapshot MCP tool. It takes the filename argument, calls the underlying ViceClient.saveSnapshot method, formats success/error responses with metadata.

  async (args) => {
    try {
      await client.saveSnapshot(args.filename);
      return formatResponse({
        success: true,
        filename: args.filename,
        message: `Snapshot saved to ${args.filename}`,
        hint: "Use loadSnapshot() to restore this state later",
      });
    } catch (error) {
      return formatError(error as ViceError);
    }
  }

• src/index.ts:961-963 (schema)

  Zod input schema validation for the saveSnapshot tool, requiring a single 'filename' string parameter.

  inputSchema: z.object({
    filename: z.string().describe("Filename for the snapshot (e.g., 'debug-state.vsf')"),
  }),

• src/protocol/client.ts:694-700 (helper)

  ViceClient helper method that implements the snapshot save by encoding the filename length-prefixed buffer and sending the VICE 'Dump' command over the protocol.

  async saveSnapshot(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.Dump, body);
  }