Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

16.8 KB
Raw Blame
#!/usr/bin/env node
/**
 * WebBrain MCP server.
 *
 * Gives any MCP client β€” Claude Code, Codex, Cursor, OpenClaw β€” the ability to
 * delegate a browser task to the user's REAL browser session: already logged
 * in, cookies present, MFA already passed. That session is the thing a headless
 * automation framework cannot reproduce, and it is the only reason this server
 * is interesting.
 *
 * Scope is deliberately coarse. We expose task delegation, not the ~50
 * low-level browser primitives, because:
 *   1. the permission gate lives in the extension's agent loop, not in
 *      `executeTool()`, so per-primitive access would bypass every safety
 *      property WebBrain advertises; and
 *   2. driving 50 primitives over a socket costs a round trip and a pile of
 *      tokens per click. Delegation is both safer and cheaper.
 *
 * stdout belongs to the MCP stdio transport. All logging goes to stderr.
 */

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { randomUUID } from "node:crypto";
import { z } from "zod";

import { BridgeError, WebBrainBridge, type CloudSnapshot } from "./bridge.js";
import { bridgeUrl, config } from "./config.js";
import { loadPairingKey } from "./pairing.js";
import { abort, awaitSettled, describeSnapshot, getStatus, respond, startRun } from "./runs.js";
import { taskMemorySchema } from "./task-memory.js";

const bridge = new WebBrainBridge();

const server = new McpServer({
  name: "webbrain",
  version: "0.1.0",
});

type TextResult = {
  content: Array<{ type: "text"; text: string }>;
  isError?: boolean;
};

const ok = (text: string): TextResult => ({ content: [{ type: "text", text }] });
const fail = (text: string): TextResult => ({ content: [{ type: "text", text }], isError: true });

function toolError(error: unknown): TextResult {
  if (error instanceof BridgeError) return fail(error.message);
  return fail(error instanceof Error ? error.message : String(error));
}

server.registerTool(
  "webbrain_run",
  {
    title: "Run a browser task in the user's real session",
    description:
      "Delegate a web task to WebBrain running in the user's actual browser β€” already " +
      "signed in, with existing cookies and sessions. Use this when a task needs a page " +
      "the caller cannot reach: an authenticated dashboard, a webmail account, an admin " +
      "panel, a SaaS report behind SSO. Describe the goal in plain language, the way you " +
      "would to a colleague sharing the screen.\n\n" +
      "mode='ask' is read-only: it reads, extracts and summarises, and cannot click, type " +
      "or submit. mode='act' allows interaction, and the user is prompted in-browser to " +
      "approve consequential actions. Prefer 'ask' whenever you only need to read.\n\n" +
      "If the run stops with status 'needs_user_input', relay the question to the user and " +
      "answer with webbrain_respond β€” never guess on their behalf.",
    inputSchema: {
      task_memory: taskMemorySchema.optional().describe("Private run-scoped bot memory transport. Requires a browser advertising bot_memory_v1. Never include this envelope in task text."),
      task: z
        .string()
        .min(1)
        .describe(
          "The goal, in plain language. e.g. 'open the Stripe dashboard and list last " +
            "week's failed payments with amounts and customer emails'.",
        ),
      mode: z
        .enum(["ask", "act"])
        .default("ask")
        .describe(
          "'ask' is read-only and cannot modify the page. 'act' permits clicking, typing " +
            "and navigation, gated by in-browser approval. Default 'ask'.",
        ),
      tab_id: z
        .number()
        .int()
        .optional()
        .describe(
          "Target a specific browser tab. Omit to use the active tab, which is almost " +
            "always what you want.",
        ),
      allow_api_mutations: z
        .boolean()
        .default(false)
        .describe(
          "Lift WebBrain's UI-first rule so the agent may issue mutating HTTP requests " +
            "directly instead of clicking through the interface. Off by default and rarely " +
            "correct β€” the UI path is visible and stoppable. Only valid when mode is 'act'.",
        ),
      timeout_seconds: z
        .number()
        .int()
        .positive()
        .max(3600)
        .optional()
        .describe(
          "How long to wait before returning control. The run keeps going in the browser " +
            "past this point; poll webbrain_status to pick it back up.",
        ),
      wait: z
        .boolean()
        .default(true)
        .describe(
          "Wait for the run to settle. Set false to start it and return the run_id " +
            "immediately.",
        ),
    },
  },
  async ({ task, mode, tab_id, allow_api_mutations, timeout_seconds, wait, task_memory }): Promise<TextResult> => {
    const timeoutMs = timeout_seconds ? timeout_seconds * 1000 : config.defaultRunTimeoutMs;
    const deadline = Date.now() + timeoutMs;
    const runId = `mcp_${randomUUID()}`;
    try {
      let started: CloudSnapshot;
      try {
        started = await startRun(
          bridge,
          {
            runId,
            task,
            mode,
            tabId: tab_id,
            apiMutationsAllowed: allow_api_mutations,
            taskMemory: task_memory,
          },
          Math.max(1, deadline - Date.now()),
        );
      } catch (error) {
        if (
          error instanceof BridgeError &&
          (error.code === "COMMAND_TIMEOUT" || error.code === "COMMAND_INTERRUPTED")
        ) {
          return ok(describeSnapshot({ runId, status: "running" }, true));
        }
        throw error;
      }

      if (!wait) {
        return ok(
          `Started in the background.\n${describeSnapshot(started)}\n\n` +
            "Poll webbrain_status with this run_id for progress.",
        );
      }

      const { snapshot, timedOut } = await awaitSettled(bridge, started.runId, {
        timeoutMs: Math.max(0, deadline - Date.now()),
      });
      return ok(describeSnapshot(snapshot, timedOut));
    } catch (error) {
      return toolError(error);
    }
  },
);

