VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:1530-1583 (registration)

  Registration of the 'screenshot' MCP tool including description, input schema, and handler function.

  server.registerTool(
    "screenshot",
    {
      description: `Capture the current VICE display as image data.
  
  Returns the raw display buffer with:
  - Pixel data (indexed 8-bit palette colors)
  - Display dimensions and visible area
  - Current palette RGB values
  
  The data can be used to understand what's currently on screen visually.
  For text mode screens, readScreen provides a simpler text representation.
  
  Options:
  - includePalette: Also return the color palette (default: true)
  
  Related tools: readScreen, readVicState`,
      inputSchema: z.object({
        includePalette: z.boolean().optional().describe("Include palette RGB values (default: true)"),
      }),
    },
    async (args) => {
      try {
        const display = await client.getDisplay();
  
        const response: Record<string, unknown> = {
          width: display.width,
          height: display.height,
          bitsPerPixel: display.bitsPerPixel,
          visibleArea: {
            offsetX: display.offsetX,
            offsetY: display.offsetY,
            innerWidth: display.innerWidth,
            innerHeight: display.innerHeight,
          },
          pixelCount: display.pixels.length,
          // Return pixels as base64 for efficient transfer
          pixelsBase64: display.pixels.toString("base64"),
        };
  
        if (args.includePalette !== false) {
          const palette = await client.getPalette();
          response.palette = palette;
          response.paletteCount = palette.length;
        }
  
        response.hint = `Display is ${display.width}x${display.height} (visible: ${display.innerWidth}x${display.innerHeight}). Use readScreen() for text mode content.`;
  
        return formatResponse(response);
      } catch (error) {
        return formatError(error as ViceError);
      }
    }
  );

• src/index.ts:1551-1582 (handler)

  The main handler for the 'screenshot' tool. Captures display data via ViceClient.getDisplay(), optionally fetches palette, encodes pixels to base64, and returns formatted response.

  async (args) => {
    try {
      const display = await client.getDisplay();
  
      const response: Record<string, unknown> = {
        width: display.width,
        height: display.height,
        bitsPerPixel: display.bitsPerPixel,
        visibleArea: {
          offsetX: display.offsetX,
          offsetY: display.offsetY,
          innerWidth: display.innerWidth,
          innerHeight: display.innerHeight,
        },
        pixelCount: display.pixels.length,
        // Return pixels as base64 for efficient transfer
        pixelsBase64: display.pixels.toString("base64"),
      };
  
      if (args.includePalette !== false) {
        const palette = await client.getPalette();
        response.palette = palette;
        response.paletteCount = palette.length;
      }
  
      response.hint = `Display is ${display.width}x${display.height} (visible: ${display.innerWidth}x${display.innerHeight}). Use readScreen() for text mode content.`;
  
      return formatResponse(response);
    } catch (error) {
      return formatError(error as ViceError);
    }
  }

• src/index.ts:1547-1549 (schema)

  Input schema for the 'screenshot' tool using Zod, defining optional 'includePalette' boolean parameter.

  inputSchema: z.object({
    includePalette: z.boolean().optional().describe("Include palette RGB values (default: true)"),
  }),

• src/protocol/client.ts:723-769 (helper)

  ViceClient.getDisplay() method: sends DisplayGet command to VICE binary monitor, parses response to extract display buffer (screenshot pixels), dimensions, and metadata.

  async getDisplay(useVicii = true): Promise<{
    width: number;
    height: number;
    bitsPerPixel: number;
    offsetX: number;
    offsetY: number;
    innerWidth: number;
    innerHeight: number;
    pixels: Buffer;
  }> {
    // Ensure VICE is stopped before display capture
    await this.ensureStopped();
  
    // Body: useVicii(1) + format(1)
    // Format: 0 = indexed 8-bit
    const body = Buffer.alloc(2);
    body[0] = useVicii ? 1 : 0;
    body[1] = 0; // 8-bit indexed
  
    // Response type is 0x84 (same as command)
    const response = await this.sendCommand(Command.DisplayGet, body, ResponseType.DisplayGet);
  
    // Parse response per VICE docs:
    // FL(4) + DW(2) + DH(2) + XO(2) + YO(2) + IW(2) + IH(2) + BP(1) + BL(4) + BD(BL)
    // FL = length of fields before display buffer (should be 17)
    // const fieldsLength = response.body.readUInt32LE(0); // Not used but documented
    const width = response.body.readUInt16LE(4);          // DW - debug width
    const height = response.body.readUInt16LE(6);         // DH - debug height
    const offsetX = response.body.readUInt16LE(8);        // XO - x offset
    const offsetY = response.body.readUInt16LE(10);       // YO - y offset
    const innerWidth = response.body.readUInt16LE(12);    // IW - inner width
    const innerHeight = response.body.readUInt16LE(14);   // IH - inner height
    const bitsPerPixel = response.body[16];               // BP - bits per pixel
    const bufferLength = response.body.readUInt32LE(17);  // BL - buffer length
    const pixels = response.body.subarray(21, 21 + bufferLength); // BD - display buffer
  
    return {
      width,
      height,
      bitsPerPixel,
      offsetX,
      offsetY,
      innerWidth,
      innerHeight,
      pixels,
    };
  }