VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:1081-1160 (handler)

  The core handler function for the readScreen tool. Determines current VIC-II bank and screen memory address by reading CIA2 ($DD00) and VIC $D018 registers. Reads 1000 bytes of screen RAM. Converts PETSCII screen codes to readable ASCII text using screenToText helper. Handles full/summary formats, includes raw data option, detects graphics mode, and adds contextual hints.

  async (args) => {
    try {
      // First get VIC bank from CIA2
      const cia2Data = await client.readMemory(0xdd00, 0xdd00);
      const bankInfo = getVicBank(cia2Data[0]);
  
      // Get screen address from $D018
      const d018Data = await client.readMemory(0xd018, 0xd018);
      const videoAddrs = getVideoAddresses(d018Data[0], bankInfo.baseAddress);
  
      // Read screen RAM (1000 bytes)
      const screenData = await client.readMemory(
        videoAddrs.screenAddress,
        videoAddrs.screenAddress + 999
      );
  
      // Convert to text
      const textLines = screenToText(screenData);
  
      // Find non-empty lines for summary
      const nonEmptyLines = textLines
        .map((line, idx) => ({ line: idx, content: line }))
        .filter((l) => l.content.trim().length > 0);
  
      const useSummaryFormat = args.format === "summary";
  
      const response: Record<string, unknown> = {
        screenAddress: {
          value: videoAddrs.screenAddress,
          hex: `$${videoAddrs.screenAddress.toString(16).padStart(4, "0")}`,
        },
        vicBank: bankInfo.bank,
        format: useSummaryFormat ? "summary" : "full",
      };
  
      if (useSummaryFormat) {
        // Summary format: only non-empty lines with line numbers
        response.lines = nonEmptyLines.map((l) => ({
          lineNumber: l.line,
          content: l.content,
        }));
        response.totalLines = 25;
        response.nonEmptyCount = nonEmptyLines.length;
      } else {
        // Full format: all 25 lines
        response.lines = textLines;
        response.summary = {
          nonEmptyLines: nonEmptyLines.length,
          preview:
            nonEmptyLines.length > 0
              ? nonEmptyLines.slice(0, 3).map((l) => `Line ${l.line}: "${l.content}"`)
              : ["Screen appears empty"],
        };
      }
  
      if (args.includeRaw) {
        response.raw = Array.from(screenData);
      }
  
      // Check graphics mode and add hint
      const d011Data = await client.readMemory(0xd011, 0xd011);
      const d016Data = await client.readMemory(0xd016, 0xd016);
      const graphicsMode = getGraphicsMode(d011Data[0], d016Data[0]);
  
      response.graphicsMode = graphicsMode.mode;
  
      if (graphicsMode.bitmap) {
        response.hint =
          "Warning: VIC-II is in bitmap mode - screen RAM contains bitmap data, not text.";
      } else if (nonEmptyLines.length === 0) {
        response.hint = "Screen appears empty or contains only spaces.";
      } else {
        response.hint = `Screen has ${nonEmptyLines.length} non-empty line(s). First: "${nonEmptyLines[0]?.content || ""}"`;
      }
  
      return formatResponse(response);
    } catch (error) {
      return formatError(error as ViceError);
    }
  }

• src/index.ts:1070-1079 (schema)

  Zod input schema defining parameters for readScreen: format (full/summary) and includeRaw (boolean).

  inputSchema: z.object({
    format: z
      .enum(["full", "summary"])
      .optional()
      .describe("Output format: 'full' (all 25 lines) or 'summary' (non-empty lines only)"),
    includeRaw: z
      .boolean()
      .optional()
      .describe("Include raw screen codes array (default: false)"),
  }),