server.registerTool(
  "webbrain_extract",
  {
    title: "Extract structured data from the user's real browser",
    description:
      "Read a page in the user's actual signed-in browser and return data that matches a " +
      "caller-supplied JSON Schema. This tool always uses WebBrain Ask mode, so it cannot " +
      "click, type, navigate or submit. Use it for authenticated reports, tables, account " +
      "details and other page data that should come back as predictable JSON rather than a " +
      "prose summary. Use webbrain_run instead when the task needs interaction.\n\n" +
      "If the run stops with status 'needs_user_input', relay the question to the user and " +
      "answer with webbrain_respond β€” never guess on their behalf.",
    inputSchema: {
      task: z
        .string()
        .min(1)
        .describe(
          "What to extract and any scope or filtering rules. Be explicit about the page, " +
            "time range, rows and fields the result should cover.",
        ),
      output_schema: z
        .record(z.unknown())
        .describe(
          "A JSON Schema object describing the exact result. Prefer an object root with " +
            "properties and required fields so the caller can rely on the returned shape.",
        ),
      tab_id: z
        .number()
        .int()
        .optional()
        .describe("Target a specific browser tab. Omit to use the active tab."),
      timeout_seconds: z
        .number()
        .int()
        .positive()
        .max(3600)
        .optional()
        .describe(
          "How long to wait before returning control. The extraction keeps running past " +
            "this point; poll webbrain_status with its run_id.",
        ),
      wait: z
        .boolean()
        .default(true)
        .describe(
          "Wait for the extraction to settle. Set false to start it and return the run_id " +
            "immediately.",
        ),
    },
  },
  async ({ task, output_schema, tab_id, timeout_seconds, wait }): Promise<TextResult> => {
    const timeoutMs = timeout_seconds ? timeout_seconds * 1000 : config.defaultRunTimeoutMs;
    const deadline = Date.now() + timeoutMs;
    const runId = `mcp_${randomUUID()}`;
    try {
      let started: CloudSnapshot;
      try {
        started = await startRun(
          bridge,
          {
            runId,
            task,
            mode: "ask",
            tabId: tab_id,
            outputSchema: output_schema,
          },
          Math.max(1, deadline - Date.now()),
        );
      } catch (error) {
        if (
          error instanceof BridgeError &&
          (error.code === "COMMAND_TIMEOUT" || error.code === "COMMAND_INTERRUPTED")
        ) {
          return ok(describeSnapshot({ runId, status: "running" }, true));
        }
        throw error;
      }

      if (!wait) {
        return ok(
          `Structured extraction started in the background.\n${describeSnapshot(started)}\n\n` +
            "Poll webbrain_status with this run_id for progress.",
        );
      }

      const { snapshot, timedOut } = await awaitSettled(bridge, started.runId, {
        timeoutMs: Math.max(0, deadline - Date.now()),
      });
      return ok(describeSnapshot(snapshot, timedOut));
    } catch (error) {
      return toolError(error);
    }
  },
);

