mcp-scraper 0.2.19 → 0.2.21

package/dist/bin/browser-agent-stdio-server.cjs

@@ -2,30 +2,642 @@
 "use strict";
 
 // bin/browser-agent-stdio-server.ts
-var import_node_fs2 = require("fs");
-var import_node_os3 = require("os");
-var import_node_path3 = require("path");
+var import_node_fs4 = require("fs");
+var import_node_os5 = require("os");
+var import_node_path6 = require("path");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
 // src/mcp/browser-agent-mcp-server.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_node_fs3 = require("fs");
+var import_node_os4 = require("os");
+var import_node_path5 = require("path");
+
+// src/lib/chrome-profiles.ts
+var import_promises = require("fs/promises");
+var import_node_os = require("os");
+var import_node_path = require("path");
+function defaultChromeUserDataDir() {
+  if (process.platform === "darwin") return (0, import_node_path.join)((0, import_node_os.homedir)(), "Library", "Application Support", "Google", "Chrome");
+  if (process.platform === "win32") {
+    return (0, import_node_path.join)(process.env.LOCALAPPDATA ?? (0, import_node_path.join)((0, import_node_os.homedir)(), "AppData", "Local"), "Google", "Chrome", "User Data");
+  }
+  return (0, import_node_path.join)(process.env.XDG_CONFIG_HOME ?? (0, import_node_path.join)((0, import_node_os.homedir)(), ".config"), "google-chrome");
+}
+function recommendedKernelProfileName(value) {
+  return value.trim().toLowerCase().replace(/@/g, "-").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "browser-profile";
+}
+async function listLocalChromeProfiles(userDataDir = defaultChromeUserDataDir(), emailFilter) {
+  const raw = await (0, import_promises.readFile)((0, import_node_path.join)(userDataDir, "Local State"), "utf8");
+  const localState = JSON.parse(raw);
+  const wanted = emailFilter?.trim().toLowerCase();
+  return Object.entries(localState.profile?.info_cache ?? {}).map(([directory, info]) => {
+    const email = (info.user_name ?? "").trim();
+    const displayName = (info.name ?? info.shortcut_name ?? "").trim();
+    const labelSource = email || displayName || directory;
+    return {
+      email,
+      displayName,
+      chromeProfileDirectory: directory,
+      chromeProfilePath: (0, import_node_path.join)(userDataDir, directory),
+      recommendedKernelProfileName: recommendedKernelProfileName(labelSource)
+    };
+  }).filter((row) => !wanted || row.email.toLowerCase() === wanted || row.displayName.toLowerCase().includes(wanted));
+}
+
+// src/lib/browser-service-env.ts
+function browserServiceProfileName() {
+  const value = (process.env.BROWSER_AGENT_PROFILE_NAME ?? process.env.BROWSER_SERVICE_PROFILE_NAME ?? process.env.KERNEL_BROWSER_PROFILE_NAME ?? process.env.KERNEL_PROFILE_NAME)?.trim();
+  return value || void 0;
+}
+function browserServiceProfileSaveChanges() {
+  const value = (process.env.BROWSER_AGENT_PROFILE_SAVE_CHANGES ?? process.env.BROWSER_SERVICE_PROFILE_SAVE_CHANGES ?? process.env.KERNEL_BROWSER_PROFILE_SAVE_CHANGES ?? process.env.KERNEL_PROFILE_SAVE_CHANGES)?.trim().toLowerCase();
+  if (!value) return void 0;
+  if (["1", "true", "yes", "on"].includes(value)) return true;
+  if (["0", "false", "no", "off"].includes(value)) return false;
+  return void 0;
+}
+
+// src/lib/local-browser-profiles.ts
 var import_node_fs = require("fs");
+var import_promises2 = require("fs/promises");
 var import_node_os2 = require("os");
 var import_node_path2 = require("path");
