codex-control-chrome-mcp 1.0.0

package/src/mcp-server.js

@@ -0,0 +1,299 @@
+import crypto from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { connectBridge, listBridgeSockets } from "./bridge-client.js";
+import { nativeHostManifestPath } from "./constants.js";
+
+export async function runMcpServer() {
+  const runtime = new ChromeUseRuntime();
+  const server = new McpServer({
+    name: "codex-control-chrome-mcp",
+    version: "1.0.0",
+  });
+
+  registerTools(server, runtime);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+class ChromeUseRuntime {
+  constructor() {
+    this.sessionId = `codex-control-chrome-mcp-${crypto.randomUUID()}`;
+    this.bridge = null;
+  }
+
+  async rpc() {
+    if (!this.bridge) {
+      this.bridge = await connectBridge();
+    }
+    return this.bridge.rpc;
+  }
+
+  sessionParams() {
+    return {
+      session_id: this.sessionId,
+      turn_id: `turn-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`,
+      session_context: "codex-control-chrome-mcp",
+    };
+  }
+
+  async request(method, params = {}, options = {}) {
+    const rpc = await this.rpc();
+    return await rpc.request(method, { ...params, ...this.sessionParams() }, options);
+  }
+
+  async rawRequest(method, params = {}, options = {}) {
+    const rpc = await this.rpc();
+    return await rpc.request(method, params, options);
+  }
+}
+
+function registerTools(server, runtime) {
+  server.registerTool(
+    "chrome_status",
+    {
+      description: "Show native host manifest path and discovered bridge sockets.",
+      inputSchema: {},
+    },
+    async () => toolResult({
+      manifestPath: nativeHostManifestPath(),
+      sockets: await listBridgeSockets(),
+    }),
+  );
+
+  server.registerTool(
+    "chrome_bridge_status",
+    {
+      description: "Ask the active Codex Control Chrome MCP bridge for status.",
+      inputSchema: {},
+    },
+    async () => toolResult(await runtime.rawRequest("bridge.getStatus", {})),
+  );
+
+  server.registerTool(
+    "chrome_get_info",
+    {
+      description: "Get connected Codex Chrome extension backend info.",
+      inputSchema: {},
+    },
+    async () => toolResult(await runtime.request("getInfo")),
+  );
+
+  server.registerTool(
+    "chrome_name_session",
+    {
+      description: "Set the Chrome tab group/session name.",
+      inputSchema: {
+        name: z.string().default("Codex Control Chrome MCP"),
+      },
+    },
+    async ({ name }) => {
+      await runtime.request("nameSession", { name });
+      return toolResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "chrome_user_tabs",
+    {
+      description: "List user Chrome tabs visible to the extension.",
+      inputSchema: {},
+    },
+    async () => toolResult({ tabs: await runtime.request("getUserTabs") }),
+  );
+
+  server.registerTool(
+    "chrome_session_tabs",
+    {
+      description: "List tabs currently claimed by this MCP browser session.",
+      inputSchema: {},
+    },
+    async () => toolResult({ tabs: await runtime.request("getTabs") }),
+  );
+
+  server.registerTool(
+    "chrome_create_tab",
+    {
+      description: "Create a new background tab and claim it for this MCP session.",
+      inputSchema: {},
+    },
+    async () => toolResult(await runtime.request("createTab")),
+  );
+
+  server.registerTool(
+    "chrome_claim_tab",
+    {
+      description: "Claim an existing Chrome tab by numeric tab id.",
+      inputSchema: {
+        tabId: z.number().int().nonnegative(),
+      },
+    },
+    async ({ tabId }) => toolResult(await runtime.request("claimUserTab", { tabId })),
+  );
+
+  server.registerTool(
+    "chrome_attach_tab",
+    {
+      description: "Attach Chrome debugger to a claimed tab.",
+      inputSchema: {
+        tabId: z.number().int().nonnegative(),
+      },
+    },
+    async ({ tabId }) => {
+      await runtime.request("attach", { tabId });
+      return toolResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "chrome_detach_tab",
+    {
+      description: "Detach Chrome debugger from a claimed tab.",
+      inputSchema: {
+        tabId: z.number().int().nonnegative(),
+      },
+    },
+    async ({ tabId }) => {
+      await runtime.request("detach", { tabId });
+      return toolResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "chrome_cdp_send",
+    {
+      description: "Send a raw CDP command to a claimed and attached tab.",
+      inputSchema: {
+        tabId: z.number().int().nonnegative(),
+        method: z.string().min(1),
+        params: z.record(z.string(), z.unknown()).default({}),
+        timeoutMs: z.number().int().positive().optional(),
+      },
+    },
+    async (args) => toolResult(await executeCdp(runtime, args)),
+  );
+
+  server.registerTool(
+    "chrome_navigate",
+    {
+      description: "Navigate a claimed tab to a URL using CDP Page.navigate.",
+      inputSchema: {
+        tabId: z.number().int().nonnegative(),
+        url: z.string().url(),
+      },
+    },
+    async ({ tabId, url }) => {
+      await runtime.request("attach", { tabId });
+      await executeCdp(runtime, { tabId, method: "Page.enable", params: {} });
+      return toolResult(await executeCdp(runtime, {
+        tabId,
+        method: "Page.navigate",
+        params: { url },
+      }));
+    },
+  );
+
+  server.registerTool(
+    "chrome_evaluate",
+    {
+      description: "Evaluate JavaScript in a claimed tab using Runtime.evaluate.",
+      inputSchema: {
+        tabId: z.number().int().nonnegative(),
+        expression: z.string().min(1),
+        awaitPromise: z.boolean().default(true),
+      },
+    },
+    async ({ tabId, expression, awaitPromise }) => {
+      await runtime.request("attach", { tabId });
+      await executeCdp(runtime, { tabId, method: "Runtime.enable", params: {} });
+      return toolResult(await executeCdp(runtime, {
+        tabId,
+        method: "Runtime.evaluate",
+        params: {
+          expression,
+          awaitPromise,
+          returnByValue: true,
+        },
+      }));
+    },
+  );
+
+  server.registerTool(
+    "chrome_screenshot",
+    {
+      description: "Capture a screenshot from a claimed tab. Returns base64 PNG.",
+      inputSchema: {
+        tabId: z.number().int().nonnegative(),
+        format: z.enum(["png", "jpeg", "webp"]).default("png"),
+      },
+    },
+    async ({ tabId, format }) => {
+      await runtime.request("attach", { tabId });
+      await executeCdp(runtime, { tabId, method: "Page.enable", params: {} });
+      return toolResult(await executeCdp(runtime, {
+        tabId,
+        method: "Page.captureScreenshot",
+        params: { format, captureBeyondViewport: true },
+        timeoutMs: 30_000,
+      }));
+    },
+  );
+
+  server.registerTool(
+    "chrome_read_events",
+    {
+      description: "Read and clear CDP/download notifications buffered by this MCP process.",
+      inputSchema: {
+        method: z.string().optional(),
+        limit: z.number().int().positive().default(100),
+      },
+    },
+    async ({ method, limit }) => {
+      const rpc = await runtime.rpc();
+      return toolResult({ events: rpc.readNotifications({ method, limit }) });
+    },
+  );
+
+  server.registerTool(
+    "chrome_finalize_tabs",
+    {
+      description: "Finalize claimed tabs. Use status handoff or deliverable.",
+      inputSchema: {
+        keep: z.array(z.object({
+          tabId: z.number().int().nonnegative(),
+          status: z.enum(["handoff", "deliverable"]),
+        })).default([]),
+      },
+    },
+    async ({ keep }) => {
+      await runtime.request("finalizeTabs", { keep });
+      return toolResult({ ok: true });
+    },
+  );
+}
+
+async function executeCdp(runtime, { tabId, method, params = {}, timeoutMs }) {
+  return await runtime.request(
+    "executeCdp",
+    {
+      target: { tabId },
+      method,
+      commandParams: params,
+      ...(timeoutMs == null ? {} : { timeoutMs }),
+    },
+    { timeoutMs: Math.max(timeoutMs ?? 30_000, 30_000) },
+  );
+}
+
+function toolResult(value) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
+      },
+    ],
+  };
+}