server.registerTool(
  "webbrain_status",
  {
    title: "Check a browser run",
    description:
      "Fetch the current state of a WebBrain run, including its result once finished. " +
      "Omit run_id to list every run this browser knows about.",
    inputSchema: {
      run_id: z
        .string()
        .optional()
        .describe("The run to inspect. Omit to list all runs."),
    },
  },
  async ({ run_id }): Promise<TextResult> => {
    try {
      const result = await getStatus(bridge, run_id);
      const runs = (result as { runs?: CloudSnapshot[] }).runs;
      if (runs) {
        if (!runs.length) return ok("No WebBrain runs on record.");
        return ok(
          runs
            .map((run) => `${run.runId}  ${run.status.padEnd(16)}  ${run.task ?? ""}`)
            .join("\n"),
        );
      }
      return ok(describeSnapshot(result as CloudSnapshot));
    } catch (error) {
      return toolError(error);
    }
  },
);

server.registerTool(
  "webbrain_respond",
  {
    title: "Answer a question from a browser run",
    description:
      "Supply the user's answer to a run sitting at status 'needs_user_input', then keep " +
      "waiting for it to settle. The answer must come from the user β€” WebBrain pauses " +
      "precisely because a human decision is required. For an ordinary clarification, pass " +
      "the user's answer verbatim. For a structured permission prompt, map the user's explicit " +
      "decision to the exact stable value shown by WebBrain: 'once', 'always', or 'deny'. Never " +
      "infer permission, and use 'always' only when the user explicitly requests a persistent grant. " +
      "Any other structured gate (form-submission confirmation, saved-workflow repair) lists its own " +
      "stable values on a 'decisions:' line β€” send one of those exactly, never a localized label.",
    inputSchema: {
      run_id: z.string().describe("The run that is waiting."),
      clarify_id: z.string().describe("The clarify_id reported alongside the question."),
      answer: z
        .string()
        .min(1)
        .describe(
          "For an ordinary clarification, the user's answer passed through verbatim. For a " +
            "permission prompt, the exact stable decision 'once', 'always', or 'deny' after the " +
            "user explicitly chooses it; a normal one-time approval maps to 'once'. For any other " +
            "structured gate, one of the exact values listed on its 'decisions:' line.",
        ),
      timeout_seconds: z
        .number()
        .int()
        .positive()
        .max(3600)
        .optional()
        .describe("How long to wait after answering before returning control."),
    },
  },
  async ({ run_id, clarify_id, answer, timeout_seconds }): Promise<TextResult> => {
    const timeoutMs = timeout_seconds ? timeout_seconds * 1000 : config.defaultRunTimeoutMs;
    const deadline = Date.now() + timeoutMs;
    try {
      try {
        await respond(
          bridge,
          run_id,
          clarify_id,
          answer,
          Math.max(1, deadline - Date.now()),
        );
      } catch (error) {
        if (
          error instanceof BridgeError &&
          (error.code === "COMMAND_TIMEOUT" || error.code === "COMMAND_INTERRUPTED")
        ) {
          return ok(describeSnapshot({ runId: run_id, status: "running" }, true));
        }
        throw error;
      }
      const { snapshot, timedOut } = await awaitSettled(bridge, run_id, {
        timeoutMs: Math.max(0, deadline - Date.now()),
      });
      return ok(describeSnapshot(snapshot, timedOut));
    } catch (error) {
      return toolError(error);
    }
  },
);