+var EXCLUDED_PROFILE_NAMES = [
+  "Cache",
+  "Code Cache",
+  "Crashpad",
+  "DawnCache",
+  "DawnGraphiteCache",
+  "DawnWebGPUCache",
+  "GPUCache",
+  "GrShaderCache",
+  "ShaderCache",
+  "Shared Dictionary"
+];
+function defaultImportedBrowserProfilesDir() {
+  return process.env.MCP_SCRAPER_BROWSER_PROFILE_BASE_DIR?.trim() || (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".mcp-scraper", "browser-profiles");
+}
+function defaultChromeExecutablePath() {
+  const envPath = process.env.MCP_SCRAPER_BROWSER_EXECUTABLE?.trim() || process.env.CHROME_PATH?.trim();
+  if (envPath) return envPath;
+  const candidates = process.platform === "darwin" ? ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"] : process.platform === "win32" ? [
+    (0, import_node_path2.join)(process.env.PROGRAMFILES ?? "C:\\Program Files", "Google", "Chrome", "Application", "chrome.exe"),
+    (0, import_node_path2.join)(process.env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)", "Google", "Chrome", "Application", "chrome.exe")
+  ] : ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium-browser", "/usr/bin/chromium"];
+  return candidates.find((candidate) => (0, import_node_fs.existsSync)(candidate));
+}
+function localBrowserModeEnabled() {
+  return process.env.MCP_SCRAPER_BROWSER_MODE?.trim().toLowerCase() === "local";
+}
+function importedProfileName(value) {
+  return recommendedKernelProfileName(value);
+}
+function importedProfileRoot(name, outputDir = defaultImportedBrowserProfilesDir()) {
+  return (0, import_node_path2.join)(outputDir, importedProfileName(name));
+}
+function importedProfileManifestPath(name, outputDir = defaultImportedBrowserProfilesDir()) {
+  return (0, import_node_path2.join)(importedProfileRoot(name, outputDir), "manifest.json");
+}
+function importedProfileUserDataDir(name, outputDir = defaultImportedBrowserProfilesDir()) {
+  return (0, import_node_path2.join)(importedProfileRoot(name, outputDir), "user-data");
+}
+async function readExistingManifest(path) {
+  try {
+    return JSON.parse(await (0, import_promises2.readFile)(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isExcludedProfilePath(sourceRoot, sourcePath) {
+  const rel = (0, import_node_path2.relative)(sourceRoot, sourcePath);
+  if (!rel) return false;
+  const parts = rel.split(import_node_path2.sep).filter(Boolean);
+  const last = parts[parts.length - 1] ?? "";
+  if (last.startsWith("Singleton")) return true;
+  if (last === "LOCK" || last.endsWith(".lock")) return true;
+  if (parts.some((part) => EXCLUDED_PROFILE_NAMES.includes(part))) return true;
+  if (parts.includes("Service Worker") && parts.includes("CacheStorage")) return true;
+  return false;
+}
+async function copyProfileTree(sourceProfilePath, destinationProfilePath) {
+  await (0, import_promises2.cp)(sourceProfilePath, destinationProfilePath, {
+    recursive: true,
+    force: true,
+    errorOnExist: false,
+    dereference: false,
+    filter: (source) => !isExcludedProfilePath(sourceProfilePath, source)
+  });
+}
+function selectProfile(profiles, options) {
+  const requestedDirectory = options.chromeProfileDirectory?.trim();
+  const requestedEmail = options.email?.trim().toLowerCase();
+  const exactDirectory = requestedDirectory ? profiles.find((profile) => profile.chromeProfileDirectory === requestedDirectory) : void 0;
+  if (exactDirectory) return exactDirectory;
+  const exactEmail = requestedEmail ? profiles.find((profile) => profile.email.toLowerCase() === requestedEmail) : void 0;
+  if (exactEmail) return exactEmail;
+  const first = profiles[0];
+  if (first) return first;
+  const hint = requestedDirectory ? `Chrome profile directory "${requestedDirectory}"` : requestedEmail ? `Chrome account "${requestedEmail}"` : "Chrome profile";
+  throw new Error(`${hint} was not found in ${options.sourceUserDataDir ?? defaultChromeUserDataDir()}`);
+}
+async function ensureProfilePathExists(profile) {
+  const details = await (0, import_promises2.stat)(profile.chromeProfilePath).catch(() => null);
+  if (!details?.isDirectory()) {
+    throw new Error(`Chrome profile path does not exist or is not a directory: ${profile.chromeProfilePath}`);
+  }
+}
+async function writeNormalizedLocalState(sourceLocalStatePath, destinationLocalStatePath, sourceProfileDirectory) {
+  const raw = await (0, import_promises2.readFile)(sourceLocalStatePath, "utf8");
+  const localState = JSON.parse(raw);
+  const selectedInfo = localState.profile?.info_cache?.[sourceProfileDirectory] ?? localState.profile?.info_cache?.Default ?? {};
+  localState.profile = {
+    ...localState.profile ?? {},
+    info_cache: { Default: selectedInfo },
+    last_used: "Default",
+    last_active_profiles: ["Default"]
+  };
+  await (0, import_promises2.writeFile)(destinationLocalStatePath, `${JSON.stringify(localState, null, 2)}
+`);
+}
+async function importChromeProfile(options = {}) {
+  const sourceUserDataDir = options.sourceUserDataDir?.trim() || defaultChromeUserDataDir();
+  const profiles = await listLocalChromeProfiles(sourceUserDataDir, options.email);
+  const sourceProfile = selectProfile(profiles, { ...options, sourceUserDataDir });
+  await ensureProfilePathExists(sourceProfile);
+  const name = importedProfileName(options.name?.trim() || sourceProfile.recommendedKernelProfileName);
+  const outputDir = options.outputDir?.trim() || defaultImportedBrowserProfilesDir();
+  const profileRoot = importedProfileRoot(name, outputDir);
+  const manifestPath = importedProfileManifestPath(name, outputDir);
+  const userDataDir = importedProfileUserDataDir(name, outputDir);
+  const existingManifest = await readExistingManifest(manifestPath);
+  const existing = (0, import_node_fs.existsSync)(profileRoot);
+  if (existing && !options.overwrite) {
+    throw new Error(`Imported browser profile "${name}" already exists at ${profileRoot}. Re-run with --overwrite to refresh it.`);
+  }
+  if (existing) await (0, import_promises2.rm)(profileRoot, { recursive: true, force: true });
+  await (0, import_promises2.mkdir)((0, import_node_path2.join)(userDataDir, "Default"), { recursive: true });
+  await writeNormalizedLocalState(
+    (0, import_node_path2.join)(sourceUserDataDir, "Local State"),
+    (0, import_node_path2.join)(userDataDir, "Local State"),
+    sourceProfile.chromeProfileDirectory
+  );
+  await copyProfileTree(sourceProfile.chromeProfilePath, (0, import_node_path2.join)(userDataDir, "Default"));
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const manifest = {
+    layoutVersion: 1,
+    name,
+    profileRoot,
+    userDataDir,
+    browserExecutablePath: options.browserExecutablePath?.trim() || defaultChromeExecutablePath() || null,
+    sourceUserDataDir,
+    sourceProfileDirectory: sourceProfile.chromeProfileDirectory,
+    sourceProfilePath: sourceProfile.chromeProfilePath,
+    email: sourceProfile.email,
+    displayName: sourceProfile.displayName,
+    createdAt: existingManifest?.createdAt ?? now,
+    updatedAt: now,
+    copyMode: "chrome-profile-clone"
+  };
+  await (0, import_promises2.writeFile)(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  return {
+    profile: manifest,
+    sourceProfile,
+    excludedNames: EXCLUDED_PROFILE_NAMES
+  };
+}
+async function loadImportedBrowserProfile(name = process.env.MCP_SCRAPER_BROWSER_PROFILE?.trim() || "default", outputDir = defaultImportedBrowserProfilesDir()) {
+  const profileName = importedProfileName(name);
+  const manifestPath = importedProfileManifestPath(profileName, outputDir);
+  const manifest = await readExistingManifest(manifestPath);
+  if (!manifest) {
+    throw new Error(
+      `Imported browser profile "${profileName}" was not found. Run: mcp-scraper-cli browser import-chrome --name ${profileName}`
+    );
+  }
+  return manifest;
+}
+async function syncImportedChromeProfile(name, options = {}) {
+  const outputDir = options.outputDir?.trim() || defaultImportedBrowserProfilesDir();
+  const manifest = await loadImportedBrowserProfile(name, outputDir);
+  return importChromeProfile({
+    name: manifest.name,
+    sourceUserDataDir: manifest.sourceUserDataDir,
+    chromeProfileDirectory: manifest.sourceProfileDirectory,
+    outputDir,
+    overwrite: true,
+    browserExecutablePath: options.browserExecutablePath ?? manifest.browserExecutablePath ?? void 0
+  });
+}
+
+// src/services/browser-agent/local-browser-agent-service.ts
+var import_node_crypto = require("crypto");
+var import_node_fs2 = require("fs");
+var import_node_path3 = require("path");
+var import_playwright = require("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() ? (0, import_node_path3.basename)(directProfileDir()) : "default");
+}
+function launchExecutablePath(profile) {
+  const configured = process.env.MCP_SCRAPER_BROWSER_EXECUTABLE?.trim() || profile.browserExecutablePath || defaultChromeExecutablePath();
+  return configured && (0, import_node_fs2.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_${(0, import_node_crypto.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 import_playwright.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/version.ts
-var PACKAGE_VERSION = "0.2.19";
+var PACKAGE_VERSION = "0.2.20";
 
 // src/mcp/browser-agent-tool-schemas.ts
 var import_zod = require("zod");
+var NullableString = import_zod.z.string().nullable();
+var BrowserRawObject = import_zod.z.record(import_zod.z.unknown());
+var BrowserElementOutput = import_zod.z.record(import_zod.z.unknown());
+var BrowserBaseOutput = {
+  ok: import_zod.z.boolean().describe("Whether the browser-agent action succeeded."),
+  tool: import_zod.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: import_zod.z.string().optional().describe("Optional human label for this session, shown in the watch console."),
   url: import_zod.z.string().url().optional().describe("Optional URL to navigate to immediately after opening."),
   profile: import_zod.z.string().optional().describe("Optional saved profile name to load a logged-in session for a site."),
+  save_profile_changes: import_zod.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: import_zod.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: import_zod.z.string().optional().describe("Optional Chrome account email or displayed profile name to filter for, for example seo@example.com."),
+  user_data_dir: import_zod.z.string().optional().describe("Optional Chrome user data directory. Defaults to the current OS Chrome profile root.")
+};
+var BrowserProfileOnboardInputSchema = {
+  email: import_zod.z.string().optional().describe("Optional local Chrome account email to find and convert into a suggested Kernel profile name."),
+  profile: import_zod.z.string().optional().describe("Optional Kernel browser profile name to create/load. If omitted, email is used to derive one."),
+  user_data_dir: import_zod.z.string().optional().describe("Optional Chrome user data directory for email lookup. Defaults to the current OS Chrome profile root."),
+  url: import_zod.z.string().url().optional().describe("Setup URL to open after creating the browser. Defaults to https://accounts.google.com/."),
+  label: import_zod.z.string().optional().describe("Optional human label for this setup session."),
+  timeout_seconds: import_zod.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: import_zod.z.string().optional().describe("Optional Chrome account email or displayed profile name to select from Chrome Local State."),
+  name: import_zod.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: import_zod.z.string().optional().describe("Optional Chrome profile directory to import, for example Default or Profile 1."),
+  user_data_dir: import_zod.z.string().optional().describe("Optional source Chrome user data directory. Defaults to the current OS Chrome profile root."),
+  output_dir: import_zod.z.string().optional().describe("Optional managed profile base directory. Defaults to ~/.mcp-scraper/browser-profiles."),
+  browser_executable_path: import_zod.z.string().optional().describe("Optional Chrome executable path for local browser launches. Defaults to the installed Google Chrome path when found."),
+  overwrite: import_zod.z.boolean().default(false).describe("Overwrite an existing managed profile clone with the same name.")
+};
+var BrowserProfileSyncInputSchema = {
+  name: import_zod.z.string().describe("Managed MCP Scraper browser profile name to refresh from its recorded source Chrome profile."),
+  output_dir: import_zod.z.string().optional().describe("Optional managed profile base directory. Defaults to ~/.mcp-scraper/browser-profiles."),
+  browser_executable_path: import_zod.z.string().optional().describe("Optional Chrome executable path to store in the refreshed profile manifest.")
+};
 var BrowserSessionInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open.")
+  session_id: import_zod.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 = import_zod.z.object({
   name: import_zod.z.string().optional().describe("Optional label for this target, echoed in the result."),
@@ -37,43 +649,43 @@ var BrowserLocateTargetSchema = import_zod.z.object({
   message: "target requires selector or text"
 });
 var BrowserLocateInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.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: import_zod.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: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.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: import_zod.z.string().url().describe("URL to navigate the browser to.")
 };
 var BrowserClickInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  x: import_zod.z.number().describe("X coordinate to click, in screenshot pixels. Use the x of an element from the latest screenshot."),
-  y: import_zod.z.number().describe("Y coordinate to click, in screenshot pixels."),
+  session_id: import_zod.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: import_zod.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: import_zod.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: import_zod.z.enum(["left", "right", "middle"]).default("left").describe("Mouse button."),
   num_clicks: import_zod.z.number().int().min(1).max(3).optional().describe("Number of clicks, e.g. 2 for double-click.")
 };
 var BrowserTypeInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.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: import_zod.z.string().describe("Text to type at the current focus. Click a field first to focus it."),
   delay: import_zod.z.number().int().min(0).max(500).optional().describe("Optional per-keystroke delay in ms for human-like typing.")
 };
 var BrowserScrollInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.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: import_zod.z.number().default(5).describe("Vertical scroll in wheel units. Positive scrolls down, negative up."),
   delta_x: import_zod.z.number().default(0).describe("Horizontal scroll in wheel units."),
   x: import_zod.z.number().optional().describe("X position to scroll at. Defaults to screen center."),
   y: import_zod.z.number().optional().describe("Y position to scroll at. Defaults to screen center.")
 };
 var BrowserPressInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.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: import_zod.z.array(import_zod.z.string()).min(1).describe('Keys or combinations to press, e.g. ["Return"], ["Ctrl+a"], ["Ctrl+Shift+Tab"].')
 };
 var BrowserReplayStopInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start.")
+  session_id: import_zod.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: import_zod.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: import_zod.z.string().describe("The session id returned by browser_open."),
-  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays."),
+  session_id: import_zod.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: import_zod.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: import_zod.z.string().optional().describe("Optional local MP4 filename. Defaults to a timestamped replay filename.")
 };
 var BrowserReplayAnnotationSchema = import_zod.z.object({
@@ -95,7 +707,7 @@ var BrowserReplayAnnotationSchema = import_zod.z.object({
   thickness: import_zod.z.number().min(1).max(24).optional().describe("Stroke thickness in pixels. Defaults to 5.")
 });
 var BrowserReplayMarkInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open. A replay must already be recording."),
+  session_id: import_zod.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: import_zod.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: import_zod.z.string().max(120).optional().describe("Optional callout text to render near the target."),
@@ -106,8 +718,8 @@ var BrowserReplayMarkInputSchema = {
   duration_seconds: import_zod.z.number().min(0.5).max(30).default(4).describe("How long the generated annotation should remain visible.")
 };
 var BrowserReplayAnnotateInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays."),
+  session_id: import_zod.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: import_zod.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: import_zod.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: import_zod.z.string().optional().describe("Optional output MP4 filename. Defaults to a timestamped annotated replay filename."),
   source_width: import_zod.z.number().positive().optional().describe("Width of the screenshot coordinate space used for annotations. Defaults to the replay video width."),
@@ -118,12 +730,156 @@ var BrowserReplayAnnotateInputSchema = {
 var BrowserListInputSchema = {
   include_closed: import_zod.z.boolean().default(false).describe("Include closed sessions in the list.")
 };
+var BrowserOpenOutputSchema = {
+  ok: import_zod.z.boolean(),
+  tool: import_zod.z.literal("browser_open"),
+  session_id: import_zod.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: import_zod.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: import_zod.z.string(),
+  raw: BrowserRawObject.optional()
+};
+var BrowserProfileListOutputSchema = {
+  ok: import_zod.z.boolean(),
+  tool: import_zod.z.literal("browser_profile_list"),
+  session_id: import_zod.z.null(),
+  profiles: import_zod.z.array(BrowserRawObject),
+  count: import_zod.z.number().int().min(0),
+  hint: import_zod.z.string()
+};
+var BrowserProfileOnboardOutputSchema = {
+  ok: import_zod.z.boolean(),
+  tool: import_zod.z.literal("browser_profile_onboard"),
+  session_id: import_zod.z.string(),
+  watch_url: import_zod.z.string(),
+  live_view_url: NullableString,
+  profile: import_zod.z.string(),
+  setup_url: import_zod.z.string(),
+  chrome_profile: BrowserRawObject.nullable(),
+  next_steps: import_zod.z.array(import_zod.z.string()),
+  raw: BrowserRawObject.optional()
+};
+var BrowserProfileImportOutputSchema = {
+  ok: import_zod.z.boolean(),
+  tool: import_zod.z.literal("browser_profile_import"),
+  session_id: import_zod.z.null(),
+  profile: BrowserRawObject,
+  source_profile: BrowserRawObject,
+  next_steps: import_zod.z.array(import_zod.z.string()),
+  hint: import_zod.z.string()
+};
+var BrowserProfileSyncOutputSchema = {
+  ok: import_zod.z.boolean(),
+  tool: import_zod.z.literal("browser_profile_sync"),
+  session_id: import_zod.z.null(),
+  profile: BrowserRawObject,
+  source_profile: BrowserRawObject,
+  hint: import_zod.z.string()
+};
+var BrowserScreenshotOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_screenshot"),
+  url: NullableString,
+  title: NullableString,
+  text: import_zod.z.string(),
+  elements: import_zod.z.array(BrowserElementOutput),
+  screenshot: import_zod.z.object({
+    mime_type: import_zod.z.string(),
+    inline: import_zod.z.boolean()
+  }).nullable()
+};
+var BrowserReadOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_read"),
+  url: NullableString,
+  title: NullableString,
+  text: import_zod.z.string(),
+  elements: import_zod.z.array(BrowserElementOutput),
+  raw: BrowserRawObject.optional()
+};
+var BrowserLocateOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_locate"),
+  url: NullableString,
+  title: NullableString,
+  viewport: BrowserRawObject.nullable(),
+  replay: BrowserRawObject.nullable(),
+  targets: import_zod.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: import_zod.z.string().nullable()
+};
+var BrowserReplayStartOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_start"),
+  view_url: NullableString,
+  download_url: NullableString,
+  raw: BrowserRawObject.optional()
+};
+var BrowserReplayStopOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_stop"),
+  view_url: NullableString,
+  download_url: NullableString,
+  raw: BrowserRawObject.optional()
+};
+var BrowserListReplaysOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_list_replays"),
+  replays: import_zod.z.array(BrowserRawObject),
+  count: import_zod.z.number().int().min(0)
+};
+var BrowserReplayDownloadOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_download"),
+  file_path: NullableString,
+  bytes: import_zod.z.number().int().min(0).nullable(),
+  mime_type: NullableString,
+  download_url: NullableString
+};
+var BrowserReplayMarkOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_mark"),
+  annotation: BrowserRawObject,
+  source_width: import_zod.z.number().nullable(),
+  source_height: import_zod.z.number().nullable(),
+  target: BrowserRawObject.nullable(),
+  hint: import_zod.z.string()
+};
+var BrowserReplayAnnotateOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_annotate"),
+  source_file_path: NullableString,
+  annotated_file_path: NullableString,
+  bytes: import_zod.z.number().int().min(0).nullable(),
+  width: import_zod.z.number().int().min(0).nullable(),
+  height: import_zod.z.number().int().min(0).nullable(),
+  annotation_count: import_zod.z.number().int().min(0).nullable(),
+  mime_type: NullableString
+};
+var BrowserCloseOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_close"),
+  closed: import_zod.z.boolean(),
+  raw: BrowserRawObject.optional()
+};
+var BrowserListSessionsOutputSchema = {
+  ok: import_zod.z.boolean(),
+  tool: import_zod.z.literal("browser_list_sessions"),
+  session_id: import_zod.z.null(),
+  sessions: import_zod.z.array(BrowserRawObject),
+  count: import_zod.z.number().int().min(0)
+};
 
 // src/mcp/replay-annotator.ts
 var import_node_child_process = require("child_process");
