VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:127-170 (registration)

  MCP tool registration for 'connect', including schema, description, and inline handler function that invokes ViceClient.connect(host, port) and formats response with connection state.

  server.registerTool(
    "connect",
    {
      description: `Connect to a running VICE emulator instance via the binary monitor protocol.
  
  VICE must be started with the binary monitor enabled:
    x64sc -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502
  
  Default connection: 127.0.0.1:6502
  
  Use this first before any debugging operations. Connection persists until disconnect() is called or VICE closes.
  
  Related tools: status, disconnect`,
      inputSchema: z.object({
        host: z
          .string()
          .optional()
          .describe("VICE host address (default: 127.0.0.1)"),
        port: z
          .number()
          .min(1)
          .max(65535)
          .optional()
          .describe("VICE binary monitor port (default: 6502)"),
      }),
    },
    async (args) => {
      const host = args.host || "127.0.0.1";
      const port = args.port || 6502;
  
      try {
        await client.connect(host, port);
        return formatResponse({
          connected: true,
          host,
          port,
          message: `Successfully connected to VICE at ${host}:${port}`,
          hint: "Connection established. You can now use readMemory, getRegisters, and other debugging tools.",
        });
      } catch (error) {
        return formatError(error as ViceError);
      }
    }
  );

• src/index.ts:153-169 (handler)

  The handler function for the 'connect' tool. Parses args for host/port, calls the underlying ViceClient.connect(), formats success/error response with _meta state.

  async (args) => {
    const host = args.host || "127.0.0.1";
    const port = args.port || 6502;
  
    try {
      await client.connect(host, port);
      return formatResponse({
        connected: true,
        host,
        port,
        message: `Successfully connected to VICE at ${host}:${port}`,
        hint: "Connection established. You can now use readMemory, getRegisters, and other debugging tools.",
      });
    } catch (error) {
      return formatError(error as ViceError);
    }
  }

• src/index.ts:140-151 (schema)

  Zod schema defining optional 'host' (string) and 'port' (number 1-65535) inputs for the connect tool.

  inputSchema: z.object({
    host: z
      .string()
      .optional()
      .describe("VICE host address (default: 127.0.0.1)"),
    port: z
      .number()
      .min(1)
      .max(65535)
      .optional()
      .describe("VICE binary monitor port (default: 6502)"),
  }),

• src/protocol/client.ts:78-142 (helper)

  ViceClient.connect() method: Establishes TCP socket connection to VICE binary monitor server on given host/port, sets up event handlers for data/error/close/connect, updates connection state, rejects pending requests on close.

  async connect(host = "127.0.0.1", port = 6502): Promise<void> {
    if (this.socket) {
      throw this.makeError(
        "ALREADY_CONNECTED",
        "Already connected to VICE",
        "Use disconnect() first if you want to reconnect"
      );
    }
  
    return new Promise((resolve, reject) => {
      this.socket = new Socket();
  
      const timeout = setTimeout(() => {
        this.socket?.destroy();
        this.socket = null;
        reject(
          this.makeError(
            "CONNECTION_TIMEOUT",
            `Connection to ${host}:${port} timed out after 5 seconds`,
            "Ensure VICE is running with -binarymonitor flag: x64sc -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502"
          )
        );
      }, 5000);
  
      this.socket.on("connect", () => {
        clearTimeout(timeout);
        this.state = { connected: true, host, port, running: true };
        resolve();
      });
  
      this.socket.on("error", (err) => {
        clearTimeout(timeout);
        this.socket?.destroy();
        this.socket = null;
        this.state.connected = false;
        reject(
          this.makeError(
            "CONNECTION_FAILED",
            `Failed to connect to ${host}:${port}: ${err.message}`,
            "Ensure VICE is running with -binarymonitor flag: x64sc -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502"
          )
        );
      });
  
      this.socket.on("close", () => {
        this.state.connected = false;
        this.socket = null;
        // Reject all pending requests
        for (const [, { reject: rejectFn }] of this.pendingRequests) {
          rejectFn(
            this.makeError(
              "CONNECTION_CLOSED",
              "Connection to VICE closed unexpectedly",
              "VICE may have been closed or crashed. Try reconnecting."
            )
          );
        }
        this.pendingRequests.clear();
      });
  
      this.socket.on("data", (data) => this.handleData(data));
  
      this.socket.connect(port, host);
    });
  }