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