iframer-toolkit 0.7.1 → 0.8.0

package/dist/mcp-server.cjs

@@ -98,23 +98,28 @@ function getLocalToken() {
 
 // src/mcp/local-server.ts
 var import_child_process = require("child_process");
+var import_net = __toESM(require("net"));
 var import_fs2 = __toESM(require("fs"));
 var import_path3 = __toESM(require("path"));
 var __dirname = "/Users/eduardoverona/tools/iframer-toolkit/src/mcp";
-var PORT = parseInt(process.env.IFRAMER_LOCAL_PORT || "3022", 10);
+var BASE_PORT = parseInt(process.env.IFRAMER_LOCAL_PORT || "3022", 10);
+var PORT_SCAN_ATTEMPTS = 200;
 var STARTUP_TIMEOUT_MS = 15000;
 var HEALTH_POLL_MS = 300;
 
 class LocalServerManager {
   child = null;
   startingPromise = null;
-  baseUrl;
+  port = null;
+  baseUrl = "";
   logPath;
   constructor() {
-    this.baseUrl = `http://127.0.0.1:${PORT}`;
     this.logPath = import_path3.default.join(getDataDir(), "local-server.log");
   }
   getBaseUrl() {
+    if (!this.baseUrl) {
+      throw new Error("Local server not started yet — call ensureRunning() first.");
+    }
     return this.baseUrl;
   }
   async ensureRunning() {
@@ -128,16 +133,18 @@ class LocalServerManager {
     return this.startingPromise;
   }
   async doStart() {
-    await this.killExisting();
+    this.port = await findFreePort(BASE_PORT, PORT_SCAN_ATTEMPTS);
+    this.baseUrl = `http://127.0.0.1:${this.port}`;
     const dataDir = getDataDir();
     import_fs2.default.mkdirSync(dataDir, { recursive: true });
     const { command, args } = this.resolveRuntime();
     const logFd = import_fs2.default.openSync(this.logPath, "a");
     const env = {
       ...process.env,
-      PORT: String(PORT),
+      PORT: String(this.port),
       IFRAMER_MODE: "local",
-      IFRAMER_DATA_DIR: dataDir
+      IFRAMER_DATA_DIR: dataDir,
+      IFRAMER_PARENT_PID: String(process.pid)
     };
     if (process.env.IFRAMER_SECRET) {
       env.IFRAMER_SECRET = process.env.IFRAMER_SECRET;
@@ -165,7 +172,7 @@ class LocalServerManager {
     }
     this.kill();
     const logTail = this.readLogTail();
-    throw new Error(`Local iframer server failed to start on port ${PORT} within ${STARTUP_TIMEOUT_MS}ms.
+    throw new Error(`Local iframer server failed to start on port ${this.port} within ${STARTUP_TIMEOUT_MS}ms.
 ` + `Last log lines:
 ${logTail}`);
   }
@@ -207,23 +214,9 @@ ${logTail}`);
     }
     this.child = null;
   }
-  async killExisting() {
-    try {
-      const res = await fetch(`${this.baseUrl}/health`, {
-        signal: AbortSignal.timeout(2000)
-      });
-      if (res.ok) {
-        try {
-          await fetch(`${this.baseUrl}/shutdown`, {
-            method: "POST",
-            signal: AbortSignal.timeout(2000)
-          });
-        } catch {}
-        await sleep(500);
-      }
-    } catch {}
-  }
   async healthCheck() {
+    if (!this.baseUrl)
+      return false;
     try {
       const res = await fetch(`${this.baseUrl}/health`, {
         signal: AbortSignal.timeout(2000)
@@ -249,6 +242,26 @@ ${logTail}`);
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+function findFreePort(start, attempts) {
+  return new Promise((resolve, reject) => {
+    const tryPort = (p) => {
+      if (p >= start + attempts) {
+        reject(new Error(`No free port found in ${start}-${start + attempts}`));
+        return;
+      }
+      const srv = import_net.default.createServer();
+      srv.once("error", () => {
+        srv.close();
+        tryPort(p + 1);
+      });
+      srv.once("listening", () => {
+        srv.close(() => resolve(p));
+      });
+      srv.listen(p, "127.0.0.1");
+    };
+    tryPort(start);
+  });
+}
 
 // src/mcp/helpers.ts
 var log = createLogger("mcp");
@@ -581,7 +594,8 @@ Returns: ok, completedSteps, results, obstacles, capturedApi, and on failure: er
       continueOnError: import_zod3.z.boolean().optional().describe("Continue past failing steps (default: false)"),
       captureApi: import_zod3.z.boolean().optional().describe("Record all API calls (XHR/fetch) the page makes."),
       mode: import_zod3.z.enum(["headless", "binary-headful", "docker-headful"]).optional().describe("DO NOT SET THIS unless user explicitly requests a mode. iframer auto-selects and auto-escalates."),
-      autoEscalate: import_zod3.z.boolean().optional().describe("Auto-retry with a stronger mode if blocked (default: true)")
+      autoEscalate: import_zod3.z.boolean().optional().describe("Auto-retry with a stronger mode if blocked (default: true)"),
+      instanceId: import_zod3.z.string().optional().describe("Run in a named parallel browser within this session (default: 'default'). Use distinct ids to drive several browsers at once, e.g. one per account — each keeps its own login/session state.")
     }).optional()
   }, async (params) => {
     try {
@@ -759,150 +773,498 @@ ${api.domain} (${api.baseUrl})`);
 }
 
 // src/mcp/tools/session.ts
+var import_zod5 = require("zod");
+var import_path6 = __toESM(require("path"));
+var import_fs4 = __toESM(require("fs"));
+
+// src/mcp/tools/reverse-engineer.ts
 var import_zod4 = require("zod");
-function registerSessionTool(server) {
-  server.tool("session", `Manage the browser session and lifecycle.
+function registerReverseEngineerTool(server) {
+  server.tool("reverse-engineer", `Reverse-engineer a website's API. Navigates to a URL, performs the steps you specify, and captures every XHR/fetch request the page makes — including auth tokens, cookies, headers, request/response bodies, and ready-to-use curl commands.
 
-Actions:
-- **stop**: save cookies/localStorage to the store, then close the browser. Session data persists for the next run.
-- **clear**: wipe all stored session data (cookies/localStorage) from the database. Does NOT kill running browsers.
-- **restart**: kill all running browser instances (local + Docker) and reset state. The next \`execute\` call will launch a fresh browser automatically. Use this when the browser is frozen, crashed, or in a bad state. Credentials and knowledge cache are NOT affected.
+Use this when the user asks to:
+- "reverse engineer" or "map" a site's API
+- "capture the endpoints" or "save the API"
+- "figure out how this site works under the hood"
+- "record the API calls" so they can be replayed later
 
-Sessions live in the single local SQLite database (~/.iframer/iframer.db), shared across every browser mode.`, {
-    action: import_zod4.z.enum(["stop", "clear", "restart"]).describe("stop: save session state + close browser | clear: wipe stored session data | restart: kill all browsers, fresh start on next execute")
-  }, async ({ action }) => {
+How it works:
+1. You provide steps (same as execute) — navigate, click, fill, extract, etc.
+2. iframer runs them while recording all API calls the page makes
+3. Returns structured data per domain: shared auth + endpoints classified by protocol (rest, graphql, json-rpc, grpc-web, form-rpc, soap) with method, path, action, verb, headers, body, response, curl
+
+IMPORTANT — one request ≠ one endpoint. Each endpoint has (protocol, action):
+- REST: action = "METHOD /parameterized/path". Verb from HTTP method.
+- GraphQL: action = operationName (or doc_id for persisted queries). Many ops share the single /graphql URL — EACH operation is its own endpoint.
+- JSON-RPC: action = body.method (e.g. eth_getBalance, user.list).
+- gRPC-web: action = request path.
+- Form-RPC (FB-style urlencoded): action = fb_api_req_friendly_name / doc_id.
+- SOAP: action = SOAPAction header.
+
+Generate ONE function per (protocol, action). Do NOT merge different GraphQL operations into one function just because they share the URL.
+
+Output layout — save as RUNNABLE CODE to <outputDir>/:
+  auth.{js,ts}                  — shared cookies, tokens, authorization
+  transport/
+    rest.{js,ts}                — shared REST helper (only if any rest endpoints)
+    graphql.{js,ts}             — shared GraphQL client: post(operationName|docId, variables)
+    jsonRpc.{js,ts}             — shared JSON-RPC client (if any)
+    grpc.{js,ts}                — shared gRPC-web client (if any)
+  <protocol>/<verb>/<functionName>.{js,ts}
+    e.g. graphql/queries/getTimelineFeed.ts
+         graphql/mutations/reactToPost.ts
+         rest/read/getChannelMessages.ts
+         rest/create/createMessage.ts
+         jsonRpc/ethGetBalance.ts
+  index.{js,ts}                 — re-exports all endpoint functions
+  types.ts                      — (typed mode only) inferred interfaces from responses
+  README.md                     — endpoints grouped by protocol + verb, dependency chain, auth expiry warning
+
+Use capturedApi[i].endpoints[j].protocol, .action, .verb, .functionName directly — iframer already classified them. Put queries (verb=read|list) under queries/, mutations (verb=create|update|delete|action) under mutations/ for GraphQL. For REST, group by verb dir.
+
+The outputDir defaults to ./<domain>/. Ask the user where to save if unclear.`, {
+    steps: import_zod4.z.array(stepSchema).describe("Pipeline steps to execute while capturing API calls"),
+    outputDir: import_zod4.z.string().optional().describe("Directory to save the captured API files. If not provided, ask the user or default to ./<domain>/"),
+    typed: import_zod4.z.boolean().optional().describe("Save as .ts with inferred types instead of .js. Set to true when the user asks for types, typescript, or type inference."),
+    options: import_zod4.z.object({
+      staleTimeoutMs: import_zod4.z.number().optional().describe("Override the 20s stale-state timeout per step"),
+      continueOnObstacle: import_zod4.z.boolean().optional().describe("Try to auto-resolve obstacles (default: true)"),
+      continueOnError: import_zod4.z.boolean().optional().describe("Continue past failing steps (default: false)"),
+      mode: import_zod4.z.enum(["headless", "binary-headful", "docker-headful"]).optional().describe("Browser mode override")
+    }).optional()
+  }, async (params) => {
     try {
-      if (action === "stop") {
-        const result = await localApiPost("/interactive/stop").catch(() => ({ ok: true, sessionSaved: false }));
-        return { content: [{ type: "text", text: `Session stopped. State saved: ${result.sessionSaved ?? false}` }] };
+      const execParams = {
+        steps: params.steps,
+        options: { ...params.options, captureApi: true }
+      };
+      const mode = params.options?.mode;
+      const dockerRunning = await isDockerRunning();
+      const captureResult = mode === "docker-headful" && dockerRunning ? await apiPost("/execute", execParams) : await localApiPost("/execute", execParams);
+      const lines = [];
+      lines.push(`ok: ${captureResult.ok}`);
+      lines.push(`steps: ${captureResult.completedSteps}/${captureResult.totalSteps}`);
+      if (captureResult.durationMs)
+        lines.push(`duration: ${captureResult.durationMs}ms`);
+      if (captureResult.finalState) {
+        lines.push(`
+Final page: ${captureResult.finalState.title}`);
+        lines.push(`URL: ${captureResult.finalState.url}`);
       }
-      if (action === "clear") {
-        await localApiDelete("/session").catch(() => {});
-        return { content: [{ type: "text", text: "Session data cleared from database." }] };
+      if (captureResult.capturedApi && captureResult.capturedApi.length > 0) {
+        formatCapturedApi(lines, captureResult.capturedApi, params);
+      } else {
+        lines.push(`
+No API calls were captured. The page may not have made any XHR/fetch requests during the steps, or the steps may not have triggered the expected behavior.`);
       }
-      if (action === "restart") {
-        const parts = [];
-        try {
-          await localApiPost("/browser/restart");
-          parts.push("Local browser restarted.");
-        } catch {
-          try {
-            await localServer.restart();
-            parts.push("Local server respawned.");
-          } catch (e) {
-            parts.push(`Local restart failed: ${e instanceof Error ? e.message : String(e)}`);
-          }
+      if (captureResult.error) {
+        lines.push(`
+--- Failure ---`);
+        if (typeof captureResult.error === "string") {
+          lines.push(`Error: ${captureResult.error}`);
+        } else {
+          lines.push(`Failed at step ${captureResult.error.failedAtStep}: ${JSON.stringify(captureResult.error.failedStep)}`);
+          lines.push(`Error type: ${captureResult.error.errorType}`);
+          lines.push(`Message: ${captureResult.error.message}`);
+          if (captureResult.error.suggestion)
+            lines.push(`Suggestion: ${captureResult.error.suggestion}`);
+        }
+      }
+      const screenshotUrl = captureResult.error?.pageState?.screenshotUrl ?? captureResult.finalState?.screenshotUrl;
+      if (screenshotUrl) {
+        const filePath = await resolveScreenshotPath(screenshotUrl);
+        if (filePath) {
+          lines.push(`
+Screenshot saved: ${filePath}`);
+          lines.push("Use the Read tool on the path above to view the screenshot.");
         }
+      }
+      if (captureResult.capturedApi && captureResult.capturedApi.length > 0) {
+        const mainDomain = captureResult.capturedApi[0]?.domain || "api";
+        const outDir = params.outputDir || `./${mainDomain}`;
         try {
-          if (await isDockerRunning()) {
-            await apiPost("/browser/restart");
-            parts.push("Docker browser restarted.");
-          }
-        } catch {}
-        parts.push("Credentials and knowledge cache are untouched. Next execute launches a fresh browser.");
-        return { content: [{ type: "text", text: parts.join(" ") }] };
+          const fs4 = await import("fs");
+          const path6 = await import("path");
+          fs4.mkdirSync(outDir, { recursive: true });
+          const jsonPath = path6.join(outDir, "captured-api.json");
+          fs4.writeFileSync(jsonPath, JSON.stringify(captureResult.capturedApi, null, 2));
+          lines.push(`
+Full captured data saved to: ${jsonPath}`);
+          lines.push("Read this file for complete curl commands, request/response bodies, and auth data.");
+        } catch (writeErr) {
+          lines.push(`
+(Could not save captured JSON: ${writeErr instanceof Error ? writeErr.message : String(writeErr)})`);
+        }
       }
-      return err("Unknown action");
+      let text = lines.join(`
+`);
+      if (text.length > 80000) {
+        text = text.slice(0, 80000) + `
+
+[... response truncated — read captured-api.json for full data]`;
+      }
+      const content = [{ type: "text", text }];
+      if (!captureResult.ok)
+        return { content, isError: true };
+      return { content };
     } catch (e) {
-      return err(`Error: ${getErrorMessage(e)}`);
+      return err(`Connection error: ${getErrorMessage(e)}. Try \`session restart\` and retry.`);
     }
   });
 }
-
-// src/mcp/tools/credentials.ts
-var import_zod5 = require("zod");
-var import_fs5 = __toESM(require("fs"));
-var import_path7 = __toESM(require("path"));
-
-// src/lib/knowledge.ts
-var import_fs4 = __toESM(require("fs"));
-var import_path6 = __toESM(require("path"));
-var log3 = createLogger("knowledge");
-function getKnowledgeDir() {
-  return import_path6.default.join(getDataDir(), "knowledge");
-}
-function getKnowledgePath(domain) {
-  const safe = sanitizeDomain(domain);
-  return import_path6.default.join(getKnowledgeDir(), `${safe}.md`);
-}
-function normalizeDomain(input) {
-  let d = (input || "").trim().toLowerCase();
-  if (!d)
-    return "";
-  try {
-    if (d.includes("://")) {
-      d = new URL(d).hostname;
-    } else if (d.includes("/")) {
-      d = new URL(`https://${d}`).hostname;
-    }
-  } catch {}
-  d = d.replace(/:\d+$/, "");
-  d = d.replace(/^www\./, "");
-  return d;
-}
-function sanitizeDomain(input) {
-  const normalized = normalizeDomain(input);
-  return normalized.replace(/[^a-z0-9.-]/g, "_");
-}
-function readKnowledge(domain) {
-  const p = getKnowledgePath(domain);
-  try {
-    return import_fs4.default.readFileSync(p, "utf8");
-  } catch {
-    return null;
-  }
-}
-function listKnowledge() {
-  const dir = getKnowledgeDir();
-  let entries = [];
-  try {
-    entries = import_fs4.default.readdirSync(dir);
-  } catch {
-    return [];
-  }
-  const results = [];
-  for (const file of entries) {
-    if (!file.endsWith(".md"))
-      continue;
-    const full = import_path6.default.join(dir, file);
-    try {
-      const stat = import_fs4.default.statSync(full);
-      const raw = import_fs4.default.readFileSync(full, "utf8");
-      const parsed = parseMarkdown(raw);
-      results.push({
-        domain: parsed?.domain ?? file.replace(/\.md$/, ""),
-        lastVerified: parsed?.lastVerified ?? new Date(stat.mtimeMs).toISOString(),
-        lastMode: parsed?.lastMode ?? "unknown",
-        sizeBytes: stat.size
-      });
-    } catch {}
-  }
-  results.sort((a, b) => a.lastVerified < b.lastVerified ? 1 : -1);
-  return results;
-}
-function clearKnowledge(domain) {
-  const dir = getKnowledgeDir();
-  if (domain) {
-    const p = getKnowledgePath(domain);
-    try {
-      import_fs4.default.unlinkSync(p);
-      return { removed: 1 };
-    } catch {
-      return { removed: 0 };
-    }
-  }
-  let removed = 0;
-  try {
-    const entries = import_fs4.default.readdirSync(dir);
-    for (const f of entries) {
-      if (f.endsWith(".md")) {
-        try {
-          import_fs4.default.unlinkSync(import_path6.default.join(dir, f));
-          removed++;
-        } catch {}
+function formatCapturedApi(lines, capturedApi, params) {
+  for (const api of capturedApi) {
+    lines.push(`
+━━━ ${api.domain} (${api.baseUrl}) ━━━`);
+    const authParts = [];
+    if (api.auth?.authorization)
+      authParts.push(`Authorization: ${api.auth.authorization.slice(0, 30)}...`);
+    if (api.auth?.cookies && Object.keys(api.auth.cookies).length > 0)
+      authParts.push(`${Object.keys(api.auth.cookies).length} cookies`);
+    if (api.auth?.tokens && Object.keys(api.auth.tokens).length > 0) {
+      for (const [k, v] of Object.entries(api.auth.tokens)) {
+        authParts.push(`${k}: ${String(v).slice(0, 30)}...`);
       }
     }
-  } catch {}
+    if (authParts.length > 0) {
+      lines.push(`
+Auth:`);
+      for (const part of authParts)
+        lines.push(`  ${part}`);
+    }
+    const byProtocol = new Map;
+    for (const ep of api.endpoints) {
+      const p = ep.protocol || "rest";
+      if (!byProtocol.has(p))
+        byProtocol.set(p, []);
+      byProtocol.get(p).push(ep);
+    }
+    const protocolSummary = Array.from(byProtocol.entries()).map(([p, eps]) => `${p}=${eps.length}`).join(", ");
+    lines.push(`
+Endpoints (${api.endpoints.length}) [${protocolSummary}]:`);
+    for (const ep of api.endpoints) {
+      lines.push(`
+  [${ep.protocol}/${ep.verb}] ${ep.functionName}`);
+      lines.push(`    Action: ${ep.action}`);
+      lines.push(`    ${ep.method} ${ep.path}  →  ${ep.responseStatus}`);
+      if (ep.requestBody) {
+        const body = ep.requestBody;
+        const signalKeys = extractSignalKeys(body);
+        if (signalKeys)
+          lines.push(`    Params: ${signalKeys}`);
+      }
+    }
+  }
+  const mainDomain = capturedApi[0]?.domain || "api";
+  const dir = params.outputDir || `./${mainDomain}`;
+  const ext = params.typed ? ".ts" : ".js";
+  lines.push(`
+━━━ Save instructions ━━━`);
+  lines.push(`Save to: ${dir}`);
+  lines.push(`Format: ${ext} files`);
+  const protocolsSeen = new Set;
+  for (const api of capturedApi)
+    for (const ep of api.endpoints)
+      protocolsSeen.add(ep.protocol);
+  lines.push(`
+Layout (protocols present: ${Array.from(protocolsSeen).join(", ")}):`);
+  lines.push(`  auth${ext}`);
+  if (protocolsSeen.has("rest"))
+    lines.push(`  transport/rest${ext}            — shared fetch wrapper with auth headers`);
+  if (protocolsSeen.has("graphql"))
+    lines.push(`  transport/graphql${ext}         — post(operationName|docId, variables) → shared GraphQL client`);
+  if (protocolsSeen.has("json-rpc"))
+    lines.push(`  transport/jsonRpc${ext}         — shared JSON-RPC client`);
+  if (protocolsSeen.has("grpc-web"))
+    lines.push(`  transport/grpc${ext}            — shared gRPC-web client`);
+  if (protocolsSeen.has("form-rpc"))
+    lines.push(`  transport/formRpc${ext}         — shared urlencoded RPC client`);
+  if (protocolsSeen.has("soap"))
+    lines.push(`  transport/soap${ext}            — shared SOAP client`);
+  lines.push(`  <protocol>/<verb>/<functionName>${ext}  — one file per endpoint, uses shared transport`);
+  lines.push(`    e.g. graphql/queries/<fn>${ext}, graphql/mutations/<fn>${ext}, rest/read/<fn>${ext}, rest/create/<fn>${ext}`);
+  lines.push(`  index${ext}                         — re-export all endpoint functions`);
+  if (params.typed)
+    lines.push(`  types.ts                         — interfaces inferred from response bodies`);
+  lines.push(`  README.md                        — endpoints grouped by protocol + verb, auth expiry warning`);
+  lines.push(`
+Rules:`);
+  lines.push(`  - One function per (protocol, action). Use the functionName field verbatim for the file + export name.`);
+  lines.push(`  - verb=read|list → queries/ (GraphQL) or read/ (REST). verb=create|update|delete|action → mutations/ (GraphQL) or verb dir (REST).`);
+  lines.push(`  - Each endpoint file is minimal: import transport + auth, call transport with the action id, pass variables, return typed result.`);
+  lines.push(`  - GraphQL transport signature: post(opNameOrDocId: string, variables: object). Pick doc_id when present in captured body, else operationName.`);
+  lines.push(`  - Do NOT inline auth headers per endpoint — they live in auth${ext} and the transport reads them.`);
+  lines.push(`
+IMPORTANT: Auth data contains real tokens/cookies — they expire. Remind the user.`);
+}
+function extractSignalKeys(body) {
+  const NOISE = new Set([
+    "__csr",
+    "__hsdp",
+    "__hblp",
+    "__dyn",
+    "__a",
+    "__req",
+    "__hs",
+    "__comet_req",
+    "__ccg",
+    "__spin_r",
+    "__spin_b",
+    "__spin_t",
+    "__jssesw",
+    "lsd",
+    "fb_dtsg",
+    "fb_api_caller_class",
+    "fb_api_req_friendly_name",
+    "jazoest",
+    "server_timestamps",
+    "__s",
+    "__user",
+    "dpr",
+    "__rev"
+  ]);
+  const signalEntries = [];
+  for (const [k, v] of Object.entries(body)) {
+    if (NOISE.has(k))
+      continue;
+    if (typeof v === "string" && v.length > 80) {
+      signalEntries.push(`${k}=${v.slice(0, 40)}...`);
+    } else if (typeof v === "object" && v !== null) {
+      const keys = Object.keys(v).slice(0, 5).join(",");
+      signalEntries.push(`${k}={${keys}${Object.keys(v).length > 5 ? ",..." : ""}}`);
+    } else {
+      signalEntries.push(`${k}=${String(v).slice(0, 40)}`);
+    }
+  }
+  return signalEntries.length > 0 ? signalEntries.join(", ") : null;
+}
+
+// src/mcp/tools/session.ts
+function registerSessionTool(server) {
+  server.tool("session", `Manage the browser session and lifecycle.
+
+Actions:
+- **stop**: save cookies/localStorage to the store, then close the browser. Session data persists for the next run.
+- **clear**: wipe all stored session data (cookies/localStorage) from the database. Does NOT kill running browsers.
+- **restart**: kill all running browser instances (local + Docker) and reset state. The next \`execute\` call will launch a fresh browser automatically. Use this when the browser is frozen, crashed, or in a bad state. Credentials and knowledge cache are NOT affected.
+- **capture-start**: attach a persistent XHR/fetch listener to the running browser. Accumulates ALL requests indefinitely — not tied to any pipeline. Use before triggering the action you want to capture (e.g. upload, delete, async mutation).
+- **capture-stop**: stop the persistent listener and return all captured endpoints + save to disk. Call this when you're satisfied you've seen the requests you need.
+- **get-cookies**: extract ALL cookies from the browser context via CDP (including HttpOnly/Secure — below the JS sandbox). Pass urls to scope. Returns name, value, domain, path, httpOnly, secure, expiry.
+- **get-auth**: extract cookies + localStorage + sessionStorage in one shot. Everything needed to replay authenticated requests from Node.js.
+
+Sessions live in the single local SQLite database (~/.iframer/iframer.db), shared across every browser mode.`, {
+    action: import_zod5.z.enum(["stop", "clear", "restart", "capture-start", "capture-stop", "get-cookies", "get-auth"]).describe("stop | clear | restart | capture-start | capture-stop | get-cookies | get-auth"),
+    mode: import_zod5.z.enum(["headless", "binary-headful"]).optional().describe("Browser mode (default: binary-headful)"),
+    urls: import_zod5.z.array(import_zod5.z.string()).optional().describe("URLs to scope cookie extraction (get-cookies/get-auth). Omit for all cookies."),
+    instanceId: import_zod5.z.string().optional().describe("Target a named parallel browser within this session (default: 'default'). Match the instanceId used in execute."),
+    outputDir: import_zod5.z.string().optional().describe("Where to save captured-api.json for capture-stop")
+  }, async ({ action, mode, urls, instanceId, outputDir }) => {
+    try {
+      if (action === "stop") {
+        const result = await localApiPost("/interactive/stop").catch(() => ({ ok: true, sessionSaved: false }));
+        return { content: [{ type: "text", text: `Session stopped. State saved: ${result.sessionSaved ?? false}` }] };
+      }
+      if (action === "clear") {
+        await localApiDelete("/session").catch(() => {});
+        return { content: [{ type: "text", text: "Session data cleared from database." }] };
+      }
+      if (action === "restart") {
+        const parts = [];
+        try {
+          await localApiPost("/browser/restart");
+          parts.push("Local browser restarted.");
+        } catch {
+          try {
+            await localServer.restart();
+            parts.push("Local server respawned.");
+          } catch (e) {
+            parts.push(`Local restart failed: ${e instanceof Error ? e.message : String(e)}`);
+          }
+        }
+        try {
+          if (await isDockerRunning()) {
+            await apiPost("/browser/restart");
+            parts.push("Docker browser restarted.");
+          }
+        } catch {}
+        parts.push("Credentials and knowledge cache are untouched. Next execute launches a fresh browser.");
+        return { content: [{ type: "text", text: parts.join(" ") }] };
+      }
+      if (action === "capture-start") {
+        const result = await localApiPost("/capture/start", { mode: mode ?? "binary-headful", instanceId });
+        return { content: [{ type: "text", text: result.message }] };
+      }
+      if (action === "capture-stop") {
+        const result = await localApiPost("/capture/stop", { mode: mode ?? "binary-headful", instanceId });
+        const lines = [result.message];
+        if (result.capturedApi && result.capturedApi.length > 0) {
+          formatCapturedApi(lines, result.capturedApi, { outputDir, typed: false });
+          const outDir = outputDir || import_path6.default.join(getDataDir(), "capture");
+          try {
+            import_fs4.default.mkdirSync(outDir, { recursive: true });
+            const jsonPath = import_path6.default.join(outDir, "captured-api.json");
+            import_fs4.default.writeFileSync(jsonPath, JSON.stringify(result.capturedApi, null, 2));
+            lines.push(`
+Full data saved to: ${jsonPath}`);
+          } catch (writeErr) {
+            lines.push(`
+(Could not save: ${writeErr instanceof Error ? writeErr.message : String(writeErr)})`);
+          }
+        }
+        let text = lines.join(`
+`);
+        if (text.length > 80000)
+          text = text.slice(0, 80000) + `
+
+[truncated — read captured-api.json]`;
+        return { content: [{ type: "text", text }] };
+      }
+      if (action === "get-cookies") {
+        const result = await localApiPost("/auth/cookies", { mode: mode ?? "binary-headful", urls, instanceId });
+        const lines = [result.message, ""];
+        for (const c of result.cookies) {
+          lines.push(`${c.name}=${c.value}  [domain=${c.domain} path=${c.path} httpOnly=${c.httpOnly} secure=${c.secure}]`);
+        }
+        return { content: [{ type: "text", text: lines.join(`
+`) }] };
+      }
+      if (action === "get-auth") {
+        const result = await localApiPost("/auth/full", { mode: mode ?? "binary-headful", urls, instanceId });
+        const lines = [result.message, ""];
+        lines.push("=== Cookies ===");
+        for (const c of result.cookies) {
+          lines.push(`${c.name}=${c.value}  [domain=${c.domain} httpOnly=${c.httpOnly}]`);
+        }
+        if (Object.keys(result.localStorage || {}).length > 0) {
+          lines.push(`
+=== localStorage ===`);
+          for (const [origin, store] of Object.entries(result.localStorage)) {
+            lines.push(`[${origin}]`);
+            for (const [k, v] of Object.entries(store)) {
+              const val = String(v);
+              lines.push(`  ${k}: ${val.length > 120 ? val.slice(0, 120) + "…" : val}`);
+            }
+          }
+        }
+        if (Object.keys(result.sessionStorage || {}).length > 0) {
+          lines.push(`
+=== sessionStorage ===`);
+          for (const [origin, store] of Object.entries(result.sessionStorage)) {
+            lines.push(`[${origin}]`);
+            for (const [k, v] of Object.entries(store)) {
+              const val = String(v);
+              lines.push(`  ${k}: ${val.length > 120 ? val.slice(0, 120) + "…" : val}`);
+            }
+          }
+        }
+        let text = lines.join(`
+`);
+        if (text.length > 80000)
+          text = text.slice(0, 80000) + `
+[truncated]`;
+        return { content: [{ type: "text", text }] };
+      }
+      return err("Unknown action");
+    } catch (e) {
+      return err(`Error: ${getErrorMessage(e)}`);
+    }
+  });
+}
+
+// src/mcp/tools/credentials.ts
+var import_zod6 = require("zod");
+var import_fs6 = __toESM(require("fs"));
+var import_path8 = __toESM(require("path"));
+
+// src/lib/knowledge.ts
+var import_fs5 = __toESM(require("fs"));
+var import_path7 = __toESM(require("path"));
+var log3 = createLogger("knowledge");
+function getKnowledgeDir() {
+  return import_path7.default.join(getDataDir(), "knowledge");
+}
+function getKnowledgePath(domain) {
+  const safe = sanitizeDomain(domain);
+  return import_path7.default.join(getKnowledgeDir(), `${safe}.md`);
+}
+function normalizeDomain(input) {
+  let d = (input || "").trim().toLowerCase();
+  if (!d)
+    return "";
+  try {
+    if (d.includes("://")) {
+      d = new URL(d).hostname;
+    } else if (d.includes("/")) {
+      d = new URL(`https://${d}`).hostname;
+    }
+  } catch {}
+  d = d.replace(/:\d+$/, "");
+  d = d.replace(/^www\./, "");
+  return d;
+}
+function sanitizeDomain(input) {
+  const normalized = normalizeDomain(input);
+  return normalized.replace(/[^a-z0-9.-]/g, "_");
+}
+function readKnowledge(domain) {
+  const p = getKnowledgePath(domain);
+  try {
+    return import_fs5.default.readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+function listKnowledge() {
+  const dir = getKnowledgeDir();
+  let entries = [];
+  try {
+    entries = import_fs5.default.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const results = [];
+  for (const file of entries) {
+    if (!file.endsWith(".md"))
+      continue;
+    const full = import_path7.default.join(dir, file);
+    try {
+      const stat = import_fs5.default.statSync(full);
+      const raw = import_fs5.default.readFileSync(full, "utf8");
+      const parsed = parseMarkdown(raw);
+      results.push({
+        domain: parsed?.domain ?? file.replace(/\.md$/, ""),
+        lastVerified: parsed?.lastVerified ?? new Date(stat.mtimeMs).toISOString(),
+        lastMode: parsed?.lastMode ?? "unknown",
+        sizeBytes: stat.size
+      });
+    } catch {}
+  }
+  results.sort((a, b) => a.lastVerified < b.lastVerified ? 1 : -1);
+  return results;
+}
+function clearKnowledge(domain) {
+  const dir = getKnowledgeDir();
+  if (domain) {
+    const p = getKnowledgePath(domain);
+    try {
+      import_fs5.default.unlinkSync(p);
+      return { removed: 1 };
+    } catch {
+      return { removed: 0 };
+    }
+  }
+  let removed = 0;
+  try {
+    const entries = import_fs5.default.readdirSync(dir);
+    for (const f of entries) {
+      if (f.endsWith(".md")) {
+        try {
+          import_fs5.default.unlinkSync(import_path7.default.join(dir, f));
+          removed++;
+        } catch {}
+      }
+    }
+  } catch {}
   return { removed };
 }
 function parseMarkdown(raw) {
@@ -977,8 +1339,8 @@ var ELICIT_TIMEOUT_MS = 45000;
 function mcpLog(event, data) {
   try {
     const dir = getDataDir();
-    import_fs5.default.mkdirSync(dir, { recursive: true });
-    import_fs5.default.appendFileSync(import_path7.default.join(dir, "mcp.log"), JSON.stringify({ ts: new Date().toISOString(), event, ...data }) + `
+    import_fs6.default.mkdirSync(dir, { recursive: true });
+    import_fs6.default.appendFileSync(import_path8.default.join(dir, "mcp.log"), JSON.stringify({ ts: new Date().toISOString(), event, ...data }) + `
 `);
   } catch {}
 }
@@ -1009,9 +1371,9 @@ CRITICAL RULES
 5. **NEVER ask the user to paste their password in chat.**
 
 6. **\`force: true\` on store is ONLY for explicit password changes.**`, {
-    action: import_zod5.z.enum(["store", "list"]).describe("store: prompt for credentials | list: show stored domains"),
-    domain: import_zod5.z.string().optional().describe("Domain (required for store). Use the bare registrable domain."),
-    force: import_zod5.z.boolean().optional().describe("Overwrite existing. ONLY for explicit password changes.")
+    action: import_zod6.z.enum(["store", "list"]).describe("store: prompt for credentials | list: show stored domains"),
+    domain: import_zod6.z.string().optional().describe("Domain (required for store). Use the bare registrable domain."),
+    force: import_zod6.z.boolean().optional().describe("Overwrite existing. ONLY for explicit password changes.")
   }, async ({ action, domain, force }) => {
     try {
       if (action === "list") {
@@ -1096,262 +1458,6 @@ ${domains.map((d) => `  - ${d}`).join(`
   });
 }
 
-// src/mcp/tools/reverse-engineer.ts
-var import_zod6 = require("zod");
-function registerReverseEngineerTool(server) {
-  server.tool("reverse-engineer", `Reverse-engineer a website's API. Navigates to a URL, performs the steps you specify, and captures every XHR/fetch request the page makes — including auth tokens, cookies, headers, request/response bodies, and ready-to-use curl commands.
-
-Use this when the user asks to:
-- "reverse engineer" or "map" a site's API
-- "capture the endpoints" or "save the API"
-- "figure out how this site works under the hood"
-- "record the API calls" so they can be replayed later
-
-How it works:
-1. You provide steps (same as execute) — navigate, click, fill, extract, etc.
-2. iframer runs them while recording all API calls the page makes
-3. Returns structured data per domain: shared auth + endpoints classified by protocol (rest, graphql, json-rpc, grpc-web, form-rpc, soap) with method, path, action, verb, headers, body, response, curl
-
-IMPORTANT — one request ≠ one endpoint. Each endpoint has (protocol, action):
-- REST: action = "METHOD /parameterized/path". Verb from HTTP method.
-- GraphQL: action = operationName (or doc_id for persisted queries). Many ops share the single /graphql URL — EACH operation is its own endpoint.
-- JSON-RPC: action = body.method (e.g. eth_getBalance, user.list).
-- gRPC-web: action = request path.
-- Form-RPC (FB-style urlencoded): action = fb_api_req_friendly_name / doc_id.
-- SOAP: action = SOAPAction header.
-
-Generate ONE function per (protocol, action). Do NOT merge different GraphQL operations into one function just because they share the URL.
-
-Output layout — save as RUNNABLE CODE to <outputDir>/:
-  auth.{js,ts}                  — shared cookies, tokens, authorization
-  transport/
-    rest.{js,ts}                — shared REST helper (only if any rest endpoints)
-    graphql.{js,ts}             — shared GraphQL client: post(operationName|docId, variables)
-    jsonRpc.{js,ts}             — shared JSON-RPC client (if any)
-    grpc.{js,ts}                — shared gRPC-web client (if any)
-  <protocol>/<verb>/<functionName>.{js,ts}
-    e.g. graphql/queries/getTimelineFeed.ts
-         graphql/mutations/reactToPost.ts
-         rest/read/getChannelMessages.ts
-         rest/create/createMessage.ts
-         jsonRpc/ethGetBalance.ts
-  index.{js,ts}                 — re-exports all endpoint functions
-  types.ts                      — (typed mode only) inferred interfaces from responses
-  README.md                     — endpoints grouped by protocol + verb, dependency chain, auth expiry warning
-
-Use capturedApi[i].endpoints[j].protocol, .action, .verb, .functionName directly — iframer already classified them. Put queries (verb=read|list) under queries/, mutations (verb=create|update|delete|action) under mutations/ for GraphQL. For REST, group by verb dir.
-
-The outputDir defaults to ./<domain>/. Ask the user where to save if unclear.`, {
-    steps: import_zod6.z.array(stepSchema).describe("Pipeline steps to execute while capturing API calls"),
-    outputDir: import_zod6.z.string().optional().describe("Directory to save the captured API files. If not provided, ask the user or default to ./<domain>/"),
-    typed: import_zod6.z.boolean().optional().describe("Save as .ts with inferred types instead of .js. Set to true when the user asks for types, typescript, or type inference."),
-    options: import_zod6.z.object({
-      staleTimeoutMs: import_zod6.z.number().optional().describe("Override the 20s stale-state timeout per step"),
-      continueOnObstacle: import_zod6.z.boolean().optional().describe("Try to auto-resolve obstacles (default: true)"),
-      continueOnError: import_zod6.z.boolean().optional().describe("Continue past failing steps (default: false)"),
-      mode: import_zod6.z.enum(["headless", "binary-headful", "docker-headful"]).optional().describe("Browser mode override")
-    }).optional()
-  }, async (params) => {
-    try {
-      const execParams = {
-        steps: params.steps,
-        options: { ...params.options, captureApi: true }
-      };
-      const mode = params.options?.mode;
-      const dockerRunning = await isDockerRunning();
-      const captureResult = mode === "docker-headful" && dockerRunning ? await apiPost("/execute", execParams) : await localApiPost("/execute", execParams);
-      const lines = [];
-      lines.push(`ok: ${captureResult.ok}`);
-      lines.push(`steps: ${captureResult.completedSteps}/${captureResult.totalSteps}`);
-      if (captureResult.durationMs)
-        lines.push(`duration: ${captureResult.durationMs}ms`);
-      if (captureResult.finalState) {
-        lines.push(`
-Final page: ${captureResult.finalState.title}`);
-        lines.push(`URL: ${captureResult.finalState.url}`);
-      }
-      if (captureResult.capturedApi && captureResult.capturedApi.length > 0) {
-        formatCapturedApi(lines, captureResult.capturedApi, params);
-      } else {
-        lines.push(`
-No API calls were captured. The page may not have made any XHR/fetch requests during the steps, or the steps may not have triggered the expected behavior.`);
-      }
-      if (captureResult.error) {
-        lines.push(`
---- Failure ---`);
-        if (typeof captureResult.error === "string") {
-          lines.push(`Error: ${captureResult.error}`);
-        } else {
-          lines.push(`Failed at step ${captureResult.error.failedAtStep}: ${JSON.stringify(captureResult.error.failedStep)}`);
-          lines.push(`Error type: ${captureResult.error.errorType}`);
-          lines.push(`Message: ${captureResult.error.message}`);
-          if (captureResult.error.suggestion)
-            lines.push(`Suggestion: ${captureResult.error.suggestion}`);
-        }
-      }
-      const screenshotUrl = captureResult.error?.pageState?.screenshotUrl ?? captureResult.finalState?.screenshotUrl;
-      if (screenshotUrl) {
-        const filePath = await resolveScreenshotPath(screenshotUrl);
-        if (filePath) {
-          lines.push(`
-Screenshot saved: ${filePath}`);
-          lines.push("Use the Read tool on the path above to view the screenshot.");
-        }
-      }
-      if (captureResult.capturedApi && captureResult.capturedApi.length > 0) {
-        const mainDomain = captureResult.capturedApi[0]?.domain || "api";
-        const outDir = params.outputDir || `./${mainDomain}`;
-        try {
-          const fs6 = await import("fs");
-          const path8 = await import("path");
-          fs6.mkdirSync(outDir, { recursive: true });
-          const jsonPath = path8.join(outDir, "captured-api.json");
-          fs6.writeFileSync(jsonPath, JSON.stringify(captureResult.capturedApi, null, 2));
-          lines.push(`
-Full captured data saved to: ${jsonPath}`);
-          lines.push("Read this file for complete curl commands, request/response bodies, and auth data.");
-        } catch (writeErr) {
-          lines.push(`
-(Could not save captured JSON: ${writeErr instanceof Error ? writeErr.message : String(writeErr)})`);
-        }
-      }
-      const content = [{ type: "text", text: lines.join(`
-`) }];
-      if (!captureResult.ok)
-        return { content, isError: true };
-      return { content };
-    } catch (e) {
-      return err(`Connection error: ${getErrorMessage(e)}. Try \`session restart\` and retry.`);
-    }
-  });
-}
-function formatCapturedApi(lines, capturedApi, params) {
-  for (const api of capturedApi) {
-    lines.push(`
-━━━ ${api.domain} (${api.baseUrl}) ━━━`);
-    const authParts = [];
-    if (api.auth?.authorization)
-      authParts.push(`Authorization: ${api.auth.authorization.slice(0, 30)}...`);
-    if (api.auth?.cookies && Object.keys(api.auth.cookies).length > 0)
-      authParts.push(`${Object.keys(api.auth.cookies).length} cookies`);
-    if (api.auth?.tokens && Object.keys(api.auth.tokens).length > 0) {
-      for (const [k, v] of Object.entries(api.auth.tokens)) {
-        authParts.push(`${k}: ${String(v).slice(0, 30)}...`);
-      }
-    }
-    if (authParts.length > 0) {
-      lines.push(`
-Auth:`);
-      for (const part of authParts)
-        lines.push(`  ${part}`);
-    }
-    const byProtocol = new Map;
-    for (const ep of api.endpoints) {
-      const p = ep.protocol || "rest";
-      if (!byProtocol.has(p))
-        byProtocol.set(p, []);
-      byProtocol.get(p).push(ep);
-    }
-    const protocolSummary = Array.from(byProtocol.entries()).map(([p, eps]) => `${p}=${eps.length}`).join(", ");
-    lines.push(`
-Endpoints (${api.endpoints.length}) [${protocolSummary}]:`);
-    for (const ep of api.endpoints) {
-      lines.push(`
-  [${ep.protocol}/${ep.verb}] ${ep.functionName}`);
-      lines.push(`    Action: ${ep.action}`);
-      lines.push(`    ${ep.method} ${ep.path}  →  ${ep.responseStatus}`);
-      if (ep.requestBody) {
-        const body = ep.requestBody;
-        const signalKeys = extractSignalKeys(body);
-        if (signalKeys)
-          lines.push(`    Params: ${signalKeys}`);
-      }
-    }
-  }
-  const mainDomain = capturedApi[0]?.domain || "api";
-  const dir = params.outputDir || `./${mainDomain}`;
-  const ext = params.typed ? ".ts" : ".js";
-  lines.push(`
-━━━ Save instructions ━━━`);
-  lines.push(`Save to: ${dir}`);
-  lines.push(`Format: ${ext} files`);
-  const protocolsSeen = new Set;
-  for (const api of capturedApi)
-    for (const ep of api.endpoints)
-      protocolsSeen.add(ep.protocol);
-  lines.push(`
-Layout (protocols present: ${Array.from(protocolsSeen).join(", ")}):`);
-  lines.push(`  auth${ext}`);
-  if (protocolsSeen.has("rest"))
-    lines.push(`  transport/rest${ext}            — shared fetch wrapper with auth headers`);
-  if (protocolsSeen.has("graphql"))
-    lines.push(`  transport/graphql${ext}         — post(operationName|docId, variables) → shared GraphQL client`);
-  if (protocolsSeen.has("json-rpc"))
-    lines.push(`  transport/jsonRpc${ext}         — shared JSON-RPC client`);
-  if (protocolsSeen.has("grpc-web"))
-    lines.push(`  transport/grpc${ext}            — shared gRPC-web client`);
-  if (protocolsSeen.has("form-rpc"))
-    lines.push(`  transport/formRpc${ext}         — shared urlencoded RPC client`);
-  if (protocolsSeen.has("soap"))
-    lines.push(`  transport/soap${ext}            — shared SOAP client`);
-  lines.push(`  <protocol>/<verb>/<functionName>${ext}  — one file per endpoint, uses shared transport`);
-  lines.push(`    e.g. graphql/queries/<fn>${ext}, graphql/mutations/<fn>${ext}, rest/read/<fn>${ext}, rest/create/<fn>${ext}`);
-  lines.push(`  index${ext}                         — re-export all endpoint functions`);
-  if (params.typed)
-    lines.push(`  types.ts                         — interfaces inferred from response bodies`);
-  lines.push(`  README.md                        — endpoints grouped by protocol + verb, auth expiry warning`);
-  lines.push(`
-Rules:`);
-  lines.push(`  - One function per (protocol, action). Use the functionName field verbatim for the file + export name.`);
-  lines.push(`  - verb=read|list → queries/ (GraphQL) or read/ (REST). verb=create|update|delete|action → mutations/ (GraphQL) or verb dir (REST).`);
-  lines.push(`  - Each endpoint file is minimal: import transport + auth, call transport with the action id, pass variables, return typed result.`);
-  lines.push(`  - GraphQL transport signature: post(opNameOrDocId: string, variables: object). Pick doc_id when present in captured body, else operationName.`);
-  lines.push(`  - Do NOT inline auth headers per endpoint — they live in auth${ext} and the transport reads them.`);
-  lines.push(`
-IMPORTANT: Auth data contains real tokens/cookies — they expire. Remind the user.`);
-}
-function extractSignalKeys(body) {
-  const NOISE = new Set([
-    "__csr",
-    "__hsdp",
-    "__hblp",
-    "__dyn",
-    "__a",
-    "__req",
-    "__hs",
-    "__comet_req",
-    "__ccg",
-    "__spin_r",
-    "__spin_b",
-    "__spin_t",
-    "__jssesw",
-    "lsd",
-    "fb_dtsg",
-    "fb_api_caller_class",
-    "fb_api_req_friendly_name",
-    "jazoest",
-    "server_timestamps",
-    "__s",
-    "__user",
-    "dpr",
-    "__rev"
-  ]);
-  const signalEntries = [];
-  for (const [k, v] of Object.entries(body)) {
-    if (NOISE.has(k))
-      continue;
-    if (typeof v === "string" && v.length > 80) {
-      signalEntries.push(`${k}=${v.slice(0, 40)}...`);
-    } else if (typeof v === "object" && v !== null) {
-      const keys = Object.keys(v).slice(0, 5).join(",");
-      signalEntries.push(`${k}={${keys}${Object.keys(v).length > 5 ? ",..." : ""}}`);
-    } else {
-      signalEntries.push(`${k}=${String(v).slice(0, 40)}`);
-    }
-  }
-  return signalEntries.length > 0 ? signalEntries.join(", ") : null;
-}
-
 // src/mcp/tools/knowledge.ts
 var import_zod7 = require("zod");
 function registerKnowledgeTool(server) {