VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:1240-1371 (handler)

  The core handler function for the 'readVicState' tool. Registers the tool with MCP server and implements the logic: reads VIC-II registers, computes bank/video addresses, graphics mode, sprite visibility, formats colors, and returns structured state with hints.

  server.registerTool(
    "readVicState",
    {
      description: `Read the full VIC-II state with interpreted values.
  
  Returns all VIC-II registers with semantic meaning:
  - Border and background colors (with names)
  - Graphics mode (text, bitmap, multicolor, etc.)
  - Screen and character memory locations
  - Scroll values
  - Raster position
  - Sprite enable bits
  
  This is the high-level view of the video chip. Use for understanding display configuration.
  
  Related tools: readScreen, readSprites, readMemory (for $D000-$D02E)`,
    },
    async () => {
      try {
        // Read all VIC registers $D000-$D02E (47 bytes)
        const vicData = await client.readMemory(0xd000, 0xd02e);
  
        // Read CIA2 for bank info
        const cia2Data = await client.readMemory(0xdd00, 0xdd00);
        const bankInfo = getVicBank(cia2Data[0]);
  
        const d011 = vicData[0x11];
        const d016 = vicData[0x16];
        const d018 = vicData[0x18];
  
        const graphicsMode = getGraphicsMode(d011, d016);
        const videoAddrs = getVideoAddresses(d018, bankInfo.baseAddress);
  
        // Raster position (9-bit)
        const rasterLine = vicData[0x12] | ((d011 & 0x80) << 1);
  
        // Sprite enable and visibility check
        const spriteEnable = vicData[0x15];
        const spriteXMsb = vicData[0x10];
        const enabledSprites: number[] = [];
        const visibleSprites: number[] = [];
  
        for (let i = 0; i < 8; i++) {
          if (spriteEnable & (1 << i)) {
            enabledSprites.push(i);
            // Check visibility
            const xLow = vicData[i * 2];
            const xHigh = (spriteXMsb & (1 << i)) ? 256 : 0;
            const x = xLow + xHigh;
            const y = vicData[i * 2 + 1];
            const visibility = isSpriteVisible(x, y, true);
            if (visibility.visible) {
              visibleSprites.push(i);
            }
          }
        }
  
        // Display enable
        const displayEnabled = !!(d011 & 0x10);
  
        const response = {
          // Colors
          borderColor: getColorInfo(vicData[0x20]),
          backgroundColor: [
            getColorInfo(vicData[0x21]),
            getColorInfo(vicData[0x22]),
            getColorInfo(vicData[0x23]),
            getColorInfo(vicData[0x24]),
          ],
  
          // Graphics mode
          graphicsMode: graphicsMode.mode,
          displayEnabled,
          bitmap: graphicsMode.bitmap,
          multicolor: graphicsMode.multicolor,
          extendedColor: graphicsMode.extendedColor,
  
          // Screen geometry
          rows: d011 & 0x08 ? 25 : 24,
          columns: d016 & 0x08 ? 40 : 38,
          scrollX: d016 & 0x07,
          scrollY: d011 & 0x07,
  
          // Memory setup
          vicBank: {
            bank: bankInfo.bank,
            baseAddress: {
              value: bankInfo.baseAddress,
              hex: `$${bankInfo.baseAddress.toString(16).padStart(4, "0")}`,
            },
          },
          screenAddress: {
            value: videoAddrs.screenAddress,
            hex: `$${videoAddrs.screenAddress.toString(16).padStart(4, "0")}`,
          },
          charAddress: {
            value: videoAddrs.charAddress,
            hex: `$${videoAddrs.charAddress.toString(16).padStart(4, "0")}`,
          },
  
          // Raster
          rasterLine,
  
          // Sprites summary
          spriteEnable: {
            value: spriteEnable,
            binary: spriteEnable.toString(2).padStart(8, "0"),
            enabledSprites,
            enabledCount: enabledSprites.length,
            visibleSprites,
            visibleCount: visibleSprites.length,
          },
  
          // Sprite multicolor registers
          spriteMulticolor0: getColorInfo(vicData[0x25]),
          spriteMulticolor1: getColorInfo(vicData[0x26]),
  
          hint: !displayEnabled
            ? "Display is blanked (DEN=0) - screen shows border color only"
            : enabledSprites.length > 0
            ? visibleSprites.length < enabledSprites.length
              ? `${graphicsMode.mode} mode, ${enabledSprites.length} sprite(s) enabled but only ${visibleSprites.length} visible. Use readSprites() for details.`
              : `${graphicsMode.mode} mode, ${enabledSprites.length} sprite(s) enabled and visible.`
            : `${graphicsMode.mode} mode, no sprites enabled.`,
        };
  
        return formatResponse(response);
      } catch (error) {
        return formatError(error as ViceError);
      }
    }
  );

• src/utils/c64.ts:119-142 (helper)

  Key helper used by readVicState to parse VIC-II graphics mode from D011 and D016 registers.

  export function getGraphicsMode(d011: number, d016: number): {
    mode: string;
    bitmap: boolean;
    multicolor: boolean;
    extendedColor: boolean;
  } {
    const ecm = !!(d011 & 0x40);
    const bmm = !!(d011 & 0x20);
    const mcm = !!(d016 & 0x10);
  
    let mode = "standard text";
    if (ecm && !bmm && !mcm) mode = "extended background color";
    else if (!ecm && !bmm && mcm) mode = "multicolor text";
    else if (!ecm && bmm && !mcm) mode = "standard bitmap";
    else if (!ecm && bmm && mcm) mode = "multicolor bitmap";
    else if (ecm) mode = "invalid (ECM + other modes)";
  
    return {
      mode,
      bitmap: bmm,
      multicolor: mcm,
      extendedColor: ecm,
    };
  }

• src/utils/c64.ts:95-102 (helper)

  Helper to compute VIC-II memory bank from CIA2 $DD00 port A value, used in readVicState.

  export function getVicBank(cia2PortA: number): { bank: number; baseAddress: number } {
    // CIA2 port A bits 0-1 (inverted) select the bank
    const bankBits = (~cia2PortA) & 0x03;
    return {
      bank: bankBits,
      baseAddress: bankBits * 0x4000,
    };
  }