• src/index.ts:1053-1161 (registration)

  MCP server tool registration for readScreen, including detailed description, input schema validation, and handler function reference.

  server.registerTool(
    "readScreen",
    {
      description: `Read the C64 screen memory and return it as interpreted text.
  
  Converts PETSCII screen codes to readable ASCII. Returns 25 lines of 40 characters.
  
  Use this instead of readMemory($0400) when you want to see what's displayed on screen.
  
  Note: This reads from the current screen RAM location (may not be $0400 if the program moved it).
  In bitmap modes, the data won't represent text.
  
  Options:
  - format: "full" (default) returns all 25 lines, "summary" returns only non-empty lines
  - includeRaw: Also return raw screen codes (default: false)
  
  Related tools: readColorRam, readVicState, readMemory`,
      inputSchema: z.object({
        format: z
          .enum(["full", "summary"])
          .optional()
          .describe("Output format: 'full' (all 25 lines) or 'summary' (non-empty lines only)"),
        includeRaw: z
          .boolean()
          .optional()
          .describe("Include raw screen codes array (default: false)"),
      }),
    },
    async (args) => {
      try {
        // First get VIC bank from CIA2
        const cia2Data = await client.readMemory(0xdd00, 0xdd00);
        const bankInfo = getVicBank(cia2Data[0]);
  
        // Get screen address from $D018
        const d018Data = await client.readMemory(0xd018, 0xd018);
        const videoAddrs = getVideoAddresses(d018Data[0], bankInfo.baseAddress);
  
        // Read screen RAM (1000 bytes)
        const screenData = await client.readMemory(
          videoAddrs.screenAddress,
          videoAddrs.screenAddress + 999
        );
  
        // Convert to text
        const textLines = screenToText(screenData);
  
        // Find non-empty lines for summary
        const nonEmptyLines = textLines
          .map((line, idx) => ({ line: idx, content: line }))
          .filter((l) => l.content.trim().length > 0);
  
        const useSummaryFormat = args.format === "summary";
  
        const response: Record<string, unknown> = {
          screenAddress: {
            value: videoAddrs.screenAddress,
            hex: `$${videoAddrs.screenAddress.toString(16).padStart(4, "0")}`,
          },
          vicBank: bankInfo.bank,
          format: useSummaryFormat ? "summary" : "full",
        };
  
        if (useSummaryFormat) {
          // Summary format: only non-empty lines with line numbers
          response.lines = nonEmptyLines.map((l) => ({
            lineNumber: l.line,
            content: l.content,
          }));
          response.totalLines = 25;
          response.nonEmptyCount = nonEmptyLines.length;
        } else {
          // Full format: all 25 lines
          response.lines = textLines;
          response.summary = {
            nonEmptyLines: nonEmptyLines.length,
            preview:
              nonEmptyLines.length > 0
                ? nonEmptyLines.slice(0, 3).map((l) => `Line ${l.line}: "${l.content}"`)
                : ["Screen appears empty"],
          };
        }
  
        if (args.includeRaw) {
          response.raw = Array.from(screenData);
        }
  
        // Check graphics mode and add hint
        const d011Data = await client.readMemory(0xd011, 0xd011);
        const d016Data = await client.readMemory(0xd016, 0xd016);
        const graphicsMode = getGraphicsMode(d011Data[0], d016Data[0]);
  
        response.graphicsMode = graphicsMode.mode;
  
        if (graphicsMode.bitmap) {
          response.hint =
            "Warning: VIC-II is in bitmap mode - screen RAM contains bitmap data, not text.";
        } else if (nonEmptyLines.length === 0) {
          response.hint = "Screen appears empty or contains only spaces.";
        } else {
          response.hint = `Screen has ${nonEmptyLines.length} non-empty line(s). First: "${nonEmptyLines[0]?.content || ""}"`;
        }
  
        return formatResponse(response);
      } catch (error) {
        return formatError(error as ViceError);
      }
    }
  );

• src/utils/c64.ts:75-92 (helper)

  Helper function that converts raw screen RAM buffer (1000 bytes) into 25 lines x 40 chars of ASCII text by mapping C64 screen codes to printable characters via screenCodeToAscii.

  export function screenToText(screenData: Buffer | number[]): string[] {
    const data = Buffer.isBuffer(screenData) ? screenData : Buffer.from(screenData);
    const lines: string[] = [];
  
    for (let row = 0; row < 25; row++) {
      const offset = row * 40;
      let line = "";
      for (let col = 0; col < 40; col++) {
        if (offset + col < data.length) {
          line += screenCodeToAscii(data[offset + col]);
        }
      }
      // Trim trailing spaces but keep the line
      lines.push(line.trimEnd());
    }
  
    return lines;
  }

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

  Calculates VIC-II memory bank (0-3) and base address ($0000, $4000, $8000, $C000) from CIA #2 port A register value ($DD00). Essential for locating screen RAM.

  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,
    };
  }