codex-control-chrome-mcp 1.0.0

package/src/bridge-client.js

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import net from "node:net";
+import path from "node:path";
+import { BRIDGE_SOCKET_DIR, BRIDGE_SOCKET_PREFIX } from "./constants.js";
+import { LengthPrefixedJsonPeer } from "./framing.js";
+import { RpcClient } from "./rpc-client.js";
+
+export async function listBridgeSockets() {
+  let names = [];
+  try {
+    names = await fs.readdir(BRIDGE_SOCKET_DIR);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((name) => name.startsWith(`${BRIDGE_SOCKET_PREFIX}-`) && name.endsWith(".sock"))
+    .map((name) => path.join(BRIDGE_SOCKET_DIR, name))
+    .sort((a, b) => a.localeCompare(b));
+}
+
+export async function connectBridge({ socketPath, timeoutMs = 5000 } = {}) {
+  const sockets = socketPath ? [socketPath] : await listBridgeSockets();
+  const failures = [];
+  for (const candidate of sockets) {
+    try {
+      const socket = await connectUnixSocket(candidate, timeoutMs);
+      const peer = new LengthPrefixedJsonPeer({
+        input: socket,
+        output: socket,
+        name: `bridge:${candidate}`,
+      });
+      const rpc = new RpcClient(peer, { idPrefix: `mcp-${process.pid}` });
+      return { socketPath: candidate, peer, rpc };
+    } catch (error) {
+      failures.push(`${candidate}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  throw new Error(
+    `No Codex Control Chrome MCP bridge socket is available. Tried ${sockets.length} socket(s). ${failures.join("; ")}`,
+  );
+}
+
+function connectUnixSocket(socketPath, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      reject(new Error(`connect timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    socket.once("connect", () => {
+      clearTimeout(timeout);
+      resolve(socket);
+    });
+    socket.once("error", (error) => {
+      clearTimeout(timeout);
+      reject(error);
+    });
+  });
+}

package/src/cli.js

@@ -0,0 +1,89 @@
+import { runMcpServer } from "./mcp-server.js";
+import { runNativeHost } from "./native-host.js";
+import { installNativeHost, nativeHostInstallStatus, uninstallNativeHost } from "./installer.js";
+import { listBridgeSockets } from "./bridge-client.js";
+import { probeLengthPrefixedSocket } from "./probe.js";
+
+export async function runCli(argv) {
+  const args = argv.slice(2);
+  const command = args[0];
+
+  if (args.includes("--stdio") || command === "stdio") {
+    await runMcpServer();
+    return;
+  }
+
+  if (args.includes("--native-host") || looksLikeChromeOrigin(command)) {
+    await runNativeHost({ origin: looksLikeChromeOrigin(command) ? command : argv[3] });
+    return;
+  }
+
+  switch (command) {
+    case "install-native-host": {
+      const binPath = readOption(args, "--bin");
+      const noProxy = args.includes("--no-proxy");
+      const result = await installNativeHost({ binPath, proxy: !noProxy });
+      printJson(result);
+      return;
+    }
+    case "uninstall-native-host": {
+      const result = await uninstallNativeHost({ force: args.includes("--force") });
+      printJson(result);
+      return;
+    }
+    case "status": {
+      printJson({
+        install: await nativeHostInstallStatus(),
+        sockets: await listBridgeSockets(),
+      });
+      return;
+    }
+    case "probe-socket": {
+      const socketPath = args[1];
+      if (!socketPath) {
+        throw new Error("Usage: codex-control-chrome-mcp probe-socket <socket-path>");
+      }
+      printJson(await probeLengthPrefixedSocket(socketPath));
+      return;
+    }
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+      printHelp();
+      return;
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+}
+
+function looksLikeChromeOrigin(value) {
+  return typeof value === "string" && value.startsWith("chrome-extension://");
+}
+
+function readOption(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function printHelp() {
+  process.stdout.write(`codex-control-chrome-mcp
+
+Usage:
+  codex-control-chrome-mcp --stdio
+  codex-control-chrome-mcp --native-host
+  codex-control-chrome-mcp install-native-host [--bin /path/to/codex-control-chrome-mcp] [--no-proxy]
+  codex-control-chrome-mcp uninstall-native-host [--force]
+  codex-control-chrome-mcp status
+  codex-control-chrome-mcp probe-socket <socket-path>
+
+Notes:
+  --stdio is the MCP server mode for Agent tools.
+  --native-host is normally launched by Chrome through Native Messaging.
+  install-native-host without --bin writes a stable launcher that runs npx.
+`);
+}

package/src/constants.js

@@ -0,0 +1,47 @@
+import os from "node:os";
+import path from "node:path";
+
+export const CODEX_EXTENSION_ID = "hehggadaopoacecdllhhajmbjkdcmajg";
+export const CODEX_NATIVE_HOST_NAME = "com.openai.codexextension";
+export const BRIDGE_SOCKET_DIR =
+  process.platform === "win32" ? "\\\\.\\pipe\\codex-browser-use" : "/tmp/codex-browser-use";
+export const BRIDGE_SOCKET_PREFIX = "codex-control-chrome-mcp";
+export const APP_STATE_DIR = path.join(os.homedir(), ".codex-control-chrome-mcp");
+export const APP_CONFIG_PATH = path.join(APP_STATE_DIR, "config.json");
+export const INSTALL_STATE_PATH = path.join(APP_STATE_DIR, "install-state.json");
+
+export function nativeHostManifestPath() {
+  const home = os.homedir();
+  switch (process.platform) {
+    case "darwin":
+      return path.join(
+        home,
+        "Library",
+        "Application Support",
+        "Google",
+        "Chrome",
+        "NativeMessagingHosts",
+        `${CODEX_NATIVE_HOST_NAME}.json`,
+      );
+    case "linux":
+      return path.join(
+        home,
+        ".config",
+        "google-chrome",
+        "NativeMessagingHosts",
+        `${CODEX_NATIVE_HOST_NAME}.json`,
+      );
+    case "win32":
+      return path.join(
+        home,
+        "AppData",
+        "Local",
+        "Google",
+        "Chrome",
+        "NativeMessagingHosts",
+        `${CODEX_NATIVE_HOST_NAME}.json`,
+      );
+    default:
+      throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+}

package/src/framing.js

@@ -0,0 +1,75 @@
+import { EventEmitter } from "node:events";
+import os from "node:os";
+
+const LENGTH_BYTES = 4;
+const IS_LE = os.endianness() === "LE";
+
+export function encodeLengthPrefixedJson(message) {
+  const payload = Buffer.from(JSON.stringify(message), "utf8");
+  const header = Buffer.alloc(LENGTH_BYTES);
+  if (IS_LE) {
+    header.writeUInt32LE(payload.length, 0);
+  } else {
+    header.writeUInt32BE(payload.length, 0);
+  }
+  return Buffer.concat([header, payload]);
+}
+
+function readFrameLength(buffer) {
+  return IS_LE ? buffer.readUInt32LE(0) : buffer.readUInt32BE(0);
+}
+
+export class LengthPrefixedJsonPeer extends EventEmitter {
+  constructor({ input, output, name = "peer" }) {
+    super();
+    this.input = input;
+    this.output = output;
+    this.name = name;
+    this.buffer = Buffer.alloc(0);
+    this.closed = false;
+
+    this.input.on("data", (chunk) => this.#handleData(chunk));
+    this.input.on("end", () => this.#markClosed());
+    this.input.on("close", () => this.#markClosed());
+    this.input.on("error", (error) => this.#markClosed(error));
+    this.output.on?.("error", (error) => this.#markClosed(error));
+  }
+
+  send(message) {
+    if (this.closed) {
+      throw new Error(`${this.name} is closed`);
+    }
+    this.output.write(encodeLengthPrefixedJson(message));
+  }
+
+  close() {
+    this.#markClosed();
+    this.output.end?.();
+    this.input.destroy?.();
+  }
+
+  #handleData(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    while (this.buffer.length >= LENGTH_BYTES) {
+      const length = readFrameLength(this.buffer);
+      if (this.buffer.length < LENGTH_BYTES + length) {
+        return;
+      }
+      const payload = this.buffer.subarray(LENGTH_BYTES, LENGTH_BYTES + length);
+      this.buffer = this.buffer.subarray(LENGTH_BYTES + length);
+      try {
+        this.emit("message", JSON.parse(payload.toString("utf8")));
+      } catch (error) {
+        this.emit("error", error);
+      }
+    }
+  }
+
+  #markClosed(error) {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.emit("close", error);
+  }
+}

package/src/installer.js

@@ -0,0 +1,161 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  APP_CONFIG_PATH,
+  APP_STATE_DIR,
+  CODEX_EXTENSION_ID,
+  CODEX_NATIVE_HOST_NAME,
+  INSTALL_STATE_PATH,
+  nativeHostManifestPath,
+} from "./constants.js";
+
+const PACKAGE_NAME = "codex-control-chrome-mcp";
+const PACKAGE_VERSION = "1.0.0";
+const MANIFEST_DESCRIPTION = "Codex Control Chrome MCP native messaging host";
+
+export async function installNativeHost({ binPath, proxy = true } = {}) {
+  const manifestPath = nativeHostManifestPath();
+  await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+  await fs.mkdir(APP_STATE_DIR, { recursive: true });
+
+  const hostPath = binPath ? await createLocalLauncher(path.resolve(binPath)) : await createNpxLauncher();
+  const existing = await readJsonIfExists(manifestPath);
+  const previousState = await readJsonIfExists(INSTALL_STATE_PATH);
+  const previousBackup = previousState?.backupPath
+    ? await readJsonIfExists(previousState.backupPath)
+    : null;
+  const existingIsOurs = isProjectManifest(existing);
+  const previousBackupIsOurs = isProjectManifest(previousBackup);
+  let backupPath = null;
+  if (existing && !existingIsOurs) {
+    backupPath = await backupManifest(manifestPath);
+  } else if (previousBackup && !previousBackupIsOurs) {
+    backupPath = previousState.backupPath;
+  }
+
+  let officialHostPath = null;
+  if (proxy && previousBackup?.path && !previousBackupIsOurs) {
+    officialHostPath = previousBackup.path;
+  } else if (
+    proxy &&
+    typeof previousState?.officialHostPath === "string" &&
+    path.resolve(previousState.officialHostPath) !== path.resolve(hostPath)
+  ) {
+    officialHostPath = previousState.officialHostPath;
+  } else if (
+    proxy &&
+    existing?.path &&
+    !existingIsOurs &&
+    path.resolve(existing.path) !== path.resolve(hostPath)
+  ) {
+    officialHostPath = existing.path;
+  }
+
+  const manifest = {
+    allowed_origins: [`chrome-extension://${CODEX_EXTENSION_ID}/`],
+    description: MANIFEST_DESCRIPTION,
+    name: CODEX_NATIVE_HOST_NAME,
+    path: hostPath,
+    type: "stdio",
+  };
+  await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+
+  const config = {
+    installedAt: new Date().toISOString(),
+    manifestPath,
+    hostPath,
+    launchMode: binPath ? "direct-bin" : "npx-launcher",
+    backupPath,
+    officialHostPath,
+    proxy,
+  };
+  await fs.writeFile(APP_CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  await fs.writeFile(INSTALL_STATE_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  return config;
+}
+
+export async function uninstallNativeHost({ force = false } = {}) {
+  const manifestPath = nativeHostManifestPath();
+  const state = await readJsonIfExists(INSTALL_STATE_PATH);
+  const manifest = await readJsonIfExists(manifestPath);
+
+  if (!manifest && !state?.backupPath) {
+    return { ok: true, action: "noop", manifestPath };
+  }
+
+  if (!force && !isProjectManifest(manifest)) {
+    throw new Error(
+      `Refusing to uninstall because ${manifestPath} does not look like a codex-control-chrome-mcp manifest. Use --force to override.`,
+    );
+  }
+
+  if (state?.backupPath) {
+    await fs.copyFile(state.backupPath, manifestPath);
+    return { ok: true, action: "restored", manifestPath, backupPath: state.backupPath };
+  }
+
+  await fs.rm(manifestPath, { force: true });
+  return { ok: true, action: "removed", manifestPath };
+}
+
+export async function nativeHostInstallStatus() {
+  const manifestPath = nativeHostManifestPath();
+  const manifest = await readJsonIfExists(manifestPath);
+  const state = await readJsonIfExists(INSTALL_STATE_PATH);
+  return { manifestPath, manifest, state };
+}
+
+async function backupManifest(manifestPath) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupPath = path.join(
+    path.dirname(manifestPath),
+    `${path.basename(manifestPath)}.backup-${stamp}`,
+  );
+  await fs.copyFile(manifestPath, backupPath);
+  return backupPath;
+}
+
+async function createNpxLauncher() {
+  if (process.platform === "win32") {
+    throw new Error("NPX native host launcher installation is not implemented for Windows yet.");
+  }
+  const launcherPath = path.join(APP_STATE_DIR, "native-host-launcher");
+  const script = `#!/usr/bin/env sh
+exec npx -y ${PACKAGE_NAME}@${PACKAGE_VERSION} --native-host "$@"
+`;
+  await fs.writeFile(launcherPath, script, { encoding: "utf8", mode: 0o755 });
+  await fs.chmod(launcherPath, 0o755);
+  return launcherPath;
+}
+
+function isProjectManifest(manifest) {
+  return manifest?.description === MANIFEST_DESCRIPTION;
+}
+
+async function createLocalLauncher(binPath) {
+  if (process.platform === "win32") {
+    return binPath;
+  }
+  if (!binPath.endsWith(".js")) {
+    return binPath;
+  }
+  const launcherPath = path.join(APP_STATE_DIR, "native-host-local-launcher");
+  const script = `#!/usr/bin/env sh
+exec ${shellQuote(process.execPath)} ${shellQuote(binPath)} "$@"
+`;
+  await fs.writeFile(launcherPath, script, { encoding: "utf8", mode: 0o755 });
+  await fs.chmod(launcherPath, 0o755);
+  return launcherPath;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+async function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}