package/src/native-host.js

@@ -0,0 +1,235 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import net from "node:net";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { APP_CONFIG_PATH, BRIDGE_SOCKET_DIR, BRIDGE_SOCKET_PREFIX } from "./constants.js";
+import { LengthPrefixedJsonPeer } from "./framing.js";
+
+const LOCAL_ID_PREFIX = "codex-control-chrome-mcp:";
+
+export async function runNativeHost({ origin = process.argv[2] } = {}) {
+  await fs.mkdir(BRIDGE_SOCKET_DIR, { recursive: true });
+  const socketPath = path.join(
+    BRIDGE_SOCKET_DIR,
+    `${BRIDGE_SOCKET_PREFIX}-${process.pid}-${crypto.randomUUID()}.sock`,
+  );
+
+  const extensionPeer = new LengthPrefixedJsonPeer({
+    input: process.stdin,
+    output: process.stdout,
+    name: "chrome-extension",
+  });
+
+  const proxyPeer = await maybeStartOfficialProxy(origin);
+  const bridge = new NativeHostBridge({ extensionPeer, proxyPeer });
+  await bridge.listen(socketPath);
+
+  const cleanup = async () => {
+    await bridge.close();
+    try {
+      await fs.unlink(socketPath);
+    } catch {}
+  };
+  process.once("SIGINT", () => cleanup().finally(() => process.exit(130)));
+  process.once("SIGTERM", () => cleanup().finally(() => process.exit(143)));
+  process.once("exit", () => {
+    try {
+      bridge.closeSync();
+    } catch {}
+  });
+}
+
+class NativeHostBridge {
+  constructor({ extensionPeer, proxyPeer = null }) {
+    this.extensionPeer = extensionPeer;
+    this.proxyPeer = proxyPeer;
+    this.server = null;
+    this.clients = new Map();
+    this.nextClientId = 1;
+    this.nextRequestId = 1;
+    this.pendingLocalRequests = new Map();
+
+    this.extensionPeer.on("message", (message) => this.#handleExtensionMessage(message));
+    this.extensionPeer.on("close", () => this.close());
+
+    if (this.proxyPeer) {
+      this.proxyPeer.on("message", (message) => this.#handleProxyMessage(message));
+      this.proxyPeer.on("close", () => {
+        this.proxyPeer = null;
+      });
+    }
+  }
+
+  async listen(socketPath) {
+    this.socketPath = socketPath;
+    this.server = net.createServer((socket) => this.#addClient(socket));
+    await new Promise((resolve, reject) => {
+      this.server.once("error", reject);
+      this.server.listen(socketPath, () => {
+        this.server.off("error", reject);
+        resolve();
+      });
+    });
+  }
+
+  async close() {
+    for (const peer of this.clients.values()) {
+      peer.close();
+    }
+    this.clients.clear();
+    if (this.server) {
+      await new Promise((resolve) => this.server.close(resolve));
+      this.server = null;
+    }
+  }
+
+  closeSync() {
+    for (const peer of this.clients.values()) {
+      peer.close();
+    }
+    this.server?.close();
+  }
+
+  #addClient(socket) {
+    const clientId = this.nextClientId++;
+    const peer = new LengthPrefixedJsonPeer({
+      input: socket,
+      output: socket,
+      name: `local-client:${clientId}`,
+    });
+    this.clients.set(clientId, peer);
+    peer.on("message", (message) => this.#handleLocalMessage(clientId, peer, message));
+    peer.on("close", () => {
+      this.clients.delete(clientId);
+      for (const [bridgeId, pending] of this.pendingLocalRequests) {
+        if (pending.clientId === clientId) {
+          this.pendingLocalRequests.delete(bridgeId);
+        }
+      }
+    });
+  }
+
+  #handleLocalMessage(clientId, peer, message) {
+    if (!message || typeof message !== "object" || !("method" in message)) {
+      return;
+    }
+    if (!("id" in message)) {
+      this.extensionPeer.send(message);
+      return;
+    }
+    if (message.method === "bridge.getStatus") {
+      peer.send({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          ok: true,
+          proxy: Boolean(this.proxyPeer),
+          clients: this.clients.size,
+          socketPath: this.socketPath,
+        },
+      });
+      return;
+    }
+    const bridgeId = `${LOCAL_ID_PREFIX}${clientId}:${this.nextRequestId++}`;
+    this.pendingLocalRequests.set(bridgeId, { clientId, originalId: message.id, peer });
+    this.extensionPeer.send({ ...message, id: bridgeId });
+  }
+
+  #handleExtensionMessage(message) {
+    if (!message || typeof message !== "object") {
+      return;
+    }
+    if ("id" in message && !("method" in message)) {
+      const id = String(message.id);
+      const pending = this.pendingLocalRequests.get(id);
+      if (pending) {
+        this.pendingLocalRequests.delete(id);
+        pending.peer.send({ ...message, id: pending.originalId });
+      } else {
+        this.proxyPeer?.send(message);
+      }
+      return;
+    }
+    if ("method" in message && !("id" in message)) {
+      this.#broadcast(message);
+      this.proxyPeer?.send(message);
+      return;
+    }
+    if ("method" in message && "id" in message) {
+      if (this.proxyPeer) {
+        this.proxyPeer.send(message);
+      } else {
+        this.#handleExtensionRequestStandalone(message);
+      }
+    }
+  }
+
+  #handleProxyMessage(message) {
+    this.extensionPeer.send(message);
+  }
+
+  #handleExtensionRequestStandalone(message) {
+    if (message.method === "ping") {
+      this.extensionPeer.send({ jsonrpc: "2.0", id: message.id, result: "pong" });
+      return;
+    }
+    if (message.method === "ensureCodexAppServer") {
+      this.extensionPeer.send({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          ok: false,
+          error: "Codex app server is not provided by codex-control-chrome-mcp standalone mode.",
+        },
+      });
+      return;
+    }
+    this.extensionPeer.send({
+      jsonrpc: "2.0",
+      id: message.id,
+      error: { code: -32601, message: `No native host handler for ${message.method}` },
+    });
+  }
+
+  #broadcast(message) {
+    for (const peer of this.clients.values()) {
+      try {
+        peer.send(message);
+      } catch {}
+    }
+  }
+}
+
+async function maybeStartOfficialProxy(origin) {
+  const config = await readJsonIfExists(APP_CONFIG_PATH);
+  const officialHostPath = config?.officialHostPath;
+  if (typeof officialHostPath !== "string" || officialHostPath.length === 0) {
+    return null;
+  }
+  if (path.resolve(officialHostPath) === path.resolve(process.argv[1])) {
+    return null;
+  }
+  try {
+    await fs.access(officialHostPath);
+  } catch {
+    return null;
+  }
+
+  const child = spawn(officialHostPath, [origin ?? ""], {
+    stdio: ["pipe", "pipe", "ignore"],
+  });
+  return new LengthPrefixedJsonPeer({
+    input: child.stdout,
+    output: child.stdin,
+    name: "official-extension-host",
+  });
+}
+
+async function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}