server.registerTool(
  "webbrain_abort",
  {
    title: "Stop a browser run",
    description:
      "Halt a run that is going wrong or is no longer needed. Note that actions already " +
      "taken in the browser are not undone.",
    inputSchema: {
      run_id: z.string().describe("The run to stop."),
    },
  },
  async ({ run_id }): Promise<TextResult> => {
    try {
      const snapshot = await abort(bridge, run_id);
      return ok(describeSnapshot(snapshot));
    } catch (error) {
      return toolError(error);
    }
  },
);

server.registerTool(
  "webbrain_connection",
  {
    title: "Check the WebBrain browser connection",
    description:
      "Report whether a WebBrain extension is currently attached. Call this first when a " +
      "browser tool fails, so you can tell the user what to fix instead of retrying blindly.",
    inputSchema: {},
  },
  async (): Promise<TextResult> => {
    if (bridge.isConnected()) {
      const caps = bridge.capabilities();
      return ok(
        `Connected. Listening on ${bridgeUrl()}.` +
          (caps.length ? `\nExtension capabilities: ${caps.join(", ")}` : ""),
      );
    }
    return ok(
      `Not connected. Listening on ${bridgeUrl()}, but no paired extension has dialled in.\n\n` +
        "To connect: open a Chromium browser (Chrome, Edge, Brave), then in " +
        "WebBrain β†’ Settings β†’ Bridge set the URL to\n" +
        `  ${bridgeUrl()}\n` +
        "paste the pairing key into Pairing key, and enable it. The key comes from " +
        `${bridge.pairingKeySource()}; when that is a file, the user can print it with ` +
        "`npx -y @webbrain/mcp-server pairing-key`. " +
        "Do not ask the user to paste the key into this chat. WebBrain versions without a " +
        "Pairing key field must be updated first. The extension holds one bridge socket at a time, so this cannot " +
        "run at the same time as WebBrain Cloud on port 17373.\n\n" +
        "Firefox cannot host the bridge β€” that build has no offscreen document. If the " +
        "user is on Firefox, say so rather than suggesting settings changes.",
    );
  },
);

async function main(): Promise<void> {
  await bridge.start();

  // Give an already-open extension a bounded chance to reconnect before the
  // stdio server advertises browser tools. If this promise is discarded, the
  // grace period is illusory and the first tool call can race the reconnect.
  await bridge.waitForExtension(3_000);

  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("[webbrain-mcp] ready on stdio");
}

let shuttingDown = false;
async function shutdown(): Promise<void> {
  if (shuttingDown) return;
  shuttingDown = true;
  await bridge.stop().catch((error) => {
    console.error("[webbrain-mcp] shutdown error:", error);
  });
  process.exit(0);
}

if (process.argv[2] === "pairing-key") {
  // `webbrain-mcp pairing-key` prints the key to paste into WebBrain β†’
  // Settings β†’ Bridge (creating it on first use) and exits without serving.
  try {
    const { key, source } = loadPairingKey();
    process.stdout.write(`${key}\n`);
    console.error(`[webbrain-mcp] pairing key from ${source}`);
  } catch (error) {
    console.error("[webbrain-mcp] fatal:", error instanceof Error ? error.message : error);
    process.exitCode = 1;
  }
} else {
  process.on("SIGINT", () => void shutdown());
  process.on("SIGTERM", () => void shutdown());
  // MCP hosts commonly stop stdio servers by closing the child's stdin rather
  // than sending a signal. Without these handlers the WebSocket listener keeps
  // the event loop alive and leaves port 17374 occupied by an orphan process.
  process.stdin.once("end", () => void shutdown());
  process.stdin.once("close", () => void shutdown());

  main().catch((error) => {
    console.error("[webbrain-mcp] fatal:", error);
    process.exit(1);
  });
}