VICE C64 Emulator MCP Server

Instructions

Implementation Reference

• src/index.ts:115-158 (registration)

  Registration of the MCP 'connect' tool, including Zod input schema for optional host/port parameters and the tool handler lambda that invokes ViceClient.connect and formats the response with metadata.
  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/protocol/client.ts:78-142 (handler)

  ViceClient.connect: core socket connection logic to VICE binary monitor, with timeout, error handling, state updates, and data handler setup.
  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); }); }
• src/index.ts:26-47 (helper)

  formatResponse helper function used by the connect tool handler to standardize responses with JSON output including connection metadata.
  function formatResponse(data: object) { const state = client.getState(); return { content: [ { type: "text" as const, text: JSON.stringify( { ...data, _meta: { connected: state.connected, running: state.running, ...(state.connected && { host: state.host, port: state.port }), }, }, null, 2 ), }, ], }; }
• src/index.ts:50-79 (helper)

  formatError helper used by connect tool handler to format error responses with connection state metadata.
  function formatError(error: ViceError | Error) { const state = client.getState(); const errorData = "code" in error ? error : { error: true, code: "UNKNOWN_ERROR", message: error.message, }; return { content: [ { type: "text" as const, text: JSON.stringify( { ...errorData, _meta: { connected: state.connected, running: state.running, }, }, null, 2 ), }, ], }; }
• src/index.ts:23-24 (helper)

  Singleton ViceClient instance used by all tools including connect.
  const client = getViceClient();