-var import_promises = require("fs/promises");
-var import_node_os = require("os");
-var import_node_path = require("path");
+var import_promises3 = require("fs/promises");
+var import_node_os3 = require("os");
+var import_node_path4 = require("path");
 var import_node_util = require("util");
 var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
 function finiteNumber(value) {
@@ -346,10 +1102,10 @@ function ffmpegFilterPath(path) {
 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 (0, import_promises.mkdtemp)((0, import_node_path.join)((0, import_node_os.tmpdir)(), "mcp-scraper-ass-"));
-  const assPath = (0, import_node_path.join)(tmp, "annotations.ass");
+  const tmp = await (0, import_promises3.mkdtemp)((0, import_node_path4.join)((0, import_node_os3.tmpdir)(), "mcp-scraper-ass-"));
+  const assPath = (0, import_node_path4.join)(tmp, "annotations.ass");
   try {
-    await (0, import_promises.writeFile)(assPath, buildAssSubtitle(options, size), "utf8");
+    await (0, import_promises3.writeFile)(assPath, buildAssSubtitle(options, size), "utf8");
     await execFileAsync("ffmpeg", [
       "-y",
       "-i",
@@ -366,7 +1122,7 @@ async function annotateReplayVideo(inputFilePath, outputFilePath, options) {
       "copy",
       outputFilePath
     ], { maxBuffer: 1024 * 1024 * 20 });
-    const out = await (0, import_promises.stat)(outputFilePath);
+    const out = await (0, import_promises3.stat)(outputFilePath);
     return {
       filePath: outputFilePath,
       bytes: out.size,
@@ -375,16 +1131,48 @@ async function annotateReplayVideo(inputFilePath, outputFilePath, options) {
       annotationCount: options.annotations.length
     };
   } finally {
-    await (0, import_promises.rm)(tmp, { recursive: true, force: true });
+    await (0, import_promises3.rm)(tmp, { recursive: true, force: true });
   }
 }
 
 // src/mcp/browser-agent-mcp-server.ts
-function textResult(value, isError = false) {
-  return { content: [{ type: "text", text: JSON.stringify(value) }], isError };
+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() || (0, import_node_path2.join)((0, import_node_os2.homedir)(), "Downloads", "mcp-scraper");
+  return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path5.join)((0, import_node_os4.homedir)(), "Downloads", "mcp-scraper");
 }
 function safeFilePart(value) {
   return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120) || "replay";
@@ -393,7 +1181,7 @@ 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 (0, import_node_path2.join)(outputBaseDir(), "browser-replays", `${name}.mp4`);
+  return (0, import_node_path5.join)(outputBaseDir(), "browser-replays", `${name}.mp4`);
 }
 function annotatedReplayFilePath(sessionId, replayId, filename) {
   const requested = filename?.trim();
@@ -429,6 +1217,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
   const baseUrl2 = 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(`${baseUrl2}${path}`, {
@@ -457,8 +1246,8 @@ function registerBrowserAgentMcpTools(server2, opts) {
       }
       const bytes = Buffer.from(await res.arrayBuffer());
       const filePath = replayFilePath(sessionId, replayId, filename);
-      (0, import_node_fs.mkdirSync)((0, import_node_path2.join)(outputBaseDir(), "browser-replays"), { recursive: true });
-      (0, import_node_fs.writeFileSync)(filePath, bytes);
+      (0, import_node_fs3.mkdirSync)((0, import_node_path5.join)(outputBaseDir(), "browser-replays"), { recursive: true });
+      (0, import_node_fs3.writeFileSync)(filePath, bytes);
       return {
         ok: true,
         data: {
@@ -480,30 +1269,211 @@ function registerBrowserAgentMcpTools(server2, opts) {
     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);
+  }
+  server2.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) });
+      }
+    }
+  );
+  server2.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) });
+      }
+    }
+  );
+  server2.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) });
+      }
+    }
+  );
+  server2.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
+      });
+    }
+  );
   server2.registerTool(
     "browser_open",
     {
       title: "Open Browser Session",
-      description: "Open a fresh cloud browser you can drive. Returns a session_id used by all other browser_* tools, and a watch_url where a human can watch live or take over. Anti-bot stealth and automatic CAPTCHA/Cloudflare solving are on by default: if a Cloudflare or CAPTCHA challenge appears, do NOT click it \u2014 wait a few seconds and call browser_screenshot again; it is solved automatically. Billing: metered per second of active browser work at ~4 credits per minute; idle and standby time are free. Call browser_close when done to stop the meter. After opening, call browser_screenshot to see the page.",
+      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: input.profile,
+        ...profile ? { profile } : {},
+        ...profile && typeof saveProfileChanges === "boolean" ? { save_profile_changes: saveProfileChanges } : {},
         timeout_seconds: input.timeout_seconds
       });