package/src/probe.js

@@ -0,0 +1,39 @@
+import net from "node:net";
+import { encodeLengthPrefixedJson } from "./framing.js";
+
+export async function probeLengthPrefixedSocket(socketPath) {
+  const events = [];
+  await new Promise((resolve) => {
+    const socket = net.createConnection(socketPath);
+    const timer = setTimeout(() => {
+      events.push({ type: "timeout" });
+      socket.destroy();
+      resolve();
+    }, 3000);
+
+    socket.on("connect", () => {
+      events.push({ type: "connect" });
+      socket.write(
+        encodeLengthPrefixedJson({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "getInfo",
+          params: {
+            session_id: "probe-session",
+            turn_id: "probe-turn",
+            session_context: "probe",
+          },
+        }),
+      );
+    });
+    socket.on("data", (chunk) => events.push({ type: "data", bytes: chunk.length }));
+    socket.on("end", () => events.push({ type: "end" }));
+    socket.on("error", (error) => events.push({ type: "error", message: error.message }));
+    socket.on("close", () => {
+      clearTimeout(timer);
+      events.push({ type: "close" });
+      resolve();
+    });
+  });
+  return events;
+}

package/src/rpc-client.js

@@ -0,0 +1,77 @@
+export class RpcClient {
+  constructor(peer, { idPrefix = "req" } = {}) {
+    this.peer = peer;
+    this.idPrefix = idPrefix;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.notifications = [];
+
+    this.peer.on("message", (message) => this.#handleMessage(message));
+    this.peer.on("close", (error) => this.#rejectAll(error ?? new Error("transport closed")));
+  }
+
+  request(method, params = {}, { timeoutMs = 30_000 } = {}) {
+    const id = `${this.idPrefix}:${this.nextId++}`;
+    const message = { jsonrpc: "2.0", id, method, params };
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timed out waiting for ${method}`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timeout });
+      try {
+        this.peer.send(message);
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pending.delete(id);
+        reject(error);
+      }
+    });
+  }
+
+  readNotifications({ method, limit = 100 } = {}) {
+    const selected = [];
+    const remaining = [];
+    for (const item of this.notifications) {
+      if (selected.length < limit && (method == null || item.method === method)) {
+        selected.push(item);
+      } else {
+        remaining.push(item);
+      }
+    }
+    this.notifications = remaining;
+    return selected;
+  }
+
+  #handleMessage(message) {
+    if (message && typeof message === "object" && "id" in message && !("method" in message)) {
+      const pending = this.pending.get(message.id);
+      if (!pending) {
+        return;
+      }
+      this.pending.delete(message.id);
+      clearTimeout(pending.timeout);
+      if ("error" in message) {
+        pending.reject(new Error(message.error?.message ?? String(message.error)));
+      } else {
+        pending.resolve(message.result);
+      }
+      return;
+    }
+    if (message && typeof message === "object" && "method" in message && !("id" in message)) {
+      this.notifications.push({
+        method: message.method,
+        params: message.params,
+        receivedAt: new Date().toISOString(),
+      });
+    }
+  }
+
+  #rejectAll(error) {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+}