mcp-scraper 0.2.19 → 0.2.21

package/dist/chunk-HS6OKELW.js

@@ -0,0 +1,1786 @@
+import {
+  browserServiceProfileName,
+  browserServiceProfileSaveChanges
+} from "./chunk-WN7PBKMV.js";
+import {
+  defaultChromeExecutablePath,
+  importChromeProfile,
+  listLocalChromeProfiles,
+  loadImportedBrowserProfile,
+  localBrowserModeEnabled,
+  syncImportedChromeProfile
+} from "./chunk-DUEW4EOO.js";
+import {
+  PACKAGE_VERSION
+} from "./chunk-XKUDVN2E.js";
+
+// src/mcp/browser-agent-mcp-server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { mkdirSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+
+// src/services/browser-agent/local-browser-agent-service.ts
+import { randomUUID } from "crypto";
+import { existsSync } from "fs";
+import { basename } from "path";
+import { chromium } from "playwright";
+function directProfileDir() {
+  return process.env.MCP_SCRAPER_BROWSER_PROFILE_DIR?.trim() || void 0;
+}
+function configuredProfileName(profile) {
+  return profile?.trim() || process.env.MCP_SCRAPER_BROWSER_PROFILE?.trim() || (directProfileDir() ? basename(directProfileDir()) : "default");
+}
+function launchExecutablePath(profile) {
+  const configured = process.env.MCP_SCRAPER_BROWSER_EXECUTABLE?.trim() || profile.browserExecutablePath || defaultChromeExecutablePath();
+  return configured && existsSync(configured) ? configured : void 0;
+}
+function ignoreDefaultArgsFor(executablePath) {
+  if (!executablePath) return void 0;
+  if (process.platform !== "darwin") return void 0;
+  if (!/Google Chrome\.app\/Contents\/MacOS\/Google Chrome$/.test(executablePath)) return void 0;
+  return ["--password-store=basic", "--use-mock-keychain"];
+}
+function normalizeKeyCombo(value) {
+  return value.split("+").map((part) => {
+    const trimmed = part.trim();
+    const lower = trimmed.toLowerCase();
+    if (lower === "ctrl" || lower === "control") return "Control";
+    if (lower === "cmd" || lower === "command" || lower === "meta") return "Meta";
+    if (lower === "option" || lower === "alt") return "Alt";
+    if (lower === "return") return "Enter";
+    if (lower === "esc") return "Escape";
+    if (trimmed.length === 1) return trimmed.toUpperCase();
+    return trimmed;
+  }).join("+");
+}
+function sessionSummary(session) {
+  return {
+    session_id: session.sessionId,
+    status: session.status,
+    label: session.label,
+    profile: session.profileName,
+    user_data_dir: session.userDataDir,
+    created_at: session.createdAt,
+    last_action_at: session.lastActionAt,
+    closed_at: session.closedAt,
+    watch_url: `local://browser-session/${session.sessionId}`,
+    url: session.status === "open" ? session.page.url() : null
+  };
+}
+var LocalBrowserAgentService = class {
+  contexts = /* @__PURE__ */ new Map();
+  sessions = /* @__PURE__ */ new Map();
+  async open(input) {
+    const profile = await this.resolveProfile(input.profile);
+    const contextState = await this.ensureContext(profile);
+    const pages = contextState.context.pages();
+    const page = pages.length === 1 && !this.hasOpenSessionForContext(contextState.key) ? pages[0] : await contextState.context.newPage();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const sessionId = `lbs_${randomUUID().replace(/-/g, "").slice(0, 20)}`;
+    const session = {
+      sessionId,
+      label: input.label ?? null,
+      page,
+      contextKey: contextState.key,
+      profileName: profile.name,
+      userDataDir: profile.userDataDir,
+      createdAt: now,
+      lastActionAt: now,
+      closedAt: null,
+      status: "open"
+    };
+    const timeoutSeconds = input.timeout_seconds ?? 600;
+    if (timeoutSeconds > 0) {
+      session.timeout = setTimeout(() => {
+        void this.close(sessionId);
+      }, timeoutSeconds * 1e3);
+      session.timeout.unref();
+    }
+    this.sessions.set(sessionId, session);
+    if (input.url) await this.goto(sessionId, input.url);
+    return {
+      session_id: sessionId,
+      watch_url: `local://browser-session/${sessionId}`,
+      live_view_url: null,
+      profile: profile.name,
+      user_data_dir: profile.userDataDir,
+      url: input.url ?? null,
+      mode: "local"
+    };
+  }
+  async screenshot(sessionId) {
+    const session = this.requireOpenSession(sessionId);
+    await this.waitForPage(session.page);
+    const image = await session.page.screenshot({ type: "png", fullPage: false });
+    const page = await this.read(sessionId);
+    return {
+      ...page,
+      image_base64: image.toString("base64"),
+      mime_type: "image/png"
+    };
+  }
+  async read(sessionId) {
+    const session = this.requireOpenSession(sessionId);
+    await this.waitForPage(session.page);
+    this.touch(session);
+    const title = await session.page.title().catch(() => "");
+    const snapshot = await session.page.evaluate(() => {
+      const cssEscape = (value) => {
+        const escapeFn = globalThis.CSS?.escape;
+        return escapeFn ? escapeFn(value) : value.replace(/["\\#.:>+~[\]()]/g, "\\$&");
+      };
+      const textFor = (element) => {
+        const html = element;
+        return (element.getAttribute("aria-label") || element.getAttribute("title") || html.placeholder || html.value || html.innerText || element.textContent || "").replace(/\s+/g, " ").trim();
+      };
+      const selectorFor = (element) => {
+        const id = element.id;
+        if (id) return `#${cssEscape(id)}`;
+        const name = element.getAttribute("name");
+        const tag = element.tagName.toLowerCase();
+        if (name) return `${tag}[name="${name.replace(/"/g, '\\"')}"]`;
+        const parts = [];
+        let current = element;
+        while (current && current !== document.body && parts.length < 4) {
+          const currentTag = current.tagName.toLowerCase();
+          const parent = current.parentElement;
+          if (!parent) {
+            parts.unshift(currentTag);
+            break;
+          }
+          const children = Array.from(parent.children);
+          const siblings = children.filter((child) => child.tagName === current.tagName);
+          const index = siblings.indexOf(current) + 1;
+          parts.unshift(siblings.length > 1 ? `${currentTag}:nth-of-type(${index})` : currentTag);
+          current = parent;
+        }
+        return parts.join(" > ") || tag;
+      };
+      const candidates = Array.from(document.querySelectorAll(
+        'a, button, input, textarea, select, summary, [role], [contenteditable="true"], [tabindex]:not([tabindex="-1"])'
+      ));
+      const elements = candidates.map((element, index) => {
+        const rect = element.getBoundingClientRect();
+        const style = window.getComputedStyle(element);
+        const visible = rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden" && Number(style.opacity || "1") > 0;
+        if (!visible) return null;
+        const label = textFor(element);
+        return {
+          index,
+          tag: element.tagName.toLowerCase(),
+          role: element.getAttribute("role") || null,
+          text: label.slice(0, 180),
+          selector: selectorFor(element),
+          x: Math.round(rect.left + rect.width / 2),
+          y: Math.round(rect.top + rect.height / 2),
+          left: Math.round(rect.left),
+          top: Math.round(rect.top),
+          width: Math.round(rect.width),
+          height: Math.round(rect.height)
+        };
+      }).filter(Boolean).slice(0, 120);
+      return {
+        text: (document.body?.innerText || "").replace(/\n{3,}/g, "\n\n").slice(0, 3e4),
+        elements,
+        viewport: {
+          width: window.innerWidth,
+          height: window.innerHeight,
+          devicePixelRatio: window.devicePixelRatio,
+          scrollX: window.scrollX,
+          scrollY: window.scrollY
+        }
+      };
+    });
+    return {
+      url: session.page.url(),
+      title,
+      text: snapshot.text,
+      elements: snapshot.elements,
+      viewport: snapshot.viewport
+    };
+  }
+  async locate(sessionId, targets) {
+    const session = this.requireOpenSession(sessionId);
+    this.touch(session);
+    const located = [];
+    for (const target of targets) {
+      try {
+        const locator = target.selector ? session.page.locator(target.selector) : session.page.getByText(target.text ?? "", { exact: target.match === "exact" });
+        const selected = locator.nth(target.index ?? 0);
+        await selected.waitFor({ state: "visible", timeout: 3e3 }).catch(() => void 0);
+        const box = await selected.boundingBox();
+        const text = await selected.textContent({ timeout: 1e3 }).catch(() => null);
+        located.push({
+          input: target,
+          found: Boolean(box),
+          element: box ? {
+            left: Math.round(box.x),
+            top: Math.round(box.y),
+            width: Math.round(box.width),
+            height: Math.round(box.height),
+            x: Math.round(box.x + box.width / 2),
+            y: Math.round(box.y + box.height / 2),
+            text: (text ?? "").replace(/\s+/g, " ").trim().slice(0, 220)
+          } : null
+        });
+      } catch (err) {
+        located.push({
+          input: target,
+          found: false,
+          element: null,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+    const read = await this.read(sessionId);
+    return {
+      url: read.url,
+      title: read.title,
+      viewport: read.viewport,
+      replay: null,
+      targets: located
+    };
+  }
+  async goto(sessionId, url) {
+    const session = this.requireOpenSession(sessionId);
+    this.touch(session);
+    const response = await session.page.goto(url, { waitUntil: "domcontentloaded", timeout: 45e3 }).catch((err) => {
+      throw new Error(err instanceof Error ? err.message : String(err));
+    });
+    await this.waitForPage(session.page);
+    return {
+      ok: true,
+      url: session.page.url(),
+      status: response?.status() ?? null,
+      mode: "local"
+    };
+  }
+  async click(sessionId, input) {
+    const session = this.requireOpenSession(sessionId);
+    this.touch(session);
+    await session.page.mouse.click(input.x, input.y, {
+      button: input.button ?? "left",
+      clickCount: input.num_clicks ?? 1
+    });
+    await this.waitForPage(session.page);
+    return { ok: true, mode: "local", url: session.page.url() };
+  }
+  async type(sessionId, input) {
+    const session = this.requireOpenSession(sessionId);
+    this.touch(session);
+    await session.page.keyboard.type(input.text, { delay: input.delay });
+    return { ok: true, mode: "local", url: session.page.url() };
+  }
+  async scroll(sessionId, input) {
+    const session = this.requireOpenSession(sessionId);
+    this.touch(session);
+    if (typeof input.x === "number" && typeof input.y === "number") {
+      await session.page.mouse.move(input.x, input.y);
+    }
+    await session.page.mouse.wheel((input.delta_x ?? 0) * 120, (input.delta_y ?? 5) * 120);
+    await session.page.waitForTimeout(150).catch(() => void 0);
+    return { ok: true, mode: "local", url: session.page.url() };
+  }
+  async press(sessionId, input) {
+    const session = this.requireOpenSession(sessionId);
+    this.touch(session);
+    for (const key of input.keys) {
+      await session.page.keyboard.press(normalizeKeyCombo(key));
+    }
+    await this.waitForPage(session.page);
+    return { ok: true, mode: "local", url: session.page.url() };
+  }
+  async close(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.status === "closed") {
+      return { ok: true, closed: true, already_closed: true, mode: "local" };
+    }
+    if (session.timeout) clearTimeout(session.timeout);
+    session.status = "closed";
+    session.closedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await session.page.close().catch(() => void 0);
+    await this.closeContextIfUnused(session.contextKey);
+    return { ok: true, closed: true, mode: "local" };
+  }
+  list(includeClosed = false) {
+    return Array.from(this.sessions.values()).filter((session) => includeClosed || session.status === "open").map(sessionSummary);
+  }
+  async resolveProfile(profile) {
+    const directDir = directProfileDir();
+    const requestedName = configuredProfileName(profile);
+    if (directDir && (!profile || requestedName === process.env.MCP_SCRAPER_BROWSER_PROFILE?.trim())) {
+      return {
+        name: requestedName,
+        userDataDir: directDir,
+        browserExecutablePath: process.env.MCP_SCRAPER_BROWSER_EXECUTABLE?.trim() || defaultChromeExecutablePath() || null,
+        manifest: null
+      };
+    }
+    const manifest = await loadImportedBrowserProfile(requestedName);
+    return {
+      name: manifest.name,
+      userDataDir: manifest.userDataDir,
+      browserExecutablePath: manifest.browserExecutablePath,
+      manifest
+    };
+  }
+  async ensureContext(profile) {
+    const existing = this.contexts.get(profile.userDataDir);
+    if (existing) return existing;
+    const executablePath = launchExecutablePath(profile);
+    const context = await chromium.launchPersistentContext(profile.userDataDir, {
+      headless: false,
+      viewport: { width: 1440, height: 900 },
+      acceptDownloads: true,
+      ...executablePath ? { executablePath } : {},
+      ...ignoreDefaultArgsFor(executablePath) ? { ignoreDefaultArgs: ignoreDefaultArgsFor(executablePath) } : {}
+    });
+    const state = { key: profile.userDataDir, context, profile };
+    context.on("close", () => {
+      this.contexts.delete(profile.userDataDir);
+      const closedAt = (/* @__PURE__ */ new Date()).toISOString();
+      for (const session of this.sessions.values()) {
+        if (session.contextKey === profile.userDataDir && session.status === "open") {
+          session.status = "closed";
+          session.closedAt = closedAt;
+          if (session.timeout) clearTimeout(session.timeout);
+        }
+      }
+    });
+    this.contexts.set(profile.userDataDir, state);
+    return state;
+  }
+  requireOpenSession(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.status !== "open") throw new Error(`Local browser session not found or closed: ${sessionId}`);
+    return session;
+  }
+  touch(session) {
+    session.lastActionAt = (/* @__PURE__ */ new Date()).toISOString();
+  }
+  hasOpenSessionForContext(contextKey) {
+    return Array.from(this.sessions.values()).some((session) => session.contextKey === contextKey && session.status === "open");
+  }
+  async closeContextIfUnused(contextKey) {
+    if (this.hasOpenSessionForContext(contextKey)) return;
+    const state = this.contexts.get(contextKey);
+    if (!state) return;
+    this.contexts.delete(contextKey);
+    await state.context.close().catch(() => void 0);
+  }
+  async waitForPage(page) {
+    await page.waitForLoadState("domcontentloaded", { timeout: 5e3 }).catch(() => void 0);
+    await page.waitForTimeout(200).catch(() => void 0);
+  }
+};
+
+// src/mcp/browser-agent-tool-schemas.ts
+import { z } from "zod";
+var NullableString = z.string().nullable();
+var BrowserRawObject = z.record(z.unknown());
+var BrowserElementOutput = z.record(z.unknown());
+var BrowserBaseOutput = {
+  ok: z.boolean().describe("Whether the browser-agent action succeeded."),
+  tool: z.string().describe("Browser Agent MCP tool that produced this response."),
+  session_id: NullableString.describe("Browser session id when the response is scoped to a session.")
+};
+var BrowserReplayBaseOutput = {
+  ...BrowserBaseOutput,
+  replay_id: NullableString.describe("Replay id when the response is scoped to a replay.")
+};
+var BrowserOpenInputSchema = {
+  label: z.string().optional().describe("Optional human label for this session, shown in the watch console."),
+  url: z.string().url().optional().describe("Optional URL to navigate to immediately after opening."),
+  profile: z.string().optional().describe("Optional saved profile name to load a logged-in session for a site."),
+  save_profile_changes: z.boolean().optional().describe("Persist cookies and local storage back to the named profile when the session is closed. Use this for profile setup or intentional auth refreshes; avoid parallel sessions writing to the same profile."),
+  timeout_seconds: z.number().int().min(60).max(259200).optional().describe("How long the session may live before auto-termination. Defaults to 600. The browser idles into a zero-cost standby between actions, so a longer timeout is cheap.")
+};
+var BrowserProfileListInputSchema = {
+  email: z.string().optional().describe("Optional Chrome account email or displayed profile name to filter for, for example seo@example.com."),
+  user_data_dir: z.string().optional().describe("Optional Chrome user data directory. Defaults to the current OS Chrome profile root.")
+};
+var BrowserProfileOnboardInputSchema = {
+  email: z.string().optional().describe("Optional local Chrome account email to find and convert into a suggested Kernel profile name."),
+  profile: z.string().optional().describe("Optional Kernel browser profile name to create/load. If omitted, email is used to derive one."),
+  user_data_dir: z.string().optional().describe("Optional Chrome user data directory for email lookup. Defaults to the current OS Chrome profile root."),
+  url: z.string().url().optional().describe("Setup URL to open after creating the browser. Defaults to https://accounts.google.com/."),
+  label: z.string().optional().describe("Optional human label for this setup session."),
+  timeout_seconds: z.number().int().min(60).max(259200).optional().describe("How long the setup session may live before auto-termination. Defaults to 600.")
+};
+var BrowserProfileImportInputSchema = {
+  email: z.string().optional().describe("Optional Chrome account email or displayed profile name to select from Chrome Local State."),
+  name: z.string().optional().describe("Name for the managed MCP Scraper browser profile. Defaults to a slug derived from the selected Chrome account."),
+  chrome_profile_directory: z.string().optional().describe("Optional Chrome profile directory to import, for example Default or Profile 1."),
+  user_data_dir: z.string().optional().describe("Optional source Chrome user data directory. Defaults to the current OS Chrome profile root."),
+  output_dir: z.string().optional().describe("Optional managed profile base directory. Defaults to ~/.mcp-scraper/browser-profiles."),
+  browser_executable_path: z.string().optional().describe("Optional Chrome executable path for local browser launches. Defaults to the installed Google Chrome path when found."),
+  overwrite: z.boolean().default(false).describe("Overwrite an existing managed profile clone with the same name.")
+};
+var BrowserProfileSyncInputSchema = {
+  name: z.string().describe("Managed MCP Scraper browser profile name to refresh from its recorded source Chrome profile."),
+  output_dir: z.string().optional().describe("Optional managed profile base directory. Defaults to ~/.mcp-scraper/browser-profiles."),
+  browser_executable_path: z.string().optional().describe("Optional Chrome executable path to store in the refreshed profile manifest.")
+};
+var BrowserSessionInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself.")
+};
+var BrowserLocateTargetSchema = z.object({
+  name: z.string().optional().describe("Optional label for this target, echoed in the result."),
+  selector: z.string().optional().describe('CSS selector for the exact DOM element to locate, for example h1, input[name="q"], or [data-testid="result"].'),
+  text: z.string().optional().describe("Visible text to locate when a selector is not known. The tool returns the text range bounds when possible."),
+  match: z.enum(["contains", "exact"]).default("contains").describe("How to match text targets. Defaults to contains."),
+  index: z.number().int().min(0).default(0).describe("Zero-based match index when multiple elements match.")
+}).refine((value) => Boolean(value.selector || value.text), {
+  message: "target requires selector or text"
+});
+var BrowserLocateInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  targets: z.array(BrowserLocateTargetSchema).min(1).max(20).describe("DOM targets to locate in the current viewport. Use selectors for exact elements, or text for visible text ranges.")
+};
+var BrowserGotoInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  url: z.string().url().describe("URL to navigate the browser to.")
+};
+var BrowserClickInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  x: z.number().describe("X coordinate to click, in screenshot pixels. Use only coordinates from the latest browser_screenshot, browser_read, or browser_locate result; do not guess."),
+  y: z.number().describe("Y coordinate to click, in screenshot pixels. Use only coordinates from the latest browser_screenshot, browser_read, or browser_locate result; do not guess."),
+  button: z.enum(["left", "right", "middle"]).default("left").describe("Mouse button."),
+  num_clicks: z.number().int().min(1).max(3).optional().describe("Number of clicks, e.g. 2 for double-click.")
+};
+var BrowserTypeInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  text: z.string().describe("Text to type at the current focus. Click a field first to focus it."),
+  delay: z.number().int().min(0).max(500).optional().describe("Optional per-keystroke delay in ms for human-like typing.")
+};
+var BrowserScrollInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  delta_y: z.number().default(5).describe("Vertical scroll in wheel units. Positive scrolls down, negative up."),
+  delta_x: z.number().default(0).describe("Horizontal scroll in wheel units."),
+  x: z.number().optional().describe("X position to scroll at. Defaults to screen center."),
+  y: z.number().optional().describe("Y position to scroll at. Defaults to screen center.")
+};
+var BrowserPressInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  keys: z.array(z.string()).min(1).describe('Keys or combinations to press, e.g. ["Return"], ["Ctrl+a"], ["Ctrl+Shift+Tab"].')
+};
+var BrowserReplayStopInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  replay_id: z.string().describe("The replay id returned by browser_replay_start or browser_list_replays. Use only a returned replay_id; do not construct one yourself.")
+};
+var BrowserReplayDownloadInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  replay_id: z.string().describe("The replay id returned by browser_replay_start or browser_list_replays. Use only a returned replay_id; do not construct one yourself."),
+  filename: z.string().optional().describe("Optional local MP4 filename. Defaults to a timestamped replay filename.")
+};
+var BrowserReplayAnnotationSchema = z.object({
+  type: z.enum(["box", "circle", "underline", "arrow", "label"]).default("box").describe("Annotation style to draw over the replay."),
+  start_seconds: z.number().min(0).default(0).describe("When the annotation should appear in the replay."),
+  end_seconds: z.number().min(0).optional().describe("When the annotation should disappear. Defaults to two seconds after start_seconds."),
+  left: z.number().optional().describe("Target left edge in browser screenshot pixels. Use element.left from browser_screenshot/browser_read."),
+  top: z.number().optional().describe("Target top edge in browser screenshot pixels. Use element.top from browser_screenshot/browser_read."),
+  width: z.number().positive().optional().describe("Target width in browser screenshot pixels. Use element.width from browser_screenshot/browser_read."),
+  height: z.number().positive().optional().describe("Target height in browser screenshot pixels. Use element.height from browser_screenshot/browser_read."),
+  x: z.number().optional().describe("Point target x coordinate in browser screenshot pixels when no box is available."),
+  y: z.number().optional().describe("Point target y coordinate in browser screenshot pixels when no box is available."),
+  from_x: z.number().optional().describe("Arrow start x coordinate in browser screenshot pixels. Defaults near the target."),
+  from_y: z.number().optional().describe("Arrow start y coordinate in browser screenshot pixels. Defaults near the target."),
+  to_x: z.number().optional().describe("Arrow target x coordinate in browser screenshot pixels. Defaults to the target box center."),
+  to_y: z.number().optional().describe("Arrow target y coordinate in browser screenshot pixels. Defaults to the target box center."),
+  label: z.string().max(120).optional().describe("Optional text callout to render near the annotation."),
+  color: z.string().regex(/^#?[0-9a-fA-F]{6}$/).optional().describe("Annotation color as hex, for example #ff3b30."),
+  thickness: z.number().min(1).max(24).optional().describe("Stroke thickness in pixels. Defaults to 5.")
+});
+var BrowserReplayMarkInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself. A replay must already be recording."),
+  target: BrowserLocateTargetSchema.describe("The exact DOM element or text range to mark in the current viewport."),
+  type: z.enum(["box", "circle", "underline", "arrow"]).default("box").describe("Annotation style to generate. Labels are included on the returned annotation when label is provided."),
+  label: z.string().max(120).optional().describe("Optional callout text to render near the target."),
+  color: z.string().regex(/^#?[0-9a-fA-F]{6}$/).optional().describe("Annotation color as hex, for example #ff3b30."),
+  thickness: z.number().min(1).max(24).optional().describe("Stroke thickness in pixels. Defaults to 5."),
+  padding: z.number().min(0).max(80).default(8).describe("Pixels to expand the DOM bounds so the highlight does not touch the text edge."),
+  start_offset_seconds: z.number().min(-5).max(10).default(-0.25).describe("Offset from the current replay time. Negative values make the callout appear just before the mark action is captured."),
+  duration_seconds: z.number().min(0.5).max(30).default(4).describe("How long the generated annotation should remain visible.")
+};
+var BrowserReplayAnnotateInputSchema = {
+  session_id: z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  replay_id: z.string().describe("The replay id returned by browser_replay_start or browser_list_replays. Use only a returned replay_id; do not construct one yourself."),
+  annotations: z.array(BrowserReplayAnnotationSchema).min(1).max(50).describe("Timed overlay annotations to render on the replay. Prefer annotations returned by browser_replay_mark; otherwise use exact DOM bounds from browser_locate/browser_screenshot/browser_read."),
+  filename: z.string().optional().describe("Optional output MP4 filename. Defaults to a timestamped annotated replay filename."),
+  source_width: z.number().positive().optional().describe("Width of the screenshot coordinate space used for annotations. Defaults to the replay video width."),
+  source_height: z.number().positive().optional().describe("Height of the coordinate space used for annotations. When this is a page viewport height smaller than the replay video height, the annotator infers the browser chrome top offset."),
+  source_left_offset: z.number().min(0).optional().describe("Optional explicit X offset from annotation coordinates to replay video coordinates. Usually omitted."),
+  source_top_offset: z.number().min(0).optional().describe("Optional explicit Y offset from annotation coordinates to replay video coordinates. Usually omitted because browser chrome offset is inferred when source_height is a page viewport height.")
+};
+var BrowserListInputSchema = {
+  include_closed: z.boolean().default(false).describe("Include closed sessions in the list.")
+};
+var BrowserOpenOutputSchema = {
+  ok: z.boolean(),
+  tool: z.literal("browser_open"),
+  session_id: z.string().describe("Session id returned by browser_open. Use only this exact value in later browser_* calls; do not construct one yourself."),
+  watch_url: z.string().describe("Human watch/takeover URL for this browser session."),
+  live_view_url: NullableString.describe("Raw live-view URL from the browser service when available."),
+  url: NullableString.describe("Initial URL requested by the caller, when provided."),
+  hint: z.string(),
+  raw: BrowserRawObject.optional()
+};
+var BrowserProfileListOutputSchema = {
+  ok: z.boolean(),
+  tool: z.literal("browser_profile_list"),
+  session_id: z.null(),
+  profiles: z.array(BrowserRawObject),
+  count: z.number().int().min(0),
+  hint: z.string()
+};
+var BrowserProfileOnboardOutputSchema = {
+  ok: z.boolean(),
+  tool: z.literal("browser_profile_onboard"),
+  session_id: z.string(),
+  watch_url: z.string(),
+  live_view_url: NullableString,
+  profile: z.string(),
+  setup_url: z.string(),
+  chrome_profile: BrowserRawObject.nullable(),
+  next_steps: z.array(z.string()),
+  raw: BrowserRawObject.optional()
+};
+var BrowserProfileImportOutputSchema = {
+  ok: z.boolean(),
+  tool: z.literal("browser_profile_import"),
+  session_id: z.null(),
+  profile: BrowserRawObject,
+  source_profile: BrowserRawObject,
+  next_steps: z.array(z.string()),
+  hint: z.string()
+};
+var BrowserProfileSyncOutputSchema = {
+  ok: z.boolean(),
+  tool: z.literal("browser_profile_sync"),
+  session_id: z.null(),
+  profile: BrowserRawObject,
+  source_profile: BrowserRawObject,
+  hint: z.string()
+};
+var BrowserScreenshotOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: z.literal("browser_screenshot"),
+  url: NullableString,
+  title: NullableString,
+  text: z.string(),
+  elements: z.array(BrowserElementOutput),
+  screenshot: z.object({
+    mime_type: z.string(),
+    inline: z.boolean()
+  }).nullable()
+};
+var BrowserReadOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: z.literal("browser_read"),
+  url: NullableString,
+  title: NullableString,
+  text: z.string(),
+  elements: z.array(BrowserElementOutput),
+  raw: BrowserRawObject.optional()
+};
+var BrowserLocateOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: z.literal("browser_locate"),
+  url: NullableString,
+  title: NullableString,
+  viewport: BrowserRawObject.nullable(),
+  replay: BrowserRawObject.nullable(),
+  targets: z.array(BrowserRawObject),
+  raw: BrowserRawObject.optional()
+};
+var BrowserActionOutputSchema = {
+  ...BrowserBaseOutput,
+  result: BrowserRawObject.describe("Provider action result. Check ok and follow with browser_screenshot/browser_read when page state matters."),
+  nextRecommendedTool: z.string().nullable()
+};
+var BrowserReplayStartOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: z.literal("browser_replay_start"),
+  view_url: NullableString,
+  download_url: NullableString,
+  raw: BrowserRawObject.optional()
+};
+var BrowserReplayStopOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: z.literal("browser_replay_stop"),
+  view_url: NullableString,
+  download_url: NullableString,
+  raw: BrowserRawObject.optional()
+};
+var BrowserListReplaysOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: z.literal("browser_list_replays"),
+  replays: z.array(BrowserRawObject),
+  count: z.number().int().min(0)
+};
+var BrowserReplayDownloadOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: z.literal("browser_replay_download"),
+  file_path: NullableString,
+  bytes: z.number().int().min(0).nullable(),
+  mime_type: NullableString,
+  download_url: NullableString
+};
+var BrowserReplayMarkOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: z.literal("browser_replay_mark"),
+  annotation: BrowserRawObject,
+  source_width: z.number().nullable(),
+  source_height: z.number().nullable(),
+  target: BrowserRawObject.nullable(),
+  hint: z.string()
+};
+var BrowserReplayAnnotateOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: z.literal("browser_replay_annotate"),
+  source_file_path: NullableString,
+  annotated_file_path: NullableString,
+  bytes: z.number().int().min(0).nullable(),
+  width: z.number().int().min(0).nullable(),
+  height: z.number().int().min(0).nullable(),
+  annotation_count: z.number().int().min(0).nullable(),
+  mime_type: NullableString
+};
+var BrowserCloseOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: z.literal("browser_close"),
+  closed: z.boolean(),
+  raw: BrowserRawObject.optional()
+};
+var BrowserListSessionsOutputSchema = {
+  ok: z.boolean(),
+  tool: z.literal("browser_list_sessions"),
+  session_id: z.null(),
+  sessions: z.array(BrowserRawObject),
+  count: z.number().int().min(0)
+};
+
+// src/mcp/replay-annotator.ts
+import { execFile } from "child_process";
+import { mkdtemp, rm, stat, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function formatAssTime(seconds) {
+  const safe = Math.max(0, seconds);
+  const hours = Math.floor(safe / 3600);
+  const minutes = Math.floor(safe % 3600 / 60);
+  const wholeSeconds = Math.floor(safe % 60);
+  const centiseconds = Math.floor((safe - Math.floor(safe)) * 100);
+  return `${hours}:${String(minutes).padStart(2, "0")}:${String(wholeSeconds).padStart(2, "0")}.${String(centiseconds).padStart(2, "0")}`;
+}
+function cssHexToAssColor(color) {
+  const normalized = color?.trim().match(/^#?([0-9a-fA-F]{6})$/)?.[1] ?? "ff3b30";
+  const red = normalized.slice(0, 2);
+  const green = normalized.slice(2, 4);
+  const blue = normalized.slice(4, 6);
+  return `&H${blue}${green}${red}&`;
+}
+function escapeAssText(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\{/g, "\\{").replace(/\}/g, "\\}").replace(/\r?\n/g, "\\N");
+}
+function resolveCoordinateTransform(video, source, options) {
+  const explicitOffsetX = finiteNumber(options.sourceLeftOffset) ? options.sourceLeftOffset : null;
+  const explicitOffsetY = finiteNumber(options.sourceTopOffset) ? options.sourceTopOffset : null;
+  const inferredTopOffset = explicitOffsetY == null && Math.round(source.width) === Math.round(video.width) && source.height < video.height && video.height - source.height <= 220 ? video.height - source.height : 0;
+  const offsetX = explicitOffsetX ?? 0;
+  const offsetY = explicitOffsetY ?? inferredTopOffset;
+  return {
+    scaleX: (video.width - offsetX) / source.width,
+    scaleY: (video.height - offsetY) / source.height,
+    offsetX,
+    offsetY
+  };
+}
+function transformPoint(x, y, transform) {
+  return {
+    x: x * transform.scaleX + transform.offsetX,
+    y: y * transform.scaleY + transform.offsetY
+  };
+}
+function scaleRect(annotation, transform) {
+  if (finiteNumber(annotation.left) && finiteNumber(annotation.top) && finiteNumber(annotation.width) && finiteNumber(annotation.height)) {
+    const origin = transformPoint(annotation.left, annotation.top, transform);
+    return {
+      left: origin.x,
+      top: origin.y,
+      width: annotation.width * transform.scaleX,
+      height: annotation.height * transform.scaleY
+    };
+  }
+  if (finiteNumber(annotation.x) && finiteNumber(annotation.y)) {
+    const radius = finiteNumber(annotation.width) ? annotation.width / 2 : 28;
+    const point = transformPoint(annotation.x, annotation.y, transform);
+    return {
+      left: point.x - radius * transform.scaleX,
+      top: point.y - radius * transform.scaleY,
+      width: radius * 2 * transform.scaleX,
+      height: radius * 2 * transform.scaleY
+    };
+  }
+  throw new Error("annotation needs either left/top/width/height or x/y");
+}
+function rectPath(rect) {
+  const x1 = Math.round(rect.left);
+  const y1 = Math.round(rect.top);
+  const x2 = Math.round(rect.left + rect.width);
+  const y2 = Math.round(rect.top + rect.height);
+  return `m ${x1} ${y1} l ${x2} ${y1} l ${x2} ${y2} l ${x1} ${y2} l ${x1} ${y1}`;
+}
+function ellipsePath(rect) {
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+  const rx = Math.max(4, rect.width / 2);
+  const ry = Math.max(4, rect.height / 2);
+  const points = [];
+  for (let i = 0; i <= 32; i += 1) {
+    const t = Math.PI * 2 * i / 32;
+    const x = Math.round(cx + Math.cos(t) * rx);
+    const y = Math.round(cy + Math.sin(t) * ry);
+    points.push(`${i === 0 ? "m" : "l"} ${x} ${y}`);
+  }
+  return points.join(" ");
+}
+function filledRectPath(left, top, width, height) {
+  return rectPath({ left, top, width, height });
+}
+function arrowPath(fromX, fromY, toX, toY, thickness) {
+  const dx = toX - fromX;
+  const dy = toY - fromY;
+  const length = Math.max(1, Math.hypot(dx, dy));
+  const ux = dx / length;
+  const uy = dy / length;
+  const px = -uy;
+  const py = ux;
+  const half = thickness / 2;
+  const head = Math.max(14, thickness * 4);
+  const baseX = toX - ux * head;
+  const baseY = toY - uy * head;
+  const p1x = Math.round(fromX + px * half);
+  const p1y = Math.round(fromY + py * half);
+  const p2x = Math.round(baseX + px * half);
+  const p2y = Math.round(baseY + py * half);
+  const p3x = Math.round(baseX + px * head * 0.55);
+  const p3y = Math.round(baseY + py * head * 0.55);
+  const p4x = Math.round(toX);
+  const p4y = Math.round(toY);
+  const p5x = Math.round(baseX - px * head * 0.55);
+  const p5y = Math.round(baseY - py * head * 0.55);
+  const p6x = Math.round(baseX - px * half);
+  const p6y = Math.round(baseY - py * half);
+  const p7x = Math.round(fromX - px * half);
+  const p7y = Math.round(fromY - py * half);
+  return `m ${p1x} ${p1y} l ${p2x} ${p2y} l ${p3x} ${p3y} l ${p4x} ${p4y} l ${p5x} ${p5y} l ${p6x} ${p6y} l ${p7x} ${p7y} l ${p1x} ${p1y}`;
+}
+function eventLine(start, end, body) {
+  return `Dialogue: 0,${formatAssTime(start)},${formatAssTime(end)},Default,,0,0,0,,${body}`;
+}
+function labelLine(start, end, x, y, label) {
+  const safeX = Math.round(x);
+  const safeY = Math.round(y);
+  return eventLine(
+    start,
+    end,
+    `{\\an7\\pos(${safeX},${safeY})\\fs30\\bord4\\shad0\\c&HFFFFFF&\\3c&H000000&}${escapeAssText(label)}`
+  );
+}
+function shapeLine(start, end, path, color, thickness, filled = false) {
+  const fillAlpha = filled ? "&H00&" : "&HFF&";
+  const border = filled ? 0 : thickness;
+  return eventLine(
+    start,
+    end,
+    `{\\an7\\pos(0,0)\\p1\\bord${border}\\shad0\\1a${fillAlpha}\\1c${color}\\3c${color}}${path}`
+  );
+}
+function buildAssSubtitle(options, video) {
+  const source = {
+    width: options.sourceWidth && options.sourceWidth > 0 ? options.sourceWidth : video.width,
+    height: options.sourceHeight && options.sourceHeight > 0 ? options.sourceHeight : video.height
+  };
+  const transform = resolveCoordinateTransform(video, source, options);
+  const lines = [];
+  for (const annotation of options.annotations) {
+    const start = Math.max(0, annotation.start_seconds ?? 0);
+    const end = annotation.end_seconds && annotation.end_seconds > start ? annotation.end_seconds : start + 2;
+    const type = annotation.type ?? "box";
+    const color = cssHexToAssColor(annotation.color);
+    const thickness = Math.round(clamp(annotation.thickness ?? 5, 2, 24));
+    if (type === "label") {
+      if (!annotation.label) throw new Error("label annotation needs label");
+      const rect2 = scaleRect(annotation, transform);
+      lines.push(labelLine(start, end, rect2.left, Math.max(8, rect2.top), annotation.label));
+      continue;
+    }
+    if (type === "arrow") {
+      const rect2 = finiteNumber(annotation.to_x) && finiteNumber(annotation.to_y) ? null : scaleRect(annotation, transform);
+      const toPoint = finiteNumber(annotation.to_x) && finiteNumber(annotation.to_y) ? transformPoint(annotation.to_x, annotation.to_y, transform) : null;
+      const toX = toPoint ? toPoint.x : rect2.left + rect2.width / 2;
+      const toY = toPoint ? toPoint.y : rect2.top + rect2.height / 2;
+      const fromPoint = finiteNumber(annotation.from_x) && finiteNumber(annotation.from_y) ? transformPoint(annotation.from_x, annotation.from_y, transform) : null;
+      const fromX = fromPoint ? fromPoint.x : clamp(toX - 120, 12, video.width - 12);
+      const fromY = fromPoint ? fromPoint.y : clamp(toY - 90, 12, video.height - 12);
+      lines.push(shapeLine(start, end, arrowPath(fromX, fromY, toX, toY, thickness), color, thickness, true));
+      if (annotation.label) lines.push(labelLine(start, end, fromX + 8, Math.max(96, fromY - 36), annotation.label));
+      continue;
+    }
+    const rect = scaleRect(annotation, transform);
+    if (type === "underline") {
+      const underlineTop = rect.top + rect.height + thickness;
+      lines.push(shapeLine(start, end, filledRectPath(rect.left, underlineTop, rect.width, thickness), color, 0, true));
+    } else if (type === "circle") {
+      lines.push(shapeLine(start, end, ellipsePath(rect), color, thickness));
+    } else {
+      lines.push(shapeLine(start, end, rectPath(rect), color, thickness));
+    }
+    if (annotation.label) lines.push(labelLine(start, end, rect.left, Math.max(8, rect.top - 38), annotation.label));
+  }
+  return [
+    "[Script Info]",
+    "ScriptType: v4.00+",
+    `PlayResX: ${Math.round(video.width)}`,
+    `PlayResY: ${Math.round(video.height)}`,
+    "ScaledBorderAndShadow: yes",
+    "",
+    "[V4+ Styles]",
+    "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
+    "Style: Default,Arial,30,&H00FFFFFF,&H000000FF,&H00000000,&H90000000,0,0,0,0,100,100,0,0,1,2,0,7,0,0,0,1",
+    "",
+    "[Events]",
+    "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
+    ...lines,
+    ""
+  ].join("\n");
+}
+async function videoSize(inputFilePath) {
+  const { stdout } = await execFileAsync("ffprobe", [
+    "-v",
+    "error",
+    "-select_streams",
+    "v:0",
+    "-show_entries",
+    "stream=width,height",
+    "-of",
+    "json",
+    inputFilePath
+  ], { maxBuffer: 1024 * 1024 });
+  const parsed = JSON.parse(stdout);
+  const stream = parsed.streams?.[0];
+  if (!stream?.width || !stream.height) throw new Error("could not read replay video dimensions");
+  return { width: stream.width, height: stream.height };
+}
+function ffmpegFilterPath(path) {
+  return path.replace(/\\/g, "\\\\").replace(/:/g, "\\:");
+}
+async function annotateReplayVideo(inputFilePath, outputFilePath, options) {
+  if (!options.annotations.length) throw new Error("annotations must include at least one item");
+  const size = await videoSize(inputFilePath);
+  const tmp = await mkdtemp(join(tmpdir(), "mcp-scraper-ass-"));
+  const assPath = join(tmp, "annotations.ass");
+  try {
+    await writeFile(assPath, buildAssSubtitle(options, size), "utf8");
+    await execFileAsync("ffmpeg", [
+      "-y",
+      "-i",
+      inputFilePath,
+      "-vf",
+      `ass=${ffmpegFilterPath(assPath)}`,
+      "-c:v",
+      "libx264",
+      "-pix_fmt",
+      "yuv420p",
+      "-movflags",
+      "+faststart",
+      "-c:a",
+      "copy",
+      outputFilePath
+    ], { maxBuffer: 1024 * 1024 * 20 });
+    const out = await stat(outputFilePath);
+    return {
+      filePath: outputFilePath,
+      bytes: out.size,
+      width: size.width,
+      height: size.height,
+      annotationCount: options.annotations.length
+    };
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+}
+
+// src/mcp/browser-agent-mcp-server.ts
+function structuredResult(value, isError = false) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value) }],
+    structuredContent: value,
+    isError
+  };
+}
+function errorMessage(value) {
+  if (value && typeof value === "object") {
+    const data = value;
+    if (typeof data.error === "string") return data.error;
+    if (typeof data.message === "string") return data.message;
+  }
+  return typeof value === "string" ? value : "Browser Agent request failed";
+}
+function errorResult(tool, value, sessionId = null, replayId = null) {
+  return structuredResult({
+    ok: false,
+    tool,
+    session_id: sessionId,
+    ...replayId !== null ? { replay_id: replayId } : {},
+    error: errorMessage(value),
+    raw: value && typeof value === "object" ? value : { value }
+  }, true);
+}
+function actionResult(tool, sessionId, ok, data, nextRecommendedTool = "browser_screenshot") {
+  if (!ok) return errorResult(tool, data, sessionId);
+  return structuredResult({
+    ok: true,
+    tool,
+    session_id: sessionId,
+    result: data && typeof data === "object" ? data : { value: data },
+    nextRecommendedTool
+  });
+}
+function outputBaseDir() {
+  return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || join2(homedir(), "Downloads", "mcp-scraper");
+}
+function safeFilePart(value) {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120) || "replay";
+}
+function replayFilePath(sessionId, replayId, filename) {
+  const requested = filename?.trim();
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const name = requested ? safeFilePart(requested).replace(/\.mp4$/i, "") : `${stamp}-${safeFilePart(sessionId)}-${safeFilePart(replayId)}`;
+  return join2(outputBaseDir(), "browser-replays", `${name}.mp4`);
+}
+function annotatedReplayFilePath(sessionId, replayId, filename) {
+  const requested = filename?.trim();
+  if (requested) return replayFilePath(sessionId, replayId, requested);
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  return replayFilePath(sessionId, replayId, `${stamp}-${safeFilePart(sessionId)}-${safeFilePart(replayId)}-annotated`);
+}
+function finiteNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function expandElementBounds(element, viewport, padding) {
+  const sourceWidth = finiteNumber2(viewport?.width) && viewport.width > 0 ? viewport.width : 1920;
+  const sourceHeight = finiteNumber2(viewport?.height) && viewport.height > 0 ? viewport.height : 1080;
+  const left = Math.max(0, element.left - padding);
+  const top = Math.max(0, element.top - padding);
+  const right = Math.min(sourceWidth, element.left + element.width + padding);
+  const bottom = Math.min(sourceHeight, element.top + element.height + padding);
+  return {
+    left,
+    top,
+    width: Math.max(1, right - left),
+    height: Math.max(1, bottom - top),
+    sourceWidth,
+    sourceHeight
+  };
+}
+function buildBrowserAgentMcpServer(opts) {
+  const server = new McpServer({ name: "browser-agent", version: PACKAGE_VERSION });
+  registerBrowserAgentMcpTools(server, opts);
+  return server;
+}
+function registerBrowserAgentMcpTools(server, opts) {
+  const baseUrl = opts.baseUrl.replace(/\/$/, "");
+  const consoleBase = (opts.consoleBaseUrl ?? opts.baseUrl).replace(/\/$/, "");
+  const timeoutMs = opts.timeoutMs ?? 9e4;
+  const localBrowser = new LocalBrowserAgentService();
+  async function req(method, path, body) {
+    try {
+      const res = await fetch(`${baseUrl}${path}`, {
+        method,
+        headers: { "Content-Type": "application/json", "x-api-key": opts.apiKey },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      const data = await res.json().catch(() => ({}));
+      return { ok: res.ok, data };
+    } catch (err) {
+      return { ok: false, data: { error: err instanceof Error ? err.message : String(err) } };
+    }
+  }
+  async function downloadReplay(sessionId, replayId, filename) {
+    const path = `/agent/sessions/${encodeURIComponent(sessionId)}/replays/${encodeURIComponent(replayId)}/download`;
+    try {
+      const res = await fetch(`${baseUrl}${path}`, {
+        method: "GET",
+        headers: { "x-api-key": opts.apiKey },
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(async () => ({ error: await res.text().catch(() => `HTTP ${res.status}`) }));
+        return { ok: false, data };
+      }
+      const bytes = Buffer.from(await res.arrayBuffer());
+      const filePath = replayFilePath(sessionId, replayId, filename);
+      mkdirSync(join2(outputBaseDir(), "browser-replays"), { recursive: true });
+      writeFileSync(filePath, bytes);
+      return {
+        ok: true,
+        data: {
+          replay_id: replayId,
+          file_path: filePath,
+          bytes: bytes.length,
+          mime_type: res.headers.get("content-type") ?? "video/mp4",
+          download_url: `${baseUrl}${path}`
+        }
+      };
+    } catch (err) {
+      return { ok: false, data: { error: err instanceof Error ? err.message : String(err) } };
+    }
+  }
+  const annotations = (title, readOnly = false) => ({
+    title,
+    readOnlyHint: readOnly,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  });
+  function selectChromeProfile(matches, email) {
+    const wanted = email?.trim().toLowerCase();
+    if (!wanted) return matches[0] ?? null;
+    return matches.find((profile) => profile.email.toLowerCase() === wanted) ?? matches[0] ?? null;
+  }
+  function localReplayUnsupported(tool, sessionId = null, replayId = null) {
+    return errorResult(tool, {
+      error: "Local browser mode does not support replay recording yet. Use hosted mode for browser_replay_* tools.",
+      mode: "local"
+    }, sessionId, replayId);
+  }
+  server.registerTool(
+    "browser_profile_list",
+    {
+      title: "List Local Chrome Profiles",
+      description: "List local Chrome profile metadata visible to this MCP server: account email, Chrome profile directory, local path, and a suggested managed browser profile name. This reads Chrome Local State only; it does not read cookies, passwords, browsing history, or copy local browser state. Use browser_profile_import when the user wants MCP Scraper to clone a local Chrome profile for local browser mode.",
+      inputSchema: BrowserProfileListInputSchema,
+      outputSchema: BrowserProfileListOutputSchema,
+      annotations: annotations("List Local Chrome Profiles", true)
+    },
+    async (input) => {
+      try {
+        const profiles = await listLocalChromeProfiles(input.user_data_dir, input.email);
+        return structuredResult({
+          ok: true,
+          tool: "browser_profile_list",
+          session_id: null,
+          profiles,
+          count: profiles.length,
+          hint: "Use browser_profile_import to clone one profile for local mode. Use browser_profile_onboard only for hosted Kernel profile setup."
+        });
+      } catch (err) {
+        return errorResult("browser_profile_list", { error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+  );
+  server.registerTool(
+    "browser_profile_import",
+    {
+      title: "Import Local Chrome Profile",
+      description: "Clone one local Chrome profile into MCP Scraper managed storage for local browser mode. This copies browser state files such as cookies, history, local storage, session storage, and password database metadata into ~/.mcp-scraper/browser-profiles by default; it skips cache and lock files and never prints cookie or password values. Use this when the user wants browser_open to run locally with their existing logged-in Chrome state.",
+      inputSchema: BrowserProfileImportInputSchema,
+      outputSchema: BrowserProfileImportOutputSchema,
+      annotations: { title: "Import Local Chrome Profile", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    async (input) => {
+      try {
+        const result = await importChromeProfile({
+          email: input.email,
+          name: input.name,
+          chromeProfileDirectory: input.chrome_profile_directory,
+          sourceUserDataDir: input.user_data_dir,
+          outputDir: input.output_dir,
+          overwrite: input.overwrite,
+          browserExecutablePath: input.browser_executable_path
+        });
+        return structuredResult({
+          ok: true,
+          tool: "browser_profile_import",
+          session_id: null,
+          profile: result.profile,
+          source_profile: result.sourceProfile,
+          next_steps: [
+            `Set MCP_SCRAPER_BROWSER_MODE=local in the MCP server config.`,
+            `Set MCP_SCRAPER_BROWSER_PROFILE=${result.profile.name}.`,
+            "Restart the MCP client so it starts the local browser mode process.",
+            "Call browser_open with the same MCP server; it will open a local Chrome window using the cloned profile."
+          ],
+          hint: "The clone is local to this machine. Re-run browser_profile_sync after logging into new sites in normal Chrome."
+        });
+      } catch (err) {
+        return errorResult("browser_profile_import", { error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+  );
+  server.registerTool(
+    "browser_profile_sync",
+    {
+      title: "Sync Local Chrome Profile",
+      description: "Refresh an existing MCP Scraper managed local browser profile from the source Chrome profile recorded in its manifest. This overwrites the managed clone, copies browser state files again, skips cache and lock files, and never prints cookie or password values.",
+      inputSchema: BrowserProfileSyncInputSchema,
+      outputSchema: BrowserProfileSyncOutputSchema,
+      annotations: { title: "Sync Local Chrome Profile", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    async (input) => {
+      try {
+        const result = await syncImportedChromeProfile(input.name, {
+          outputDir: input.output_dir,
+          browserExecutablePath: input.browser_executable_path
+        });
+        return structuredResult({
+          ok: true,
+          tool: "browser_profile_sync",
+          session_id: null,
+          profile: result.profile,
+          source_profile: result.sourceProfile,
+          hint: `Refreshed ${result.profile.name}. Restart local browser sessions that were using this profile.`
+        });
+      } catch (err) {
+        return errorResult("browser_profile_sync", { error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+  );
+  server.registerTool(
+    "browser_profile_onboard",
+    {
+      title: "Onboard Hosted Browser Profile",
+      description: "Create or load a saved hosted Kernel browser profile and open a live setup browser with profile saving enabled. Use this only for hosted browser mode. If email is provided, the tool reads local Chrome profile metadata only to suggest the Kernel profile name; it does not import local cookies. For local browser mode with real Chrome state, use browser_profile_import instead.",
+      inputSchema: BrowserProfileOnboardInputSchema,
+      outputSchema: BrowserProfileOnboardOutputSchema,
+      annotations: annotations("Onboard Hosted Browser Profile")
+    },
+    async (input) => {
+      let chromeProfile = null;
+      if (input.email) {
+        try {
+          chromeProfile = selectChromeProfile(await listLocalChromeProfiles(input.user_data_dir, input.email), input.email);
+        } catch (err) {
+          return errorResult("browser_profile_onboard", { error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+      const profile = input.profile?.trim() || chromeProfile?.recommendedKernelProfileName || browserServiceProfileName();
+      if (!profile) {
+        return errorResult("browser_profile_onboard", {
+          error: "profile is required when no email match or BROWSER_AGENT_PROFILE_NAME is available"
+        });
+      }
+      const setupUrl = input.url ?? "https://accounts.google.com/";
+      const open = await req("POST", "/agent/sessions", {
+        label: input.label ?? `Profile setup: ${profile}`,
+        profile,
+        save_profile_changes: true,
+        timeout_seconds: input.timeout_seconds
+      });
+      if (!open.ok) return errorResult("browser_profile_onboard", open.data);
+      const session = open.data;
+      const goto = await req("POST", `/agent/sessions/${session.session_id}/goto`, { url: setupUrl });
+      if (!goto.ok) return errorResult("browser_profile_onboard", goto.data, session.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_profile_onboard",
+        session_id: session.session_id,
+        watch_url: `${consoleBase}/console/${session.session_id}`,
+        live_view_url: session.live_view_url ?? null,
+        profile,
+        setup_url: setupUrl,
+        chrome_profile: chromeProfile,
+        next_steps: [
+          "Open the watch_url and complete the login manually.",
+          "After login is complete, call browser_close with this session_id to persist cookies and local storage to the Kernel profile.",
+          "Use BROWSER_AGENT_PROFILE_NAME or browser_open.profile with this profile name for future authenticated sessions."
+        ],
+        raw: session
+      });
+    }
+  );
+  server.registerTool(
+    "browser_open",
+    {
+      title: "Open Browser Session",
+      description: "Open a browser you can drive. By default this creates a hosted cloud browser with a watch_url; when MCP_SCRAPER_BROWSER_MODE=local it opens a local Google Chrome window against an imported MCP Scraper Chrome profile. Returns a session_id used by all other browser_* tools. In hosted mode, anti-bot stealth and automatic CAPTCHA/Cloudflare solving are on by default. Call browser_close when done.",
+      inputSchema: BrowserOpenInputSchema,
+      outputSchema: BrowserOpenOutputSchema,
+      annotations: annotations("Open Browser Session")
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        try {
+          const session2 = await localBrowser.open(input);
+          return structuredResult({
+            ok: true,
+            tool: "browser_open",
+            session_id: session2.session_id,
+            watch_url: session2.watch_url,
+            live_view_url: null,
+            url: input.url ?? null,
+            hint: "Local Chrome is open on this machine. Call browser_screenshot to see the page and click by x,y coordinates.",
+            raw: session2
+          });
+        } catch (err) {
+          return errorResult("browser_open", { error: err instanceof Error ? err.message : String(err), mode: "local" });
+        }
+      }
+      const profile = input.profile ?? browserServiceProfileName();
+      const saveProfileChanges = input.save_profile_changes ?? browserServiceProfileSaveChanges();
+      const open = await req("POST", "/agent/sessions", {
+        label: input.label,
+        ...profile ? { profile } : {},
+        ...profile && typeof saveProfileChanges === "boolean" ? { save_profile_changes: saveProfileChanges } : {},
+        timeout_seconds: input.timeout_seconds
+      });
+      if (!open.ok) return errorResult("browser_open", open.data);
+      const session = open.data;
+      if (input.url) {
+        await req("POST", `/agent/sessions/${session.session_id}/goto`, { url: input.url });
+      }
+      return structuredResult({
+        ok: true,
+        tool: "browser_open",
+        session_id: session.session_id,
+        watch_url: `${consoleBase}/console/${session.session_id}`,
+        live_view_url: session.live_view_url ?? null,
+        url: input.url ?? null,
+        hint: "Call browser_screenshot to see the page. Click by the x,y of an element from the snapshot.",
+        raw: session
+      });
+    }
+  );
+  server.registerTool(
+    "browser_screenshot",
+    {
+      title: "See Page (Screenshot + Elements)",
+      description: "Capture what the browser currently shows. Returns a screenshot image PLUS a text snapshot listing interactive elements with their center x,y coordinates, the page url and title, and visible text. This is your primary way to perceive the page. Click elements by their listed x,y. If a Cloudflare/CAPTCHA challenge is visible, wait and screenshot again rather than clicking it.",
+      inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserScreenshotOutputSchema,
+      annotations: annotations("See Page", true)
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        try {
+          const res2 = await localBrowser.screenshot(input.session_id);
+          const content2 = [];
+          if (res2.image_base64) content2.push({ type: "image", data: res2.image_base64, mimeType: res2.mime_type });
+          const structured2 = {
+            ok: true,
+            tool: "browser_screenshot",
+            session_id: input.session_id,
+            url: res2.url ?? null,
+            title: res2.title ?? null,
+            text: res2.text,
+            elements: res2.elements,
+            screenshot: { mime_type: res2.mime_type, inline: true }
+          };
+          content2.push({ type: "text", text: JSON.stringify(structured2) });
+          return { content: content2, structuredContent: structured2 };
+        } catch (err) {
+          return errorResult("browser_screenshot", { error: err instanceof Error ? err.message : String(err), mode: "local" }, input.session_id);
+        }
+      }
+      const res = await req("POST", `/agent/sessions/${input.session_id}/screenshot`);
+      if (!res.ok) return errorResult("browser_screenshot", res.data, input.session_id);
+      const { image_base64, mime_type, url, title, elements, text } = res.data;
+      const content = [];
+      if (image_base64) content.push({ type: "image", data: image_base64, mimeType: mime_type ?? "image/png" });
+      const structured = {
+        ok: true,
+        tool: "browser_screenshot",
+        session_id: input.session_id,
+        url: url ?? null,
+        title: title ?? null,
+        text: typeof text === "string" ? text : "",
+        elements: Array.isArray(elements) ? elements : [],
+        screenshot: image_base64 ? { mime_type: mime_type ?? "image/png", inline: true } : null
+      };
+      content.push({
+        type: "text",
+        text: JSON.stringify(structured)
+      });
+      return { content, structuredContent: structured };
+    }
+  );
+  server.registerTool(
+    "browser_read",
+    {
+      title: "Read Page Text + Elements",
+      description: "Return the page url, title, visible text, and the list of interactive elements (with x,y) without an image. Cheaper than browser_screenshot when you only need to read content or find a target element to click.",
+      inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserReadOutputSchema,
+      annotations: annotations("Read Page", true)
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        try {
+          const res2 = await localBrowser.read(input.session_id);
+          return structuredResult({
+            ok: true,
+            tool: "browser_read",
+            session_id: input.session_id,
+            url: res2.url ?? null,
+            title: res2.title ?? null,
+            text: res2.text,
+            elements: res2.elements,
+            raw: res2
+          });
+        } catch (err) {
+          return errorResult("browser_read", { error: err instanceof Error ? err.message : String(err), mode: "local" }, input.session_id);
+        }
+      }
+      const res = await req("POST", `/agent/sessions/${input.session_id}/read`);
+      if (!res.ok) return errorResult("browser_read", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_read",
+        session_id: input.session_id,
+        url: res.data?.url ?? null,
+        title: res.data?.title ?? null,
+        text: typeof res.data?.text === "string" ? res.data.text : "",
+        elements: Array.isArray(res.data?.elements) ? res.data.elements : [],
+        raw: res.data
+      });
+    }
+  );
+  server.registerTool(
+    "browser_locate",
+    {
+      title: "Locate DOM Targets",
+      description: "Locate exact visible DOM elements or text ranges in the current browser viewport and return left/top/width/height bounds in screenshot pixels. Use this before drawing annotations or when a callout must literally circle, box, underline, or point to a real element. Prefer CSS selectors for exact UI elements; use text when selector is unknown. When a replay is actively recording, the result includes replay_elapsed_seconds for timing.",
+      inputSchema: BrowserLocateInputSchema,
+      outputSchema: BrowserLocateOutputSchema,
+      annotations: annotations("Locate DOM Targets", true)
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        try {
+          const res2 = await localBrowser.locate(input.session_id, input.targets);
+          return structuredResult({
+            ok: true,
+            tool: "browser_locate",
+            session_id: input.session_id,
+            url: res2.url ?? null,
+            title: res2.title ?? null,
+            viewport: res2.viewport ?? null,
+            replay: null,
+            targets: Array.isArray(res2.targets) ? res2.targets : [],
+            raw: res2
+          });
+        } catch (err) {
+          return errorResult("browser_locate", { error: err instanceof Error ? err.message : String(err), mode: "local" }, input.session_id);
+        }
+      }
+      const res = await req("POST", `/agent/sessions/${input.session_id}/locate`, { targets: input.targets });
+      if (!res.ok) return errorResult("browser_locate", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_locate",
+        session_id: input.session_id,
+        url: res.data?.url ?? null,
+        title: res.data?.title ?? null,
+        viewport: res.data?.viewport ?? null,
+        replay: res.data?.replay ?? null,
+        targets: Array.isArray(res.data?.targets) ? res.data.targets : [],
+        raw: res.data
+      });
+    }
+  );
+  server.registerTool(
+    "browser_goto",
+    {
+      title: "Navigate To URL",
+      description: "Navigate an existing browser session to a URL when the user asks you to go to another page or continue browsing in the same session. Use browser_open first if no session exists. Follow with browser_screenshot to see redirects, login walls, CAPTCHA/Cloudflare state, or the loaded page.",
+      inputSchema: BrowserGotoInputSchema,
+      outputSchema: BrowserActionOutputSchema,
+      annotations: annotations("Navigate To URL")
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        try {
+          const res2 = await localBrowser.goto(input.session_id, input.url);
+          return actionResult("browser_goto", input.session_id, true, res2, "browser_screenshot");
+        } catch (err) {
+          return errorResult("browser_goto", { error: err instanceof Error ? err.message : String(err), mode: "local" }, input.session_id);
+        }
+      }
+      const res = await req("POST", `/agent/sessions/${input.session_id}/goto`, { url: input.url });
+      return actionResult("browser_goto", input.session_id, res.ok, res.data, "browser_screenshot");
+    }
+  );
+  server.registerTool(
+    "browser_click",
+    {
+      title: "Click",
+      description: "Click a visible page target using screenshot pixel coordinates. Use this when the user asks you to press a button, open a menu, choose a result, or activate a visible UI element. Use x/y only from the latest browser_screenshot, browser_read, or browser_locate result; do not guess coordinates. Follow with browser_screenshot when the click may change the page.",
+      inputSchema: BrowserClickInputSchema,
+      outputSchema: BrowserActionOutputSchema,
+      annotations: annotations("Click")
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        try {
+          const res2 = await localBrowser.click(input.session_id, input);
+          return actionResult("browser_click", input.session_id, true, res2, "browser_screenshot");
+        } catch (err) {
+          return errorResult("browser_click", { error: err instanceof Error ? err.message : String(err), mode: "local" }, input.session_id);
+        }
+      }
+      const res = await req("POST", `/agent/sessions/${input.session_id}/click`, {
+        x: input.x,
+        y: input.y,
+        button: input.button,
+        num_clicks: input.num_clicks
+      });
+      return actionResult("browser_click", input.session_id, res.ok, res.data, "browser_screenshot");
+    }
+  );
+  server.registerTool(
+    "browser_type",
+    {
+      title: "Type Text",
+      description: 'Type text into the currently focused browser field. Use this when the user asks you to fill a search box, form field, login field, or editable text area. Click or Tab to the field first if focus is uncertain. Use browser_press with ["Return"] to submit, and browser_screenshot afterward when page state matters.',
+      inputSchema: BrowserTypeInputSchema,
+      outputSchema: BrowserActionOutputSchema,
+      annotations: annotations("Type Text")
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        try {
+          const res2 = await localBrowser.type(input.session_id, input);
+          return actionResult("browser_type", input.session_id, true, res2, "browser_screenshot");
+        } catch (err) {
+          return errorResult("browser_type", { error: err instanceof Error ? err.message : String(err), mode: "local" }, input.session_id);
+        }
+      }
+      const res = await req("POST", `/agent/sessions/${input.session_id}/type`, { text: input.text, delay: input.delay });
+      return actionResult("browser_type", input.session_id, res.ok, res.data, "browser_screenshot");
+    }
+  );
+  server.registerTool(
+    "browser_scroll",
+    {
+      title: "Scroll",
+      description: "Scroll the page to reveal more content before reading, clicking, or locating elements. Positive delta_y scrolls down; negative delta_y scrolls up. Follow with browser_screenshot or browser_read to inspect newly revealed content.",
+      inputSchema: BrowserScrollInputSchema,
+      outputSchema: BrowserActionOutputSchema,
+      annotations: annotations("Scroll")
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        try {
+          const res2 = await localBrowser.scroll(input.session_id, input);
+          return actionResult("browser_scroll", input.session_id, true, res2, "browser_screenshot");
+        } catch (err) {
+          return errorResult("browser_scroll", { error: err instanceof Error ? err.message : String(err), mode: "local" }, input.session_id);
+        }
+      }
+      const res = await req("POST", `/agent/sessions/${input.session_id}/scroll`, {
+        delta_y: input.delta_y,
+        delta_x: input.delta_x,
+        x: input.x,
+        y: input.y
+      });
+      return actionResult("browser_scroll", input.session_id, res.ok, res.data, "browser_screenshot");
+    }
+  );
+  server.registerTool(
+    "browser_press",
+    {
+      title: "Press Keys",
+      description: 'Press keyboard keys or combinations in the active browser session. Use this for submit, Escape, Tab navigation, select-all, or keyboard shortcuts. Examples: ["Return"], ["Escape"], ["Tab"], ["Ctrl+a"], ["Ctrl+Shift+Tab"]. Use browser_type for text entry and browser_screenshot after keypresses that may change the page.',
+      inputSchema: BrowserPressInputSchema,
+      outputSchema: BrowserActionOutputSchema,
+      annotations: annotations("Press Keys")
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        try {
+          const res2 = await localBrowser.press(input.session_id, input);
+          return actionResult("browser_press", input.session_id, true, res2, "browser_screenshot");
+        } catch (err) {
+          return errorResult("browser_press", { error: err instanceof Error ? err.message : String(err), mode: "local" }, input.session_id);
+        }
+      }
+      const res = await req("POST", `/agent/sessions/${input.session_id}/press`, { keys: input.keys });
+      return actionResult("browser_press", input.session_id, res.ok, res.data, "browser_screenshot");
+    }
+  );
+  server.registerTool(
+    "browser_replay_start",
+    {
+      title: "Start Recording",
+      description: "Start recording an MP4 replay of the session. Returns replay_id, view_url when available, and a download_url. Use to capture a task for later review; stop with browser_replay_stop.",
+      inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserReplayStartOutputSchema,
+      annotations: annotations("Start Recording")
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) return localReplayUnsupported("browser_replay_start", input.session_id);
+      const res = await req("POST", `/agent/sessions/${input.session_id}/replay/start`);
+      if (!res.ok) return errorResult("browser_replay_start", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_start",
+        session_id: input.session_id,
+        replay_id: res.data?.replay_id ?? res.data?.replayId ?? null,
+        view_url: res.data?.view_url ?? res.data?.viewUrl ?? null,
+        download_url: res.data?.download_url ?? res.data?.downloadUrl ?? null,
+        raw: res.data
+      });
+    }
+  );
+  server.registerTool(
+    "browser_replay_stop",
+    {
+      title: "Stop Recording",
+      description: "Stop a replay recording and expose the final view_url and download_url. Use browser_replay_download to save the MP4 locally.",
+      inputSchema: BrowserReplayStopInputSchema,
+      outputSchema: BrowserReplayStopOutputSchema,
+      annotations: annotations("Stop Recording")
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) return localReplayUnsupported("browser_replay_stop", input.session_id, input.replay_id);
+      const res = await req("POST", `/agent/sessions/${input.session_id}/replay/stop`, { replay_id: input.replay_id });
+      if (!res.ok) return errorResult("browser_replay_stop", res.data, input.session_id, input.replay_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_stop",
+        session_id: input.session_id,
+        replay_id: res.data?.replay_id ?? res.data?.replayId ?? input.replay_id,
+        view_url: res.data?.view_url ?? res.data?.viewUrl ?? null,
+        download_url: res.data?.download_url ?? res.data?.downloadUrl ?? null,
+        raw: res.data
+      });
+    }
+  );
+  server.registerTool(
+    "browser_list_replays",
+    {
+      title: "List Replay Videos",
+      description: "List replay recordings for a browser session, including final view_url and authenticated download_url values when available.",
+      inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserListReplaysOutputSchema,
+      annotations: annotations("List Replay Videos", true)
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) return localReplayUnsupported("browser_list_replays", input.session_id);
+      const res = await req("GET", `/agent/sessions/${input.session_id}/replays`);
+      if (!res.ok) return errorResult("browser_list_replays", res.data, input.session_id);
+      const replays = Array.isArray(res.data?.replays) ? res.data.replays : [];
+      return structuredResult({
+        ok: true,
+        tool: "browser_list_replays",
+        session_id: input.session_id,
+        replays,
+        count: replays.length
+      });
+    }
+  );
+  server.registerTool(
+    "browser_replay_download",
+    {
+      title: "Download Replay MP4",
+      description: "Download a replay recording through MCP Scraper and save the MP4 locally under MCP_SCRAPER_OUTPUT_DIR/browser-replays. Use after browser_replay_stop or browser_list_replays.",
+      inputSchema: BrowserReplayDownloadInputSchema,
+      outputSchema: BrowserReplayDownloadOutputSchema,
+      annotations: annotations("Download Replay MP4")
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) return localReplayUnsupported("browser_replay_download", input.session_id, input.replay_id);
+      const res = await downloadReplay(input.session_id, input.replay_id, input.filename);
+      if (!res.ok) return errorResult("browser_replay_download", res.data, input.session_id, input.replay_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_download",
+        session_id: input.session_id,
+        replay_id: input.replay_id,
+        file_path: res.data?.file_path ?? null,
+        bytes: typeof res.data?.bytes === "number" ? res.data.bytes : null,
+        mime_type: res.data?.mime_type ?? null,
+        download_url: res.data?.download_url ?? null
+      });
+    }
+  );
+  server.registerTool(
+    "browser_replay_mark",
+    {
+      title: "Mark Replay Annotation",
+      description: "While a replay is actively recording, locate one exact DOM target and return a ready-to-use annotation object with DOM bounds and replay-relative timing. Use this instead of guessing start_seconds or drawing rough rectangles. Workflow: start browser_replay_start, navigate until the target is visible and stable, call browser_replay_mark for each callout, then stop the replay and pass the returned annotations to browser_replay_annotate.",
+      inputSchema: BrowserReplayMarkInputSchema,
+      outputSchema: BrowserReplayMarkOutputSchema,
+      annotations: annotations("Mark Replay Annotation", true)
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) return localReplayUnsupported("browser_replay_mark", input.session_id);
+      const res = await req("POST", `/agent/sessions/${input.session_id}/locate`, { targets: [input.target] });
+      if (!res.ok) return errorResult("browser_replay_mark", res.data, input.session_id);
+      const target = res.data?.targets?.[0];
+      const element = target?.element;
+      const elapsed = res.data?.replay?.replay_elapsed_seconds;
+      if (!target?.found || !element) {
+        return errorResult("browser_replay_mark", { error: target?.error ?? "target not found in current viewport", target }, input.session_id);
+      }
+      if (!finiteNumber2(elapsed)) {
+        return errorResult("browser_replay_mark", { error: "no active replay clock found; call browser_replay_start before browser_replay_mark" }, input.session_id);
+      }
+      const padded = expandElementBounds(element, res.data?.viewport, input.padding ?? 8);
+      const start = Math.max(0, elapsed + (input.start_offset_seconds ?? -0.25));
+      const duration = input.duration_seconds ?? 4;
+      const annotation = {
+        type: input.type ?? "box",
+        start_seconds: Number(start.toFixed(3)),
+        end_seconds: Number((start + duration).toFixed(3)),
+        left: Math.round(padded.left),
+        top: Math.round(padded.top),
+        width: Math.round(padded.width),
+        height: Math.round(padded.height),
+        ...input.label ? { label: input.label } : {},
+        ...input.color ? { color: input.color } : {},
+        ...input.thickness ? { thickness: input.thickness } : {}
+      };
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_mark",
+        session_id: input.session_id,
+        replay_id: res.data?.replay?.replay_id ?? res.data?.replay?.replayId ?? null,
+        annotation,
+        source_width: padded.sourceWidth,
+        source_height: padded.sourceHeight,
+        replay: res.data.replay,
+        target,
+        hint: "Append annotation to your annotations array. Use source_width/source_height with browser_replay_annotate."
+      });
+    }
+  );
+  server.registerTool(
+    "browser_replay_annotate",
+    {
+      title: "Annotate Replay MP4",
+      description: "Download a browser replay MP4, render visual annotations over it, and save a new annotated MP4 locally. Use this after browser_replay_stop when the user wants proof videos with circles, boxes, arrows, underlines, or labels. For accurate timing and placement, prefer annotations returned by browser_replay_mark while the replay is recording; otherwise use exact left/top/width/height bounds from browser_locate. If the replay video size differs from the screenshot coordinate space, pass source_width and source_height.",
+      inputSchema: BrowserReplayAnnotateInputSchema,
+      outputSchema: BrowserReplayAnnotateOutputSchema,
+      annotations: annotations("Annotate Replay MP4")
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) return localReplayUnsupported("browser_replay_annotate", input.session_id, input.replay_id);
+      const sourceName = input.filename ? `${input.filename}-source` : void 0;
+      const downloaded = await downloadReplay(input.session_id, input.replay_id, sourceName);
+      if (!downloaded.ok) return errorResult("browser_replay_annotate", downloaded.data, input.session_id, input.replay_id);
+      try {
+        const sourcePath = String(downloaded.data.file_path);
+        const outputPath = annotatedReplayFilePath(input.session_id, input.replay_id, input.filename);
+        mkdirSync(join2(outputBaseDir(), "browser-replays"), { recursive: true });
+        const result = await annotateReplayVideo(sourcePath, outputPath, {
+          annotations: input.annotations,
+          sourceWidth: input.source_width,
+          sourceHeight: input.source_height,
+          sourceLeftOffset: input.source_left_offset,
+          sourceTopOffset: input.source_top_offset
+        });
+        return structuredResult({
+          ok: true,
+          tool: "browser_replay_annotate",
+          session_id: input.session_id,
+          replay_id: input.replay_id,
+          source_file_path: sourcePath,
+          annotated_file_path: result.filePath,
+          bytes: result.bytes,
+          width: result.width,
+          height: result.height,
+          annotation_count: result.annotationCount,
+          mime_type: "video/mp4"
+        });
+      } catch (err) {
+        return errorResult("browser_replay_annotate", { error: err instanceof Error ? err.message : String(err) }, input.session_id, input.replay_id);
+      }
+    }
+  );
+  server.registerTool(
+    "browser_close",
+    {
+      title: "Close Browser Session",
+      description: "Close and release a browser session when the task is done, when the user asks to stop the browser, or when active browser billing should end. Use browser_list_sessions first if you need to recover the session_id.",
+      inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserCloseOutputSchema,
+      annotations: { title: "Close Browser Session", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        try {
+          const res2 = await localBrowser.close(input.session_id);
+          return structuredResult({
+            ok: true,
+            tool: "browser_close",
+            session_id: input.session_id,
+            closed: true,
+            raw: res2
+          });
+        } catch (err) {
+          return errorResult("browser_close", { error: err instanceof Error ? err.message : String(err), mode: "local" }, input.session_id);
+        }
+      }
+      const res = await req("DELETE", `/agent/sessions/${input.session_id}`);
+      if (!res.ok) return errorResult("browser_close", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_close",
+        session_id: input.session_id,
+        closed: true,
+        raw: res.data
+      });
+    }
+  );
+  server.registerTool(
+    "browser_list_sessions",
+    {
+      title: "List Browser Sessions",
+      description: "List browser sessions and their status, with a watch_url for each. Use this to recover a session_id, find an active browser, or decide which session to close. Use browser_open to create a new session.",
+      inputSchema: BrowserListInputSchema,
+      outputSchema: BrowserListSessionsOutputSchema,
+      annotations: annotations("List Browser Sessions", true)
+    },
+    async (input) => {
+      if (localBrowserModeEnabled()) {
+        const sessions2 = localBrowser.list(input.include_closed);
+        return structuredResult({
+          ok: true,
+          tool: "browser_list_sessions",
+          session_id: null,
+          sessions: sessions2,
+          count: sessions2.length
+        });
+      }
+      const res = await req("GET", `/agent/sessions${input.include_closed ? "?all=1" : ""}`);
+      if (!res.ok) return errorResult("browser_list_sessions", res.data);
+      const sessions = (res.data.sessions ?? []).map((s) => ({ ...s, watch_url: `${consoleBase}/console/${s.session_id}` }));
+      return structuredResult({
+        ok: true,
+        tool: "browser_list_sessions",
+        session_id: null,
+        sessions,
+        count: sessions.length
+      });
+    }
+  );
+}
+
+export {
+  buildBrowserAgentMcpServer,
+  registerBrowserAgentMcpTools
+};
+//# sourceMappingURL=chunk-HS6OKELW.js.map