-      if (!open.ok) return textResult(open.data, true);
+      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 textResult({
+      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,
-        hint: "Call browser_screenshot to see the page. Click by the x,y of an element from the snapshot."
+        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
       });
     }
   );
@@ -513,19 +1483,51 @@ function registerBrowserAgentMcpTools(server2, opts) {
       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 textResult(res.data, true);
+      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({ url, title, elements, text })
+        text: JSON.stringify(structured)
       });
-      return { content };
+      return { content, structuredContent: structured };
     }
   );
   server2.registerTool(
@@ -534,11 +1536,39 @@ function registerBrowserAgentMcpTools(server2, opts) {
       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`);
-      return textResult(res.data, !res.ok);
+      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
+      });
     }
   );
   server2.registerTool(
@@ -547,86 +1577,161 @@ function registerBrowserAgentMcpTools(server2, opts) {
       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 });
-      return textResult(res.data, !res.ok);
+      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
+      });
     }
   );
   server2.registerTool(
     "browser_goto",
     {
       title: "Navigate To URL",
-      description: "Navigate the browser to a URL. Follow with browser_screenshot to see the result.",
+      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 textResult(res.data, !res.ok);
+      return actionResult("browser_goto", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_click",
     {
       title: "Click",
-      description: "Click at x,y (screenshot pixel coordinates). Use the x,y of a target element from the latest browser_screenshot or browser_read.",
+      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 textResult(res.data, !res.ok);
+      return actionResult("browser_click", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_type",
     {
       title: "Type Text",
-      description: 'Type text at the current focus. Click an input field first to focus it. Use browser_press with ["Return"] to submit.',
+      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 textResult(res.data, !res.ok);
+      return actionResult("browser_type", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_scroll",
     {
       title: "Scroll",
-      description: "Scroll the page. Positive delta_y scrolls down. Follow with browser_screenshot to see newly revealed content.",
+      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 textResult(res.data, !res.ok);
+      return actionResult("browser_scroll", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_press",
     {
       title: "Press Keys",
-      description: 'Press keys or combinations, e.g. ["Return"] to submit, ["Ctrl+a"] to select all, ["Ctrl+Shift+Tab"] to switch tabs.',
+      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 textResult(res.data, !res.ok);
+      return actionResult("browser_press", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
@@ -635,11 +1740,22 @@ function registerBrowserAgentMcpTools(server2, opts) {
       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`);
-      return textResult(res.data, !res.ok);
+      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
+      });
     }
   );
   server2.registerTool(
@@ -648,11 +1764,22 @@ function registerBrowserAgentMcpTools(server2, opts) {
       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 });
