VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:1498-1551 (registration)

  Registration of the MCP 'screenshot' tool, including description, Zod input schema, and inline handler function that captures display buffer and palette from VICE client.
  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:1519-1550 (handler)

  Handler function for 'screenshot' tool: fetches display buffer and optional palette using ViceClient, encodes pixels to base64, adds metadata, 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:1500-1517 (schema)

  Schema definition for 'screenshot' tool input: optional boolean for including palette.
  { 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)"), }),
• src/protocol/client.ts:681-723 (helper)

  ViceClient.getDisplay(): Sends DisplayGet command to VICE binary monitor, receives and parses screenshot pixel buffer with dimensions and viewport info.
  // Get display buffer (screenshot data) async getDisplay(useVicii = true): Promise<{ width: number; height: number; bitsPerPixel: number; offsetX: number; offsetY: number; innerWidth: number; innerHeight: number; pixels: Buffer; }> { // 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 const response = await this.sendCommand(Command.DisplayGet, body); // Parse response // Response: length(4) + width(4) + height(4) + bpp(1) + offsetX(4) + offsetY(4) + // innerWidth(4) + innerHeight(4) + pixels... const dataLength = response.body.readUInt32LE(0); const width = response.body.readUInt32LE(4); const height = response.body.readUInt32LE(8); const bitsPerPixel = response.body[12]; const offsetX = response.body.readUInt32LE(13); const offsetY = response.body.readUInt32LE(17); const innerWidth = response.body.readUInt32LE(21); const innerHeight = response.body.readUInt32LE(25); const pixels = response.body.subarray(29, 29 + dataLength); return { width, height, bitsPerPixel, offsetX, offsetY, innerWidth, innerHeight, pixels, }; }
• src/protocol/client.ts:725-744 (helper)

  ViceClient.getPalette(): Retrieves the current VIC-II color palette RGB values used for screenshot rendering.
  // Get palette (color table) async getPalette(): Promise<Array<{ r: number; g: number; b: number }>> { const response = await this.sendCommand(Command.PaletteGet); // Parse response // Response: count(2) + [r(1) + g(1) + b(1)]... const count = response.body.readUInt16LE(0); const colors: Array<{ r: number; g: number; b: number }> = []; for (let i = 0; i < count; i++) { const offset = 2 + i * 3; colors.push({ r: response.body[offset], g: response.body[offset + 1], b: response.body[offset + 2], }); } return colors; }