-      return textResult(res.data, !res.ok);
+      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
+      });
     }
   );
   server2.registerTool(
@@ -661,11 +1788,21 @@ function registerBrowserAgentMcpTools(server2, opts) {
       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`);
-      return textResult(res.data, !res.ok);
+      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
+      });
     }
   );
   server2.registerTool(
@@ -674,11 +1811,23 @@ function registerBrowserAgentMcpTools(server2, opts) {
       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,
-      annotations: annotations("Download Replay MP4", true)
+      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);
-      return textResult(res.data, !res.ok);
+      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
+      });
     }
   );
   server2.registerTool(
@@ -687,19 +1836,21 @@ function registerBrowserAgentMcpTools(server2, opts) {
       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 textResult(res.data, true);
+      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 textResult({ error: target?.error ?? "target not found in current viewport", target }, true);
+        return errorResult("browser_replay_mark", { error: target?.error ?? "target not found in current viewport", target }, input.session_id);
       }
       if (!finiteNumber2(elapsed)) {
-        return textResult({ error: "no active replay clock found; call browser_replay_start before browser_replay_mark" }, true);
+        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));
@@ -716,7 +1867,11 @@ function registerBrowserAgentMcpTools(server2, opts) {
         ...input.color ? { color: input.color } : {},
         ...input.thickness ? { thickness: input.thickness } : {}
       };
-      return textResult({
+      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,
@@ -732,16 +1887,18 @@ function registerBrowserAgentMcpTools(server2, opts) {
       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,
-      annotations: annotations("Annotate Replay MP4", true)
+      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 textResult(downloaded.data, true);
+      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);
-        (0, import_node_fs.mkdirSync)((0, import_node_path2.join)(outputBaseDir(), "browser-replays"), { recursive: true });
+        (0, import_node_fs3.mkdirSync)((0, import_node_path5.join)(outputBaseDir(), "browser-replays"), { recursive: true });
         const result = await annotateReplayVideo(sourcePath, outputPath, {
           annotations: input.annotations,
           sourceWidth: input.source_width,
@@ -749,7 +1906,10 @@ function registerBrowserAgentMcpTools(server2, opts) {
           sourceLeftOffset: input.source_left_offset,
           sourceTopOffset: input.source_top_offset
         });
-        return textResult({
+        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,
@@ -760,7 +1920,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
           mime_type: "video/mp4"
         });
       } catch (err) {
-        return textResult({ error: err instanceof Error ? err.message : String(err) }, true);
+        return errorResult("browser_replay_annotate", { error: err instanceof Error ? err.message : String(err) }, input.session_id, input.replay_id);
       }
     }
   );
@@ -768,28 +1928,67 @@ function registerBrowserAgentMcpTools(server2, opts) {
     "browser_close",
     {
       title: "Close Browser Session",
-      description: "Close and release the browser session when the task is done.",
+      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}`);
-      return textResult(res.data, !res.ok);
+      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
+      });
     }
   );
   server2.registerTool(
     "browser_list_sessions",
     {
       title: "List Browser Sessions",
-      description: "List your browser sessions and their status, with a watch_url for each.",
+      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 textResult(res.data, true);
+      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 textResult({ sessions });
+      return structuredResult({
+        ok: true,
+        tool: "browser_list_sessions",
+        session_id: null,
+        sessions,
+        count: sessions.length
+      });
     }
   );
 }
@@ -797,10 +1996,10 @@ function registerBrowserAgentMcpTools(server2, opts) {
 // bin/browser-agent-stdio-server.ts
 function readApiKeyFile() {
   const explicitPath = process.env.MCP_SCRAPER_KEY_PATH?.trim();
-  const paths = [explicitPath, (0, import_node_path3.join)((0, import_node_os3.homedir)(), ".mcp-scraper-key")].filter(Boolean);
+  const paths = [explicitPath, (0, import_node_path6.join)((0, import_node_os5.homedir)(), ".mcp-scraper-key")].filter(Boolean);
   for (const path of paths) {
     try {
-      const value = (0, import_node_fs2.readFileSync)(path, "utf8").trim();
+      const value = (0, import_node_fs4.readFileSync)(path, "utf8").trim();
       if (value) return value;
     } catch {
     }