mcp-scraper 0.3.45 → 0.3.47

package/dist/bin/mcp-stdio-server.cjs

@@ -24,9 +24,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // bin/mcp-stdio-server.ts
-var import_node_fs5 = require("fs");
-var import_node_os5 = require("os");
-var import_node_path6 = require("path");
+var import_node_fs6 = require("fs");
+var import_node_os6 = require("os");
+var import_node_path7 = require("path");
 var import_mcp3 = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
@@ -474,7 +474,7 @@ render();
 }
 
 // src/version.ts
-var PACKAGE_VERSION = "0.3.45";
+var PACKAGE_VERSION = "0.3.47";
 
 // src/mcp/browser-agent-tool-schemas.ts
 var import_zod = require("zod");
@@ -1136,6 +1136,14 @@ function sanitizeOutboundDiagnostics(value, parentKey = "") {
   return value;
 }
 
+// src/mcp/output-schema-registry.ts
+var ADVERTISE_OUTPUT_SCHEMAS = process.env.MCP_SCRAPER_ADVERTISE_OUTPUT_SCHEMAS === "true";
+var OUTPUT_SCHEMAS = {};
+function recordOutputSchema(name, schema) {
+  OUTPUT_SCHEMAS[name] = schema;
+  return ADVERTISE_OUTPUT_SCHEMAS ? schema : void 0;
+}
+
 // src/mcp/browser-agent-mcp-server.ts
 function structuredResult(value, isError = false) {
   const safe2 = sanitizeOutboundDiagnostics(value);
@@ -1301,7 +1309,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Save a Site Login to a Profile",
       description: "Save a logged-in browser session so this server can reuse a site the user is signed into (ChatGPT, Claude, Reddit, any account-gated site). Returns a watch_url; the user signs in fresh (existing browser cookies are NOT imported) and cookies save to a named profile. ONE profile holds MANY logins \u2014 call again with the same profile and a different domain to stack another account. NOT for one-off scraping (use extract_url) or driving the browser (use browser_open). After sign-in, poll browser_profile_list until AUTHENTICATED, then browser_open with the profile.",
       inputSchema: BrowserProfileConnectInputSchema,
-      outputSchema: BrowserProfileConnectOutputSchema,
+      outputSchema: recordOutputSchema("browser_profile_connect", BrowserProfileConnectOutputSchema),
       annotations: annotations("Save a Site Login to a Profile")
     },
     async (input) => {
@@ -1359,7 +1367,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "List Saved Logins in a Profile",
       description: "List every site login saved in a profile with its auth status (NEEDS_AUTH/AUTHENTICATED), email, and note. Use to check what's connected, or to poll a just-saved login until AUTHENTICATED. Read-only, no cost. Pass profile (or email to derive it); narrow with domain or connection_id.",
       inputSchema: BrowserProfileListInputSchema,
-      outputSchema: BrowserProfileListOutputSchema,
+      outputSchema: recordOutputSchema("browser_profile_list", BrowserProfileListOutputSchema),
       annotations: annotations("List Saved Logins in a Profile", true)
     },
     async (input) => {
@@ -1393,7 +1401,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Open Browser Session",
       description: "Open a direct no-proxy hosted browser session you can drive. Pass a saved profile name to load a session already logged into that profile's sites (set one up first with browser_profile_connect). Returns a session_id used by all other browser_* tools.",
       inputSchema: BrowserOpenInputSchema,
-      outputSchema: BrowserOpenOutputSchema,
+      outputSchema: recordOutputSchema("browser_open", BrowserOpenOutputSchema),
       annotations: annotations("Open Browser Session")
     },
     async (input) => {
@@ -1427,7 +1435,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "See Page (Screenshot + Elements)",
       description: "Capture what the browser currently shows: a screenshot plus a text snapshot of interactive elements with x,y coordinates, page url/title, and visible text. 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,
+      outputSchema: recordOutputSchema("browser_screenshot", BrowserScreenshotOutputSchema),
       annotations: annotations("See Page", true)
     },
     async (input) => {
@@ -1459,7 +1467,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Read Page Text + Elements",
       description: "Return the page url, title, visible text, and interactive elements (with x,y) without an image. Cheaper than browser_screenshot when you only need to read content or find a click target.",
       inputSchema: BrowserSessionInputSchema,
-      outputSchema: BrowserReadOutputSchema,
+      outputSchema: recordOutputSchema("browser_read", BrowserReadOutputSchema),
       annotations: annotations("Read Page", true)
     },
     async (input) => {
@@ -1483,7 +1491,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Locate DOM Targets",
       description: "Locate exact visible DOM elements or text ranges and return left/top/width/height bounds in screenshot pixels. Use before drawing annotations that must circle, box, underline, or point to a real element. Prefer CSS selectors; use text when selector is unknown.",
       inputSchema: BrowserLocateInputSchema,
-      outputSchema: BrowserLocateOutputSchema,
+      outputSchema: recordOutputSchema("browser_locate", BrowserLocateOutputSchema),
       annotations: annotations("Locate DOM Targets", true)
     },
     async (input) => {
@@ -1508,7 +1516,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Navigate To URL",
       description: "Navigate an existing browser session to a URL. Use browser_open first if no session exists; follow with browser_screenshot to see the loaded page.",
       inputSchema: BrowserGotoInputSchema,
-      outputSchema: BrowserActionOutputSchema,
+      outputSchema: recordOutputSchema("browser_goto", BrowserActionOutputSchema),
       annotations: annotations("Navigate To URL")
     },
     async (input) => {
@@ -1522,7 +1530,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Click",
       description: "Click a visible page target using screenshot pixel coordinates. Use x/y only from the latest browser_screenshot, browser_read, or browser_locate result; do not guess coordinates.",
       inputSchema: BrowserClickInputSchema,
-      outputSchema: BrowserActionOutputSchema,
+      outputSchema: recordOutputSchema("browser_click", BrowserActionOutputSchema),
       annotations: annotations("Click")
     },
     async (input) => {
@@ -1541,7 +1549,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Type Text",
       description: 'Type text into the currently focused browser field. Click or Tab to the field first if focus is uncertain. Use browser_press with ["Return"] to submit.',
       inputSchema: BrowserTypeInputSchema,
-      outputSchema: BrowserActionOutputSchema,
+      outputSchema: recordOutputSchema("browser_type", BrowserActionOutputSchema),
       annotations: annotations("Type Text")
     },
     async (input) => {
@@ -1555,7 +1563,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Scroll",
       description: "Scroll the page to reveal more content. Positive delta_y scrolls down; negative scrolls up.",
       inputSchema: BrowserScrollInputSchema,
-      outputSchema: BrowserActionOutputSchema,
+      outputSchema: recordOutputSchema("browser_scroll", BrowserActionOutputSchema),
       annotations: annotations("Scroll")
     },
     async (input) => {
@@ -1574,7 +1582,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Press Keys",
       description: "Press keyboard keys or combinations in the active browser session \u2014 submit, Escape, Tab navigation, select-all, or shortcuts. Use browser_type for text entry.",
       inputSchema: BrowserPressInputSchema,
-      outputSchema: BrowserActionOutputSchema,
+      outputSchema: recordOutputSchema("browser_press", BrowserActionOutputSchema),
       annotations: annotations("Press Keys")
     },
     async (input) => {
@@ -1588,7 +1596,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Start Recording",
       description: "Start recording an MP4 replay of the session. Returns replay_id and a download_url. Stop with browser_replay_stop.",
       inputSchema: BrowserSessionInputSchema,
-      outputSchema: BrowserReplayStartOutputSchema,
+      outputSchema: recordOutputSchema("browser_replay_start", BrowserReplayStartOutputSchema),
       annotations: annotations("Start Recording")
     },
     async (input) => {
@@ -1611,7 +1619,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Stop Recording",
       description: "Stop a replay recording and expose its final view_url/download_url. Use browser_replay_download to save the MP4.",
       inputSchema: BrowserReplayStopInputSchema,
-      outputSchema: BrowserReplayStopOutputSchema,
+      outputSchema: recordOutputSchema("browser_replay_stop", BrowserReplayStopOutputSchema),
       annotations: annotations("Stop Recording")
     },
     async (input) => {
@@ -1634,7 +1642,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "List Replay Videos",
       description: "List replay recordings for a browser session, including view_url and download_url when available.",
       inputSchema: BrowserSessionInputSchema,
-      outputSchema: BrowserListReplaysOutputSchema,
+      outputSchema: recordOutputSchema("browser_list_replays", BrowserListReplaysOutputSchema),
       annotations: annotations("List Replay Videos", true)
     },
     async (input) => {
@@ -1654,9 +1662,9 @@ function registerBrowserAgentMcpTools(server2, opts) {
     "browser_replay_download",
     {
       title: "Download Replay MP4",
-      description: "Download a replay recording and save the MP4 under MCP_SCRAPER_OUTPUT_DIR/browser-replays. Use after browser_replay_stop or browser_list_replays.",
+      description: opts.savesReportsLocally === false ? "Download a replay recording. Returns the download_url; fetch it directly (nothing is saved on this hosted endpoint). Use after browser_replay_stop or browser_list_replays." : "Download a replay recording and save the MP4 under MCP_SCRAPER_OUTPUT_DIR/browser-replays. Use after browser_replay_stop or browser_list_replays.",
       inputSchema: BrowserReplayDownloadInputSchema,
-      outputSchema: BrowserReplayDownloadOutputSchema,
+      outputSchema: recordOutputSchema("browser_replay_download", BrowserReplayDownloadOutputSchema),
       annotations: annotations("Download Replay MP4")
     },
     async (input) => {
@@ -1680,7 +1688,7 @@ 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 with DOM bounds and replay-relative timing, instead of guessing start_seconds or rectangles. Pass the returned annotations to browser_replay_annotate after stopping the replay.",
       inputSchema: BrowserReplayMarkInputSchema,
-      outputSchema: BrowserReplayMarkOutputSchema,
+      outputSchema: recordOutputSchema("browser_replay_mark", BrowserReplayMarkOutputSchema),
       annotations: annotations("Mark Replay Annotation", true)
     },
     async (input) => {
@@ -1730,7 +1738,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Annotate Replay MP4",
       description: "Download a browser replay MP4, render visual annotations (circles/boxes/arrows/labels) over it, and save a new annotated MP4. Prefer annotations from browser_replay_mark for accurate timing; otherwise use exact bounds from browser_locate. Pass source_width/source_height if the replay video size differs from the screenshot coordinate space.",
       inputSchema: BrowserReplayAnnotateInputSchema,
-      outputSchema: BrowserReplayAnnotateOutputSchema,
+      outputSchema: recordOutputSchema("browser_replay_annotate", BrowserReplayAnnotateOutputSchema),
       annotations: annotations("Annotate Replay MP4")
     },
     async (input) => {
@@ -1772,7 +1780,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Close Browser Session",
       description: "Close and release a browser session when the task is done, to end active browser billing. Use browser_list_sessions first to recover a session_id.",
       inputSchema: BrowserSessionInputSchema,
-      outputSchema: BrowserCloseOutputSchema,
+      outputSchema: recordOutputSchema("browser_close", BrowserCloseOutputSchema),
       annotations: { title: "Close Browser Session", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
     },
     async (input) => {
@@ -1793,7 +1801,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "List Browser Sessions",
       description: "List browser sessions and their status, with a watch_url for each. Use to recover a session_id or decide which session to close.",
       inputSchema: BrowserListInputSchema,
-      outputSchema: BrowserListSessionsOutputSchema,
+      outputSchema: recordOutputSchema("browser_list_sessions", BrowserListSessionsOutputSchema),
       annotations: annotations("List Browser Sessions", true)
     },
     async (input) => {
@@ -1815,7 +1823,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Capture AI Search Fan-Out",
       description: "Capture the query fan-out behind a ChatGPT or Claude web-search answer for AEO: sub-queries issued, every researched URL split into cited vs browsed-only, and top sourced sites. Returns raw structured data for you to classify and analyze. Set export=true for JSON/CSV/TSV/HTML artifacts. WRITE NOTE: passing prompt submits a real message in the user's logged-in account \u2014 only send when the user wants that; omit it to capture a prompt the user just ran. The session must already be open on chatgpt.com or claude.ai (see browser_profile_connect) while the prompt streams. NOT for Google AI Overview \u2014 use harvest_paa for that.",
       inputSchema: BrowserCaptureFanoutInputSchema,
-      outputSchema: BrowserCaptureFanoutOutputSchema,
+      outputSchema: recordOutputSchema("query_fanout_workflow", BrowserCaptureFanoutOutputSchema),
       annotations: annotations("Capture AI Search Fan-Out")
     },
     async (input) => {
@@ -1869,13 +1877,14 @@ function registerBrowserAgentMcpTools(server2, opts) {
 
 // src/mcp/paa-mcp-server.ts
 var import_mcp2 = require("@modelcontextprotocol/sdk/server/mcp.js");
-var import_node_fs4 = require("fs");
-var import_node_path5 = require("path");
+var import_node_fs5 = require("fs");
+var import_node_path6 = require("path");
+var import_node_crypto2 = require("crypto");
 
 // src/mcp/mcp-response-formatter.ts
-var import_node_fs3 = require("fs");
-var import_node_os4 = require("os");
-var import_node_path4 = require("path");
+var import_node_fs4 = require("fs");
+var import_node_os5 = require("os");
+var import_node_path5 = require("path");
 
 // src/mcp/workflow-catalog.ts
 var WORKFLOW_RECIPES = [
@@ -2412,7 +2421,129 @@ function renderImageSection(audit) {
   return lines.join("\n");
 }
 
+// src/mcp/report-artifact-offload.ts
+var import_node_crypto = require("crypto");
+
+// src/api/blob-store.ts
+var import_node_fs3 = require("fs");
+var import_node_os4 = require("os");
+var import_node_path4 = require("path");
+function byteLength(data) {
+  return Buffer.isBuffer(data) ? data.length : Buffer.byteLength(data);
+}
+var LocalBlobStore = class {
+  constructor(baseDir) {
+    this.baseDir = baseDir;
+  }
+  baseDir;
+  kind = "local";
+  async put(key, data, contentType = "application/octet-stream") {
+    const path = (0, import_node_path4.join)(this.baseDir, "blobs", key);
+    (0, import_node_fs3.mkdirSync)((0, import_node_path4.dirname)(path), { recursive: true });
+    (0, import_node_fs3.writeFileSync)(path, data);
+    return { key, url: `file://${path}`, bytes: byteLength(data), contentType };
+  }
+  async get(key) {
+    const path = (0, import_node_path4.join)(this.baseDir, "blobs", key);
+    try {
+      const { readFileSync: readFileSync3 } = await import("fs");
+      return readFileSync3(path);
+    } catch {
+      return null;
+    }
+  }
+};
+function localBaseDir() {
+  return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path4.join)((0, import_node_os4.homedir)(), "Downloads", "mcp-scraper");
+}
+var cached = null;
+function getBlobStore() {
+  if (cached) return cached;
+  if (process.env.BLOB_READ_WRITE_TOKEN) {
+    cached = new VercelBlobStore(process.env.BLOB_READ_WRITE_TOKEN);
+  } else {
+    cached = new LocalBlobStore(localBaseDir());
+  }
+  return cached;
+}
+var VercelBlobStore = class {
+  constructor(token) {
+    this.token = token;
+  }
+  token;
+  kind = "vercel-blob";
+  async put(key, data, contentType = "application/octet-stream") {
+    const { put } = await import("@vercel/blob");
+    const body = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    const result = await put(key, body, {
+      access: "public",
+      token: this.token,
+      contentType,
+      addRandomSuffix: true
+    });
+    return { key, url: result.url, bytes: byteLength(data), contentType };
+  }
+  async get(key) {
+    try {
+      const { list } = await import("@vercel/blob");
+      const res = await list({ prefix: key, token: this.token, limit: 1 });
+      const match = res.blobs.find((b) => b.pathname === key || b.pathname.startsWith(key));
+      if (!match) return null;
+      const resp = await fetch(match.url);
+      if (!resp.ok) return null;
+      return Buffer.from(await resp.arrayBuffer());
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/mcp/report-artifact-offload.ts
+var REPORT_BLOB_TTL_MS = 24 * 60 * 60 * 1e3;
+var REPORT_BLOB_PREFIX = "mcp-reports/";
+var PREVIEW_CHARS = 2e3;
+var ARTIFACT_OFFLOAD_ENABLED = process.env.MCP_SCRAPER_ARTIFACT_OFFLOAD !== "false";
+async function offloadReport(toolName, ownerId, report) {
+  const timestamp = Date.now();
+  const random = (0, import_node_crypto.randomBytes)(6).toString("hex");
+  const key = `${REPORT_BLOB_PREFIX}${ownerId}/${toolName}/${timestamp}-${random}.md`;
+  const stored = await getBlobStore().put(key, report, "text/markdown");
+  return {
+    artifactId: stored.key,
+    bytes: stored.bytes,
+    expiresAt: new Date(timestamp + REPORT_BLOB_TTL_MS).toISOString(),
+    preview: report.slice(0, PREVIEW_CHARS)
+  };
+}
+function artifactOwnerId(artifactId) {
+  if (!artifactId.startsWith(REPORT_BLOB_PREFIX)) return null;
+  const rest = artifactId.slice(REPORT_BLOB_PREFIX.length);
+  const segment = rest.split("/")[0];
+  return segment || null;
+}
+async function readArtifactWindow(artifactId, offset, maxBytes) {
+  const buf = await getBlobStore().get(artifactId);
+  if (!buf) return null;
+  const totalBytes = buf.length;
+  const start = Math.max(0, offset);
+  const end = Math.min(totalBytes, start + maxBytes);
+  const slice = buf.subarray(start, end);
+  const nextOffset = end < totalBytes ? end : null;
+  return { text: slice.toString("utf8"), totalBytes, nextOffset };
+}
+function summaryEnvelope(executiveSummary, offloaded) {
+  return [
+    executiveSummary.trim(),
+    "",
+    "--- Full report stored as artifact ---",
+    `artifactId: ${offloaded.artifactId} \xB7 ${offloaded.bytes} bytes \xB7 expires ${offloaded.expiresAt}`,
+    "Read it with report_artifact_read (supports offset/maxBytes windowing)."
+  ].join("\n");
+}
+
 // src/mcp/mcp-response-formatter.ts
+var INLINE_BUDGET_BYTES = Number(process.env.MCP_SCRAPER_INLINE_BUDGET ?? 5e4);
+var STRUCTURED_ARRAY_CAP = 25;
 var reportSavingEnabled = true;
 function sanitizeVendorText(text) {
   return sanitizeVendorName(
@@ -2427,16 +2558,16 @@ function reportTitle(full) {
   return title?.replace(/^#\s+/, "").trim() || "MCP Scraper Report";
 }
 function outputBaseDir3() {
-  return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path4.join)((0, import_node_os4.homedir)(), "Downloads", "mcp-scraper");
+  return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path5.join)((0, import_node_os5.homedir)(), "Downloads", "mcp-scraper");
 }
 function saveFullReport(full) {
   if (!reportSavingEnabled || process.env.MCP_SCRAPER_SAVE_REPORTS === "false") return null;
   const outDir = outputBaseDir3();
   try {
-    (0, import_node_fs3.mkdirSync)(outDir, { recursive: true });
+    (0, import_node_fs4.mkdirSync)(outDir, { recursive: true });
     const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const file = (0, import_node_path4.join)(outDir, `${stamp}-${slugifyReportName(reportTitle(full))}.md`);
-    (0, import_node_fs3.writeFileSync)(file, full, "utf8");
+    const file = (0, import_node_path5.join)(outDir, `${stamp}-${slugifyReportName(reportTitle(full))}.md`);
+    (0, import_node_fs4.writeFileSync)(file, full, "utf8");
     return file;
   } catch {
     return null;
@@ -2451,9 +2582,9 @@ function saveBulkSite(siteUrl, pages, seo, imageAudit) {
   if (!reportSavingActive()) return null;
   try {
     const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const dir = (0, import_node_path4.join)(outputBaseDir3(), `extract-${slugifyReportName(siteUrl)}-${stamp}`);
-    const pagesDir = (0, import_node_path4.join)(dir, "pages");
-    (0, import_node_fs3.mkdirSync)(pagesDir, { recursive: true });
+    const dir = (0, import_node_path5.join)(outputBaseDir3(), `extract-${slugifyReportName(siteUrl)}-${stamp}`);
+    const pagesDir = (0, import_node_path5.join)(dir, "pages");
+    (0, import_node_fs4.mkdirSync)(pagesDir, { recursive: true });
     const indexRows = pages.map((p, i) => {
       const num = String(i + 1).padStart(4, "0");
       const slug = slugifyReportName(p.url.replace(/^https?:\/\//, "")).slice(0, 60) || "page";
@@ -2467,7 +2598,7 @@ function saveBulkSite(siteUrl, pages, seo, imageAudit) {
         "",
         body || "_(no content extracted)_"
       ].filter(Boolean).join("\n");
-      (0, import_node_fs3.writeFileSync)((0, import_node_path4.join)(pagesDir, fname), content, "utf8");
+      (0, import_node_fs4.writeFileSync)((0, import_node_path5.join)(pagesDir, fname), content, "utf8");
       return `| ${i + 1} | ${cell(p.title ?? "Untitled")} | ${p.url} | pages/${fname} |`;
     });
     const dataFilesSection = seo ? [
@@ -2499,40 +2630,40 @@ function saveBulkSite(siteUrl, pages, seo, imageAudit) {
 |---|-------|-----|------|
 ${indexRows.join("\n")}`
     ].filter(Boolean).join("\n");
-    const indexFile = (0, import_node_path4.join)(dir, "index.md");
-    (0, import_node_fs3.writeFileSync)(indexFile, index, "utf8");
+    const indexFile = (0, import_node_path5.join)(dir, "index.md");
+    (0, import_node_fs4.writeFileSync)(indexFile, index, "utf8");
     let seoFiles;
     if (seo) {
       const toJsonl = (rows) => rows.map((r) => JSON.stringify(r)).join("\n");
-      const pagesJsonl = (0, import_node_path4.join)(dir, "pages.jsonl");
-      const linksJsonl = (0, import_node_path4.join)(dir, "links.jsonl");
-      const metricsJsonl = (0, import_node_path4.join)(dir, "link-metrics.jsonl");
-      const issuesFile = (0, import_node_path4.join)(dir, "issues.json");
-      const reportFile = (0, import_node_path4.join)(dir, "report.md");
-      (0, import_node_fs3.writeFileSync)(pagesJsonl, toJsonl(seo.pageRows), "utf8");
-      (0, import_node_fs3.writeFileSync)(linksJsonl, toJsonl(seo.edges), "utf8");
-      (0, import_node_fs3.writeFileSync)(metricsJsonl, toJsonl(seo.metrics), "utf8");
-      (0, import_node_fs3.writeFileSync)(issuesFile, JSON.stringify(seo.issues, null, 2), "utf8");
-      (0, import_node_fs3.writeFileSync)(reportFile, seo.reportMd + (imageAudit ? `
+      const pagesJsonl = (0, import_node_path5.join)(dir, "pages.jsonl");
+      const linksJsonl = (0, import_node_path5.join)(dir, "links.jsonl");
+      const metricsJsonl = (0, import_node_path5.join)(dir, "link-metrics.jsonl");
+      const issuesFile = (0, import_node_path5.join)(dir, "issues.json");
+      const reportFile = (0, import_node_path5.join)(dir, "report.md");
+      (0, import_node_fs4.writeFileSync)(pagesJsonl, toJsonl(seo.pageRows), "utf8");
+      (0, import_node_fs4.writeFileSync)(linksJsonl, toJsonl(seo.edges), "utf8");
+      (0, import_node_fs4.writeFileSync)(metricsJsonl, toJsonl(seo.metrics), "utf8");
+      (0, import_node_fs4.writeFileSync)(issuesFile, JSON.stringify(seo.issues, null, 2), "utf8");
+      (0, import_node_fs4.writeFileSync)(reportFile, seo.reportMd + (imageAudit ? `
 
 ${renderImageSection(imageAudit)}` : ""), "utf8");
-      const linkReportFile = (0, import_node_path4.join)(dir, "link-report.md");
-      const linksSummaryFile = (0, import_node_path4.join)(dir, "links-summary.json");
-      const externalDomainsFile = (0, import_node_path4.join)(dir, "external-domains.json");
-      (0, import_node_fs3.writeFileSync)(linkReportFile, renderLinkReport(seo.linkReport), "utf8");
-      (0, import_node_fs3.writeFileSync)(linksSummaryFile, JSON.stringify(seo.linkReport.summary, null, 2), "utf8");
-      (0, import_node_fs3.writeFileSync)(externalDomainsFile, JSON.stringify(seo.linkReport.externalDomains, null, 2), "utf8");
+      const linkReportFile = (0, import_node_path5.join)(dir, "link-report.md");
+      const linksSummaryFile = (0, import_node_path5.join)(dir, "links-summary.json");
+      const externalDomainsFile = (0, import_node_path5.join)(dir, "external-domains.json");
+      (0, import_node_fs4.writeFileSync)(linkReportFile, renderLinkReport(seo.linkReport), "utf8");
+      (0, import_node_fs4.writeFileSync)(linksSummaryFile, JSON.stringify(seo.linkReport.summary, null, 2), "utf8");
+      (0, import_node_fs4.writeFileSync)(externalDomainsFile, JSON.stringify(seo.linkReport.externalDomains, null, 2), "utf8");
       seoFiles = [pagesJsonl, linksJsonl, metricsJsonl, issuesFile, reportFile, linkReportFile, linksSummaryFile, externalDomainsFile];
       if (imageAudit) {
-        const imagesJsonl = (0, import_node_path4.join)(dir, "images.jsonl");
-        const imagesSummary = (0, import_node_path4.join)(dir, "images-summary.json");
-        (0, import_node_fs3.writeFileSync)(imagesJsonl, imageAudit.rows.map((r) => JSON.stringify(r)).join("\n"), "utf8");
-        (0, import_node_fs3.writeFileSync)(imagesSummary, JSON.stringify(imageAudit.summary, null, 2), "utf8");
+        const imagesJsonl = (0, import_node_path5.join)(dir, "images.jsonl");
+        const imagesSummary = (0, import_node_path5.join)(dir, "images-summary.json");
+        (0, import_node_fs4.writeFileSync)(imagesJsonl, imageAudit.rows.map((r) => JSON.stringify(r)).join("\n"), "utf8");
+        (0, import_node_fs4.writeFileSync)(imagesSummary, JSON.stringify(imageAudit.summary, null, 2), "utf8");
         seoFiles.push(imagesJsonl, imagesSummary);
       }
       if (seo.branding) {
-        const brandingFile = (0, import_node_path4.join)(dir, "branding.json");
-        (0, import_node_fs3.writeFileSync)(brandingFile, JSON.stringify(seo.branding, null, 2), "utf8");
+        const brandingFile = (0, import_node_path5.join)(dir, "branding.json");
+        (0, import_node_fs4.writeFileSync)(brandingFile, JSON.stringify(seo.branding, null, 2), "utf8");
         seoFiles.push(brandingFile);
       }
     }
@@ -2545,12 +2676,12 @@ function saveUrlInventory(siteUrl, urls) {
   if (!reportSavingActive()) return null;
   try {
     const outDir = outputBaseDir3();
-    (0, import_node_fs3.mkdirSync)(outDir, { recursive: true });
+    (0, import_node_fs4.mkdirSync)(outDir, { recursive: true });
     const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const file = (0, import_node_path4.join)(outDir, `${stamp}-urlmap-${slugifyReportName(siteUrl.replace(/^https?:\/\//, ""))}.csv`);
+    const file = (0, import_node_path5.join)(outDir, `${stamp}-urlmap-${slugifyReportName(siteUrl.replace(/^https?:\/\//, ""))}.csv`);
     const csv = (v) => /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
     const rows = ["url,status", ...urls.map((u) => `${csv(u.url)},${u.status ?? ""}`)];
-    (0, import_node_fs3.writeFileSync)(file, rows.join("\n"), "utf8");
+    (0, import_node_fs4.writeFileSync)(file, rows.join("\n"), "utf8");
     return file;
   } catch {
     return null;
@@ -2559,12 +2690,12 @@ function saveUrlInventory(siteUrl, urls) {
 function persistScreenshotLocally(base64, url) {
   if (!reportSavingEnabled || process.env.MCP_SCRAPER_SAVE_REPORTS === "false") return null;
   try {
-    const dir = (0, import_node_path4.join)(outputBaseDir3(), "screenshots");
-    (0, import_node_fs3.mkdirSync)(dir, { recursive: true });
+    const dir = (0, import_node_path5.join)(outputBaseDir3(), "screenshots");
+    (0, import_node_fs4.mkdirSync)(dir, { recursive: true });
     const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
     const slug = url.replace(/^https?:\/\//, "").replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "").slice(0, 60);
-    const filePath = (0, import_node_path4.join)(dir, `${stamp}-${slug}.png`);
-    (0, import_node_fs3.writeFileSync)(filePath, Buffer.from(base64, "base64"));
+    const filePath = (0, import_node_path5.join)(dir, `${stamp}-${slug}.png`);
+    (0, import_node_fs4.writeFileSync)(filePath, Buffer.from(base64, "base64"));
     return filePath;
   } catch {
     return null;
@@ -2577,6 +2708,20 @@ function oneBlock(content, diskContent) {
 \u{1F4C4} Saved: \`${filePath}\`` : content;
   return { content: [{ type: "text", text }] };
 }
+async function maybeOffload(toolName, ctx, fullText, summaryText, structuredContent) {
+  if (!ctx?.hosted || !ARTIFACT_OFFLOAD_ENABLED) return null;
+  const bytes = Buffer.byteLength(fullText);
+  if (bytes <= INLINE_BUDGET_BYTES) return null;
+  const offloaded = await offloadReport(toolName, ctx.ownerId, fullText);
+  return {
+    content: [{ type: "text", text: summaryEnvelope(summaryText, offloaded) }],
+    structuredContent: { ...structuredContent, artifact: offloaded }
+  };
+}
+function capArray(items, cap) {
+  if (items.length <= cap) return { items };
+  return { items: items.slice(0, cap), truncatedCount: items.length - cap };
+}
 function workflowRecipeTable(recipes) {
   if (!recipes.length) return "";
   return [
@@ -2928,7 +3073,7 @@ ${headingSection}${kpoSection}${brandingSection}${bodySectionFull}${memSection}$
   }
   return { ...textResult, structuredContent };
 }
-function formatMapSiteUrls(raw, input) {
+async function formatMapSiteUrls(raw, input, ctx) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
   const d = parsed.data;
@@ -2969,20 +3114,28 @@ ${broken.map((u) => `- ${u.url} (${u.status})`).join("\n")}` : "",
 - Extract content from all pages: use \`extract_site\`
 - Scrape a single page: use \`extract_url\``
   ].filter(Boolean).join("\n");
-  return {
-    ...oneBlock(full),
-    structuredContent: {
-      startUrl: d.startUrl ?? input.url,
-      totalFound: d.totalFound ?? urls.length,
-      truncated: d.truncated === true,
-      okCount: ok.length,
-      redirectCount: redirects.length,
-      brokenCount: broken.length,
-      inventoryFile: inventoryFile ?? null,
-      urls: urls.map((u) => ({ url: u.url, status: u.status ?? null })),
-      durationMs: d.durationMs ?? 0
-    }
+  const structuredContent = {
+    startUrl: d.startUrl ?? input.url,
+    totalFound: d.totalFound ?? urls.length,
+    truncated: d.truncated === true,
+    okCount: ok.length,
+    redirectCount: redirects.length,
+    brokenCount: broken.length,
+    inventoryFile: inventoryFile ?? null,
+    urls: urls.map((u) => ({ url: u.url, status: u.status ?? null })),
+    durationMs: d.durationMs ?? 0
   };
+  const summary = `# URL Map: ${input.url}
+**${d.totalFound} URLs** \xB7 ${(d.durationMs / 1e3).toFixed(1)}s
+
+## Summary
+- 2xx: ${ok.length}
+- 3xx: ${redirects.length}
+- 4xx+: ${broken.length}`;
+  const capped = capArray(structuredContent.urls, STRUCTURED_ARRAY_CAP);
+  const offloaded = await maybeOffload("map_site_urls", ctx, full, summary, { ...structuredContent, urls: capped.items, truncatedCount: capped.truncatedCount });
+  if (offloaded) return offloaded;
+  return { ...oneBlock(full), structuredContent };
 }
 function buildSeoExport(siteUrl, pages, branding) {
   const { edges, metrics } = buildLinkGraph(pages, siteUrl);
@@ -3002,7 +3155,7 @@ function buildSeoExport(siteUrl, pages, branding) {
     branding: branding ?? void 0
   };
 }
-function formatExtractSite(raw, input) {
+async function formatExtractSite(raw, input, ctx) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
   const d = parsed.data;
@@ -3037,6 +3190,36 @@ function formatExtractSite(raw, input) {
       schemaTypes: schemaTypesOf(p)
     })));
     const preview = pages.slice(0, BULK_PAGE_THRESHOLD).map(pageRow).join("\n");
+    const summaryHeader = [
+      `# Site Extract: ${input.url}`,
+      durationLine,
+      `
+## Pages (first ${Math.min(BULK_PAGE_THRESHOLD, pages.length)} of ${pages.length})
+| # | Title | URL | Schema |
+|---|-------|-----|--------|
+${preview}`
+    ].join("\n");
+    if (!bulk && ctx?.hosted) {
+      const pageDetails2 = pages.map((p, i) => {
+        const body = (p.bodyMarkdown ?? "").trim();
+        return [
+          `
+## ${i + 1}. ${p.title ?? "Untitled"}`,
+          `- **URL:** ${p.url}`,
+          p.metaDescription ? `- **Description:** ${p.metaDescription}` : "",
+          body ? `
+${body}` : "_(no content extracted)_"
+        ].filter(Boolean).join("\n");
+      }).join("\n");
+      const fullForOffload = `${summaryHeader}
+
+---
+# Full Page Content
+${pageDetails2}${tips}`;
+      const capped = capArray(structuredContent.pages, STRUCTURED_ARRAY_CAP);
+      const offloaded = await maybeOffload("extract_site", ctx, fullForOffload, `${summaryHeader}${tips}`, { ...structuredContent, pages: capped.items, truncatedCount: capped.truncatedCount });
+      if (offloaded) return offloaded;
+    }
     const location = bulk ? `
 ## \u{1F4C1} Bulk scrape saved
 - **Folder:** \`${bulk.dir}\` \u2190 all scraped page content is here
@@ -3089,7 +3272,7 @@ ${body}` : "_(no content extracted)_"
 ${pageDetails}${tips}`;
   return { ...oneBlock(full, diskReport), structuredContent };
 }
-async function formatAuditSite(raw, input) {
+async function formatAuditSite(raw, input, ctx) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
   const d = parsed.data;
@@ -3120,6 +3303,24 @@ async function formatAuditSite(raw, input) {
     images: { unique: img.unique, totalBytes: img.totalBytes, over100kb: img.over100kb, legacyFormat: img.legacyFormat },
     links: { internal: lr.internal.totalLinks, external: lr.external.totalLinks, orphans: lr.internal.orphans, brokenInternal: lr.internal.brokenInternal, externalDomains: lr.external.uniqueDomains }
   };
+  const summary = [
+    `# Technical SEO Audit: ${input.url}`,
+    durationLine,
+    `
+## Top issues
+${topIssues || "_none found_"}`,
+    `
+## Links
+${linkLine}`,
+    `
+## Images
+${imgLine}`
+  ].join("\n");
+  if (!bulk && ctx?.hosted) {
+    const fullForOffload = [summary, "\n---\n# Full Audit Report", seo.reportMd, renderImageSection(imageAudit), renderLinkReport(seo.linkReport)].join("\n");
+    const offloaded = await maybeOffload("audit_site", ctx, fullForOffload, summary, structuredContent);
+    if (offloaded) return offloaded;
+  }
   const location = bulk ? `
 ## \u{1F4C1} Technical audit saved
 - **Folder:** \`${bulk.dir}\` \u2190 full audit + page content here
@@ -3890,7 +4091,7 @@ ${rows}`,
     }
   };
 }
-function formatDirectoryWorkflow(raw, input) {
+async function formatDirectoryWorkflow(raw, input, ctx) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
   const d = parsed.data;
@@ -3942,26 +4143,29 @@ ${businessRows}` : null,
     durationMs != null ? `
 *Completed in ${(durationMs / 1e3).toFixed(1)}s*` : null
   ].filter(Boolean).join("\n");
-  return {
-    ...oneBlock(full),
-    structuredContent: {
-      query: d.query,
-      state: d.state,
-      minPopulation: d.minPopulation,
-      populationYear: d.populationYear,
-      maxResultsPerCity: d.maxResultsPerCity,
-      concurrency: d.concurrency,
-      censusSourceUrl: d.censusSourceUrl,
-      usZipsSourcePath: d.usZipsSourcePath ?? null,
-      warnings,
-      extractedAt: d.extractedAt,
-      selectedCityCount: d.selectedCityCount,
-      totalResultCount,
-      csvPath,
-      cities,
-      durationMs: durationMs ?? 0
-    }
+  const structuredContent = {
+    query: d.query,
+    state: d.state,
+    minPopulation: d.minPopulation,
+    populationYear: d.populationYear,
+    maxResultsPerCity: d.maxResultsPerCity,
+    concurrency: d.concurrency,
+    censusSourceUrl: d.censusSourceUrl,
+    usZipsSourcePath: d.usZipsSourcePath ?? null,
+    warnings,
+    extractedAt: d.extractedAt,
+    selectedCityCount: d.selectedCityCount,
+    totalResultCount,
+    csvPath,
+    cities,
+    durationMs: durationMs ?? 0
   };
+  const summary = `# Directory Workflow: ${input.query}
+**Markets:** ${cities.length} \xB7 **Maps results:** ${totalResultCount} \xB7 **State:** ${d.state ?? input.state ?? "US"}`;
+  const capped = capArray(cities, STRUCTURED_ARRAY_CAP);
+  const offloaded = await maybeOffload("directory_workflow", ctx, full, summary, { ...structuredContent, cities: capped.items, truncatedCount: capped.truncatedCount });
+  if (offloaded) return offloaded;
+  return { ...oneBlock(full), structuredContent };
 }
 function formatMapsPlaceIntel(raw, input) {
   const parsed = parseData(raw);
@@ -4483,9 +4687,13 @@ ${rows}` : ""
 }
 
 // src/mcp/server-instructions.ts
-var SERVER_INSTRUCTIONS = `
+function serverInstructions(savesReportsLocally) {
+  const reportLine = savesReportsLocally ? "All report-producing tools also save a full Markdown report to disk." : "On this hosted endpoint, small reports return inline; large reports are stored as artifacts \u2014 read them back with report_artifact_read.";
+  return `
 # MCP Scraper
 
+${reportLine}
+
 Scrapes and analyzes web, search, maps, social, and site data. **Pick a tool by NAME from the map
 below, then load its schema before calling.** Where a tool needs a value another tool produces, the
 seam is noted so you can chain them.
@@ -4569,9 +4777,11 @@ Multi-step orchestrations \u2014 prefer these over hand-chaining primitives when
   sites. It returns a saved folder/artifact plus a summary, not the full content inline.
 - Browser sessions and media transcription cost credits and take longer \u2014 prefer the cheapest tool that
   answers the question (plain search/extract before browser agents).
-- Large results are saved to disk or an artifact and returned as a summary plus a path; read the path for
-  full detail rather than expecting the whole payload inline.
+- Large results are saved to disk or an artifact and returned as a summary plus a path or artifactId;
+  read it back for full detail rather than expecting the whole payload inline.
 `.trim();
+}
+var SERVER_INSTRUCTIONS = serverInstructions(true);
 
 // src/mcp/mcp-tool-schemas.ts
 var import_zod3 = require("zod");
@@ -4744,7 +4954,7 @@ var RedditThreadInputSchema = {
 var VideoFrameAnalysisInputSchema = {
   sourceUrl: import_zod3.z.string().min(1).describe("A DIRECT video file URL (.mp4/.webm/.mov). Not a YouTube/Facebook/Instagram page URL \u2014 resolve those to a direct media URL first. Videos up to 30 minutes are supported."),
   intervalS: import_zod3.z.number().min(1).max(30).optional().describe("Preferred seconds between sampled frames (1-30, default 2). Automatically widened for long videos so the whole duration is covered within the frame budget."),
-  maxFrames: import_zod3.z.number().int().min(1).max(120).optional().describe("Max frames analyzed (<=120, default 120). Frames are spread evenly across the whole video."),
+  maxFrames: import_zod3.z.number().int().min(1).max(480).optional().describe("Max frames analyzed (<=480, default 120). $1 per 120 frames requested \u2014 120=$1 \u2026 480=$4 \u2014 automatically refunded down if the video cannot use them (minimum 1s between frames). Frames are spread evenly across the whole video."),
   detail: import_zod3.z.enum(["fast", "standard", "deep"]).optional().describe("Analysis depth. Default standard."),
   vault: import_zod3.z.string().min(1).optional().describe('Memory vault to save the finished breakdown into. Default "Library".')
 };
@@ -4819,12 +5029,18 @@ var DirectoryWorkflowInputSchema = {
   maxResultsPerCity: import_zod3.z.number().int().min(1).max(50).default(50).describe("Google Maps candidates to collect per city."),
   concurrency: import_zod3.z.number().int().min(1).max(5).default(5).describe("City Maps searches to run in parallel."),
   includeZipGroups: import_zod3.z.boolean().default(true).describe("Attach ZIP groups from a configured US ZIPS CSV when available (MCP_SCRAPER_USZIPS_CSV_PATH or usZipsCsvPath)."),
-  usZipsCsvPath: import_zod3.z.string().optional().describe("Local/test-only path to a US ZIPS CSV (state_abbr, zipcode, county, city columns). Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead."),
+  usZipsCsvPath: import_zod3.z.string().optional().describe("Local/test-only path to a US ZIPS CSV (state_abbr, zipcode, county, city columns). Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead. For ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the server, or pass this in local/test mode."),
   saveCsv: import_zod3.z.boolean().default(true).describe("Save a directory-ready CSV of results to the MCP Scraper output directory and return its path."),
   proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE).describe("Proxy targeting per city search. Defaults to location (city/ZIP-group residential targeting); configured forces the service proxy; none is local debugging only."),
   proxyZip: import_zod3.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting; normally omitted."),
   debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics.")
 };
+var ArtifactPointerOutputSchema = import_zod3.z.object({
+  artifactId: import_zod3.z.string(),
+  bytes: import_zod3.z.number().int().min(0),
+  expiresAt: import_zod3.z.string(),
+  preview: import_zod3.z.string()
+});
 var RankTrackerModeSchema = import_zod3.z.enum(["maps", "organic", "ai_overview", "paa"]);
 var RankTrackerBlueprintInputSchema = {
   projectName: import_zod3.z.string().min(1).optional().describe("Optional name for the rank tracker project, client, or campaign."),
@@ -4938,7 +5154,9 @@ var DirectoryWorkflowOutputSchema = {
     attempts: import_zod3.z.array(MapsSearchAttemptOutput),
     results: import_zod3.z.array(DirectoryMapsBusinessOutput)
   })),
-  durationMs: import_zod3.z.number().int().min(0)
+  durationMs: import_zod3.z.number().int().min(0),
+  truncatedCount: import_zod3.z.number().int().min(0).optional(),
+  artifact: ArtifactPointerOutputSchema.optional()
 };
 var RankTrackerToolPlanOutput = import_zod3.z.object({
   tool: import_zod3.z.string(),
@@ -5058,7 +5276,9 @@ var ExtractSiteOutputSchema = {
     title: NullableString2,
     schemaTypes: import_zod3.z.array(import_zod3.z.string())
   })),
-  durationMs: import_zod3.z.number().min(0)
+  durationMs: import_zod3.z.number().min(0),
+  truncatedCount: import_zod3.z.number().int().min(0).optional(),
+  artifact: ArtifactPointerOutputSchema.optional()
 };
 var AuditSiteOutputSchema = {
   url: import_zod3.z.string(),
@@ -5078,7 +5298,8 @@ var AuditSiteOutputSchema = {
     orphans: import_zod3.z.number().int().min(0),
     brokenInternal: import_zod3.z.number().int().min(0),
     externalDomains: import_zod3.z.number().int().min(0)
-  })
+  }),
+  artifact: ArtifactPointerOutputSchema.optional()
 };
 var MapsPlaceIntelOutputSchema = {
   name: import_zod3.z.string(),
@@ -5150,7 +5371,9 @@ var MapSiteUrlsOutputSchema = {
     url: import_zod3.z.string(),
     status: import_zod3.z.number().int().nullable()
   })),
-  durationMs: import_zod3.z.number().min(0)
+  durationMs: import_zod3.z.number().min(0),
+  truncatedCount: import_zod3.z.number().int().min(0).optional(),
+  artifact: ArtifactPointerOutputSchema.optional()
 };
 var YoutubeHarvestOutputSchema = {
   mode: import_zod3.z.string(),
@@ -5194,7 +5417,12 @@ var VideoFrameAnalysisStatusOutputSchema = {
   frameCount: import_zod3.z.number().int().nullable().optional(),
   artifactPath: NullableString2,
   report: NullableString2,
-  error: NullableString2
+  error: NullableString2,
+  reconciliation: import_zod3.z.object({
+    billedMc: import_zod3.z.number().int(),
+    refundedMc: import_zod3.z.number().int(),
+    effectiveFrames: import_zod3.z.number().int().nullable()
+  }).nullable().optional()
 };
 var RedditThreadOutputSchema = {
   sourceUrl: NullableString2,
@@ -5582,6 +5810,17 @@ var CaptureSerpPageSnapshotsInputSchema = {
   timeoutMs: import_zod3.z.number().int().min(1e3).max(6e4).default(15e3).describe("Per-page capture timeout in milliseconds; timeouts return as structured capture failures."),
   debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics.")
 };
+var ReportArtifactReadInputSchema = {
+  artifactId: import_zod3.z.string().min(1).describe("Artifact id returned inline by a tool whose result was too large to inline. Use only a returned artifactId; do not construct one yourself."),
+  offset: import_zod3.z.number().int().min(0).default(0).describe("Byte offset to start reading from. Pass the previous call's nextOffset to continue."),
+  maxBytes: import_zod3.z.number().int().min(1e3).max(1e5).default(2e4).describe("Maximum bytes of artifact text to return in this window.")
+};
+var ReportArtifactReadOutputSchema = {
+  artifactId: import_zod3.z.string(),
+  text: import_zod3.z.string(),
+  totalBytes: import_zod3.z.number().int().min(0),
+  nextOffset: import_zod3.z.number().int().min(0).nullable()
+};
 
 // src/mcp/rank-tracker-blueprint.ts
 var DEFAULT_MODES = ["maps", "organic", "ai_overview", "paa"];
@@ -5919,16 +6158,16 @@ function liveWebToolAnnotations(title) {
 function registerSerpIntelligenceCaptureTools(server2, executor) {
   server2.registerTool("capture_serp_snapshot", {
     title: "SERP Intelligence Snapshot",
-    description: "Capture a structured SERP Intelligence Google snapshot (the product capture path used by Phoenix). Split query from location; leave proxyMode unset.",
+    description: "Capture a structured SERP Intelligence snapshot of a Google query \u2014 the persistent evidence format used by rank-tracking and comparison pipelines. Split query from location; leave proxyMode unset.",
     inputSchema: CaptureSerpSnapshotInputSchema,
-    outputSchema: CaptureSerpSnapshotOutputSchema,
+    outputSchema: recordOutputSchema("capture_serp_snapshot", CaptureSerpSnapshotOutputSchema),
     annotations: liveWebToolAnnotations("SERP Intelligence Snapshot")
   }, async (input) => formatCaptureSerpSnapshot(await executor.captureSerpSnapshot(input), input));
   server2.registerTool("capture_serp_page_snapshots", {
     title: "SERP Intelligence Page Snapshots",
-    description: "Capture public ranking-page evidence as SERP Intelligence page snapshots (the product path used by Phoenix). Provide urls, or targets to preserve source metadata. Private IPs, localhost, file, and internal URLs are rejected.",
+    description: "Capture public ranking pages as SERP Intelligence page snapshots \u2014 persistent page evidence linked to a captured SERP. Provide urls, or targets to preserve source metadata. Private IPs, localhost, file, and internal URLs are rejected.",
     inputSchema: CaptureSerpPageSnapshotsInputSchema,
-    outputSchema: CaptureSerpPageSnapshotsOutputSchema,
+    outputSchema: recordOutputSchema("capture_serp_page_snapshots", CaptureSerpPageSnapshotsOutputSchema),
     annotations: liveWebToolAnnotations("SERP Intelligence Page Snapshots")
   }, async (input) => formatCaptureSerpPageSnapshots(await executor.captureSerpPageSnapshots(input), input));
 }
@@ -5944,7 +6183,7 @@ function localPlanningToolAnnotations(title) {
 function listSavedReports() {
   try {
     const dir = outputBaseDir3();
-    return (0, import_node_fs4.readdirSync)(dir).filter((f) => f.endsWith(".md")).map((f) => ({ filename: f, mtimeMs: (0, import_node_fs4.statSync)((0, import_node_path5.join)(dir, f)).mtimeMs })).sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, 100);
+    return (0, import_node_fs5.readdirSync)(dir).filter((f) => f.endsWith(".md")).map((f) => ({ filename: f, mtimeMs: (0, import_node_fs5.statSync)((0, import_node_path6.join)(dir, f)).mtimeMs })).sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, 100);
   } catch {
     return [];
   }
@@ -5968,233 +6207,254 @@ function registerSavedReportResources(server2) {
     },
     async (uri, variables) => {
       const requested = Array.isArray(variables.filename) ? variables.filename[0] : variables.filename;
-      const filename = (0, import_node_path5.basename)(decodeURIComponent(String(requested ?? "")));
+      const filename = (0, import_node_path6.basename)(decodeURIComponent(String(requested ?? "")));
       if (!filename.endsWith(".md")) throw new Error("Only saved .md reports can be read");
-      const text = (0, import_node_fs4.readFileSync)((0, import_node_path5.join)(outputBaseDir3(), filename), "utf8");
+      const text = (0, import_node_fs5.readFileSync)((0, import_node_path6.join)(outputBaseDir3(), filename), "utf8");
       return { contents: [{ uri: uri.href, mimeType: "text/markdown", text }] };
     }
   );
 }
 function registerPaaExtractorMcpTools(server2, executor, options = {}) {
   const savesReports = options.savesReportsLocally !== false;
-  const reportNote = savesReports ? " Saves a full Markdown report to disk." : " Reports are returned inline; no files are saved on this hosted endpoint.";
-  const withReportNote = (description) => `${description}${reportNote}`;
+  const fileBehavior = (local, hosted) => savesReports ? local : hosted;
+  const ownerId = options.ownerId ?? "local";
+  const ctx = { hosted: !savesReports, ownerId };
   if (savesReports) registerSavedReportResources(server2);
   server2.registerTool("harvest_paa", {
     title: "Google PAA + SERP Harvest",
-    description: withReportNote("Best default tool for Google search research: People Also Ask questions with answers/sources, organic SERP, local pack, entity IDs, and AI Overview. Split topic from location; leave proxyMode unset. Warn the user before maxQuestions above 100 \u2014 deep harvests can run several minutes with no interim progress, billed per extracted question."),
+    description: "Best default tool for Google search research: People Also Ask questions with answers/sources, organic SERP, local pack, entity IDs, and AI Overview. Split topic from location; leave proxyMode unset. Warn the user before maxQuestions above 100 \u2014 deep harvests can run several minutes with no interim progress, billed per extracted question.",
     inputSchema: HarvestPaaInputSchema,
-    outputSchema: HarvestPaaOutputSchema,
+    outputSchema: recordOutputSchema("harvest_paa", HarvestPaaOutputSchema),
     annotations: liveWebToolAnnotations("Google PAA + SERP Harvest")
   }, async (input) => formatHarvestPaa(await executor.harvestPaa(input), input));
   server2.registerTool("search_serp", {
     title: "Google SERP Lookup",
-    description: withReportNote("Fast Google SERP lookup without PAA expansion \u2014 rankings, organic results, local pack, positions. Split topic from location; leave proxyMode unset."),
+    description: "Fast Google SERP lookup without PAA expansion \u2014 rankings, organic results, local pack, positions. Split topic from location; leave proxyMode unset.",
     inputSchema: SearchSerpInputSchema,
-    outputSchema: SearchSerpOutputSchema,
+    outputSchema: recordOutputSchema("search_serp", SearchSerpOutputSchema),
     annotations: liveWebToolAnnotations("Google SERP Lookup")
   }, async (input) => formatSearchSerp(await executor.searchSerp(input), input));
   server2.registerTool("extract_url", {
     title: "Single URL Extract",
-    description: withReportNote("Extract structured data from one public URL: content, schema, headings, metadata, screenshots, branding, or media assets. Set depositToVault:true to save the full page into the user's MCP Memory vault server-side (not returned to chat)."),
+    description: "Extract structured data from one public URL: content, schema, headings, metadata, screenshots, branding, or media assets. Set depositToVault:true to save the full page into the user's MCP Memory vault server-side (not returned to chat).",
     inputSchema: ExtractUrlInputSchema,
-    outputSchema: ExtractUrlOutputSchema,
+    outputSchema: recordOutputSchema("extract_url", ExtractUrlOutputSchema),
     annotations: liveWebToolAnnotations("Single URL Extract")
   }, async (input) => formatExtractUrl(await executor.extractUrl(input), input));
   server2.registerTool("map_site_urls", {
     title: "Site URL Map",
-    description: withReportNote("Map/crawl a public website for a sitemap, URL inventory, or broken-link scan. Returns internal URLs with HTTP status; maps over 500 URLs are written to a local CSV file instead of inlined."),
+    description: `Map/crawl a public website for a sitemap, URL inventory, or broken-link scan. Returns internal URLs with HTTP status; ${fileBehavior("maps over 500 URLs are written to a local CSV file instead of inlined.", "large results are stored as a retrievable artifact \u2014 you get an inline summary plus an artifactId for report_artifact_read.")}`,
     inputSchema: MapSiteUrlsInputSchema,
-    outputSchema: MapSiteUrlsOutputSchema,
+    outputSchema: recordOutputSchema("map_site_urls", MapSiteUrlsOutputSchema),
     annotations: liveWebToolAnnotations("Site URL Map")
-  }, async (input) => formatMapSiteUrls(await executor.mapSiteUrls(input), input));
+  }, async (input) => formatMapSiteUrls(await executor.mapSiteUrls(input), input, ctx));
   server2.registerTool("extract_site", {
     title: "Multi-Page Site Content Crawl",
-    description: withReportNote("Crawl a public website and return page CONTENT (Markdown) across multiple pages. Bulk crawls over 25 pages are saved as per-page Markdown files in a local folder instead of inlined. Content only \u2014 for a technical SEO audit use audit_site instead."),
+    description: `Crawl a public website and return page CONTENT (Markdown) across multiple pages. ${fileBehavior("Bulk crawls over 25 pages are saved as per-page Markdown files in a local folder instead of inlined.", "Large results are stored as a retrievable artifact \u2014 you get an inline summary plus an artifactId for report_artifact_read.")} Content only \u2014 for a technical SEO audit use audit_site instead.`,
     inputSchema: ExtractSiteInputSchema,
-    outputSchema: ExtractSiteOutputSchema,
+    outputSchema: recordOutputSchema("extract_site", ExtractSiteOutputSchema),
     annotations: liveWebToolAnnotations("Multi-Page Site Content Crawl")
-  }, async (input) => formatExtractSite(await executor.extractSite(input), input));
+  }, async (input) => formatExtractSite(await executor.extractSite(input), input, ctx));
   server2.registerTool("audit_site", {
     title: "Technical SEO Audit",
-    description: withReportNote("Run a full technical SEO audit (Screaming-Frog-style) on a public website: on-page issues, internal link graph, indexability, heading/image analysis. Writes a folder of analysis files plus per-page content, and returns a summary plus the folder path. Use extract_site instead for plain page content."),
+    description: `Run a full technical SEO audit (Screaming-Frog-style) on a public website: on-page issues, internal link graph, indexability, heading/image analysis. ${fileBehavior("Writes a folder of analysis files plus per-page content, and returns a summary plus the folder path.", "Large results are stored as a retrievable artifact \u2014 you get an inline summary plus an artifactId for report_artifact_read.")} Use extract_site instead for plain page content.`,
     inputSchema: AuditSiteInputSchema,
-    outputSchema: AuditSiteOutputSchema,
+    outputSchema: recordOutputSchema("audit_site", AuditSiteOutputSchema),
     annotations: liveWebToolAnnotations("Technical SEO Audit")
-  }, async (input) => formatAuditSite(await executor.auditSite(input), input));
+  }, async (input) => formatAuditSite(await executor.auditSite(input), input, ctx));
   server2.registerTool("youtube_harvest", {
     title: "YouTube Video Harvest",
-    description: withReportNote('Harvest YouTube video metadata by topic search or channel library. Use mode "search" for keyword/topic requests, mode "channel" for @handles/channel IDs/URLs. Returns titles, views, durations, and videoIds.'),
+    description: 'Harvest YouTube video metadata by topic search or channel library. Use mode "search" for keyword/topic requests, mode "channel" for @handles/channel IDs/URLs. Returns titles, views, durations, and videoIds.',
     inputSchema: YoutubeHarvestInputSchema,
-    outputSchema: YoutubeHarvestOutputSchema,
+    outputSchema: recordOutputSchema("youtube_harvest", YoutubeHarvestOutputSchema),
     annotations: liveWebToolAnnotations("YouTube Video Harvest")
   }, async (input) => formatYoutubeHarvest(await executor.youtubeHarvest(input), input));
   server2.registerTool("youtube_transcribe", {
     title: "YouTube Transcription",
-    description: withReportNote("Fetch and transcribe captions from a YouTube video. Pass videoId from youtube_harvest, or a url the user pasted. Returns full transcript, timestamped chunks, and word count."),
+    description: "Fetch and transcribe captions from a YouTube video. Pass videoId from youtube_harvest, or a url the user pasted. Returns full transcript, timestamped chunks, and word count.",
     inputSchema: YoutubeTranscribeInputSchema,
-    outputSchema: YoutubeTranscribeOutputSchema,
+    outputSchema: recordOutputSchema("youtube_transcribe", YoutubeTranscribeOutputSchema),
     annotations: liveWebToolAnnotations("YouTube Transcription")
   }, async (input) => formatYoutubeTranscribe(await executor.youtubeTranscribe(input), input));
   server2.registerTool("facebook_page_intel", {
     title: "Facebook Advertiser Ad Intel",
-    description: withReportNote("Harvest ads from a Facebook advertiser: copy, creative angles, CTAs, and direct video URLs ready for facebook_ad_transcribe. Accepts pageId, libraryId, or a brand/advertiser name."),
+    description: "Harvest ads from a Facebook advertiser: copy, creative angles, CTAs, and direct video URLs ready for facebook_ad_transcribe. Accepts pageId, libraryId, or a brand/advertiser name.",
     inputSchema: FacebookPageIntelInputSchema,
-    outputSchema: FacebookPageIntelOutputSchema,
+    outputSchema: recordOutputSchema("facebook_page_intel", FacebookPageIntelOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Advertiser Ad Intel")
   }, async (input) => formatFacebookPageIntel(await executor.facebookPageIntel(input), input));
   server2.registerTool("facebook_ad_search", {
     title: "Facebook Ad Library Search",
-    description: withReportNote("Search Facebook Ad Library to find advertisers by brand, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs."),
+    description: "Search Facebook Ad Library to find advertisers by brand, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs.",
     inputSchema: FacebookAdSearchInputSchema,
-    outputSchema: FacebookAdSearchOutputSchema,
+    outputSchema: recordOutputSchema("facebook_ad_search", FacebookAdSearchOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Ad Library Search")
   }, async (input) => formatFacebookAdSearch(await executor.facebookAdSearch(input), input));
   server2.registerTool("reddit_thread", {
     title: "Reddit Thread + Comments",
-    description: withReportNote("Capture a Reddit post and its comment tree from a reddit.com thread URL \u2014 comments, opinions, audience voice. Handles Reddit's bot protection automatically; pass maxComments to cap the list."),
+    description: "Capture a Reddit post and its comment tree from a reddit.com thread URL \u2014 comments, opinions, audience voice. Handles Reddit's bot protection automatically; pass maxComments to cap the list.",
     inputSchema: RedditThreadInputSchema,
-    outputSchema: RedditThreadOutputSchema,
+    outputSchema: recordOutputSchema("reddit_thread", RedditThreadOutputSchema),
     annotations: liveWebToolAnnotations("Reddit Thread + Comments")
   }, async (input) => formatRedditThread(await executor.redditThread(input), input));
   server2.registerTool("video_frame_analysis", {
     title: "Video Breakdown (frame-by-frame + transcript)",
-    description: "Produce a deep frame-by-frame + transcript breakdown of a video \u2014 pacing, hook, visual style, and how to replicate it. Pass a DIRECT video file URL (.mp4/.webm/.mov), not a page URL. Runs asynchronously and costs a flat $1 (refunded on failure): returns a runId immediately; poll video_frame_analysis_status until done.",
+    description: "Produce a deep frame-by-frame + transcript breakdown of a video \u2014 pacing, hook, visual style, and how to replicate it. Pass a DIRECT video file URL (.mp4/.webm/.mov), not a page URL. Costs $1 per 120 frames requested (max 480 = $4; refunded down if the video can't use them; refunded fully on failure): returns a runId immediately; poll video_frame_analysis_status until done. Videos up to 30 minutes.",
     inputSchema: VideoFrameAnalysisInputSchema,
-    outputSchema: VideoFrameAnalysisOutputSchema,
+    outputSchema: recordOutputSchema("video_frame_analysis", VideoFrameAnalysisOutputSchema),
     annotations: { title: "Video Breakdown", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
   }, async (input) => executor.videoFrameAnalysis(input));
   server2.registerTool("video_frame_analysis_status", {
     title: "Video Breakdown Status",
-    description: 'Check progress of a video breakdown started with video_frame_analysis, using its runId. Free to call. When status is "done" it returns the full report and vault path; stop polling on "done" or "failed".',
+    description: 'Check progress of a video breakdown started with video_frame_analysis, using its runId. Free to call. When status is "done" it returns the full report and vault path; stop polling on "done" or "failed". Reports the billed tier reconciliation when done.',
     inputSchema: VideoFrameAnalysisStatusInputSchema,
-    outputSchema: VideoFrameAnalysisStatusOutputSchema,
+    outputSchema: recordOutputSchema("video_frame_analysis_status", VideoFrameAnalysisStatusOutputSchema),
     annotations: { title: "Video Breakdown Status", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
   }, async (input) => executor.videoFrameAnalysisStatus(input));
   server2.registerTool("facebook_ad_transcribe", {
     title: "Facebook Ad Transcription",
     description: "Transcribe audio from a Facebook ad video CDN URL returned by facebook_page_intel. Use only that direct videoUrl value \u2014 do not pass public Facebook post/reel/share URLs (use facebook_video_transcribe for those).",
     inputSchema: FacebookAdTranscribeInputSchema,
-    outputSchema: FacebookAdTranscribeOutputSchema,
+    outputSchema: recordOutputSchema("facebook_ad_transcribe", FacebookAdTranscribeOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Ad Transcription")
   }, async (input) => formatFacebookAdTranscribe(await executor.facebookAdTranscribe(input), input));
   server2.registerTool("google_ads_search", {
     title: "Google Ads Transparency Search",
-    description: withReportNote("Search the Google Ads Transparency Center to find advertisers by domain or brand name. Returns advertisers with advertiser ID and approximate ad count, to pass to google_ads_page_intel."),
+    description: "Search the Google Ads Transparency Center to find advertisers by domain or brand name. Returns advertisers with advertiser ID and approximate ad count, to pass to google_ads_page_intel.",
     inputSchema: GoogleAdsSearchInputSchema,
-    outputSchema: GoogleAdsSearchOutputSchema,
+    outputSchema: recordOutputSchema("google_ads_search", GoogleAdsSearchOutputSchema),
     annotations: liveWebToolAnnotations("Google Ads Transparency Search")
   }, async (input) => formatGoogleAdsSearch(await executor.googleAdsSearch(input), input));
   server2.registerTool("google_ads_page_intel", {
     title: "Google Ads Advertiser Intel",
-    description: withReportNote("Harvest an advertiser's ad creatives from the Google Ads Transparency Center: format, image URLs, and \u2014 for video ads \u2014 a YouTube video ID or direct video URL. Accepts advertiserId (from google_ads_search) or a domain."),
+    description: "Harvest an advertiser's ad creatives from the Google Ads Transparency Center: format, image URLs, and \u2014 for video ads \u2014 a YouTube video ID or direct video URL. Accepts advertiserId (from google_ads_search) or a domain.",
     inputSchema: GoogleAdsPageIntelInputSchema,
-    outputSchema: GoogleAdsPageIntelOutputSchema,
+    outputSchema: recordOutputSchema("google_ads_page_intel", GoogleAdsPageIntelOutputSchema),
     annotations: liveWebToolAnnotations("Google Ads Advertiser Intel")
   }, async (input) => formatGoogleAdsPageIntel(await executor.googleAdsPageIntel(input), input));
   server2.registerTool("google_ads_transcribe", {
     title: "Google Ad Video Transcription",
     description: "Transcribe audio from a Google video ad's direct videoUrl (a googlevideo.com playback URL) returned by google_ads_page_intel. For YouTube-hosted ads, use youtube_transcribe with the returned youtubeVideoId instead.",
     inputSchema: GoogleAdsTranscribeInputSchema,
-    outputSchema: GoogleAdsTranscribeOutputSchema,
+    outputSchema: recordOutputSchema("google_ads_transcribe", GoogleAdsTranscribeOutputSchema),
     annotations: liveWebToolAnnotations("Google Ad Video Transcription")
   }, async (input) => formatGoogleAdsTranscribe(await executor.googleAdsTranscribe(input), input));
   server2.registerTool("facebook_video_transcribe", {
     title: "Facebook Organic Video Transcription",
-    description: withReportNote("Transcribe audio from an organic Facebook reel/video/post/share URL (including fb.watch). Renders the page, selects the best public CDN MP4, and returns the transcript plus resolved video metadata."),
+    description: "Transcribe audio from an organic Facebook reel/video/post/share URL (including fb.watch). Renders the page, selects the best public CDN MP4, and returns the transcript plus resolved video metadata.",
     inputSchema: FacebookVideoTranscribeInputSchema,
-    outputSchema: FacebookVideoTranscribeOutputSchema,
+    outputSchema: recordOutputSchema("facebook_video_transcribe", FacebookVideoTranscribeOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Organic Video Transcription")
   }, async (input) => formatFacebookVideoTranscribe(await executor.facebookVideoTranscribe(input), input));
   server2.registerTool("instagram_profile_content", {
     title: "Instagram Profile Content Discovery",
-    description: withReportNote("Discover Instagram profile grid content links (posts/reels/tv) for a handle or profile URL, for later selection with instagram_media_download. Returns profile stats and collected URLs."),
+    description: "Discover Instagram profile grid content links (posts/reels/tv) for a handle or profile URL, for later selection with instagram_media_download. Returns profile stats and collected URLs.",
     inputSchema: InstagramProfileContentInputSchema,
-    outputSchema: InstagramProfileContentOutputSchema,
+    outputSchema: recordOutputSchema("instagram_profile_content", InstagramProfileContentOutputSchema),
     annotations: liveWebToolAnnotations("Instagram Profile Content Discovery")
   }, async (input) => formatInstagramProfileContent(await executor.instagramProfileContent(input), input));
   server2.registerTool("instagram_media_download", {
     title: "Instagram Post/Reel Media Download",
-    description: withReportNote("Extract and download media from one Instagram post, reel, or tv URL \u2014 image, caption, video/audio tracks, optional muxed MP4, or transcript. Selects the best video/audio track pair and muxes when ffmpeg is available."),
+    description: "Extract and download media from one Instagram post, reel, or tv URL \u2014 image, caption, video/audio tracks, optional muxed MP4, or transcript. Selects the best video/audio track pair and muxes when ffmpeg is available.",
     inputSchema: InstagramMediaDownloadInputSchema,
-    outputSchema: InstagramMediaDownloadOutputSchema,
+    outputSchema: recordOutputSchema("instagram_media_download", InstagramMediaDownloadOutputSchema),
     annotations: liveWebToolAnnotations("Instagram Post/Reel Media Download")
   }, async (input) => formatInstagramMediaDownload(await executor.instagramMediaDownload(input), input));
   server2.registerTool("maps_place_intel", {
     title: "Google Maps Business Profile Details",
-    description: withReportNote("Extract Google Maps business intelligence for one known/named business: rating, reviews, category, address, phone, hours, entity IDs. Not for category searches or multi-business prospect lists \u2014 use maps_search for those. Split business name from location."),
+    description: "Extract Google Maps business intelligence for one known/named business: rating, reviews, category, address, phone, hours, entity IDs. Not for category searches or multi-business prospect lists \u2014 use maps_search for those. Split business name from location.",
     inputSchema: MapsPlaceIntelInputSchema,
-    outputSchema: MapsPlaceIntelOutputSchema,
+    outputSchema: recordOutputSchema("maps_place_intel", MapsPlaceIntelOutputSchema),
     annotations: liveWebToolAnnotations("Google Maps Business Profile Details")
   }, async (input) => formatMapsPlaceIntel(await executor.mapsPlaceIntel(input), input));
   server2.registerTool("maps_search", {
     title: "Google Maps Business Search",
-    description: withReportNote("Search Google Maps for multiple businesses by category, niche, or local market \u2014 leads, prospects, competitors, or beyond the 3-pack. Leave proxyMode unset. Returns up to 50 candidates (default 10) with names, place URLs, CIDs, ratings."),
+    description: "Search Google Maps for multiple businesses by category, niche, or local market \u2014 leads, prospects, competitors, or beyond the 3-pack. Leave proxyMode unset. Returns up to 50 candidates (default 10) with names, place URLs, CIDs, ratings.",
     inputSchema: MapsSearchInputSchema,
-    outputSchema: MapsSearchOutputSchema,
+    outputSchema: recordOutputSchema("maps_search", MapsSearchOutputSchema),
     annotations: liveWebToolAnnotations("Google Maps Business Search")
   }, async (input) => formatMapsSearch(await executor.mapsSearch(input), input));
   server2.registerTool("directory_workflow", {
     title: "Directory Workflow: Markets + Maps",
-    description: withReportNote('Build directory/prospecting datasets: selects US city markets from Census population data, optionally joins configured ZIP groups, then runs Google Maps business searches per city in parallel. Use for "all cities over 100k population in a state" or market+Maps workflows. Saves a CSV of results per city. For ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the server, or pass usZipsCsvPath in local/test mode.'),
+    description: `Build directory/prospecting datasets: selects US city markets from Census population data, optionally joins configured ZIP groups, then runs Google Maps business searches per city in parallel. Use for "all cities over 100k population in a state" or market+Maps workflows. ${fileBehavior("Saves a CSV of results per city.", "Large results are stored as a retrievable artifact \u2014 you get an inline summary plus an artifactId for report_artifact_read.")}`,
     inputSchema: DirectoryWorkflowInputSchema,
-    outputSchema: DirectoryWorkflowOutputSchema,
+    outputSchema: recordOutputSchema("directory_workflow", DirectoryWorkflowOutputSchema),
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
-  }, async (input) => formatDirectoryWorkflow(await executor.directoryWorkflow(input), input));
+  }, async (input) => formatDirectoryWorkflow(await executor.directoryWorkflow(input), input, ctx));
   server2.registerTool("workflow_list", {
     title: "Workflow Catalog",
     description: "List MCP Scraper higher-level workflows and recipes \u2014 market analysis, ICP research, CRO audits, competitive positioning, content gap briefs, AI search visibility, and more. Returns runnable workflow ids plus tool-chain guidance.",
     inputSchema: WorkflowListInputSchema,
-    outputSchema: WorkflowListOutputSchema,
+    outputSchema: recordOutputSchema("workflow_list", WorkflowListOutputSchema),
     annotations: localPlanningToolAnnotations("Workflow Catalog")
   }, async (input) => formatWorkflowList(await executor.workflowList(input), input));
   server2.registerTool("workflow_suggest", {
     title: "Workflow Intent Router",
     description: "Route a high-level business/research goal (market analysis, ICP research, CRO audit, competitor comparison, content gap brief, AI search visibility, etc) to the right MCP Scraper workflow/tool chain. Free; tells you what to run next.",
     inputSchema: WorkflowSuggestInputSchema,
-    outputSchema: WorkflowSuggestOutputSchema,
+    outputSchema: recordOutputSchema("workflow_suggest", WorkflowSuggestOutputSchema),
     annotations: localPlanningToolAnnotations("Workflow Intent Router")
   }, async (input) => formatWorkflowSuggest(input));
   server2.registerTool("workflow_run", {
     title: "Run Workflow",
-    description: withReportNote("Start a higher-level MCP Scraper workflow (directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language). Use after workflow_suggest or workflow_list. Stepwise workflows return runId + nextStep \u2014 call workflow_step with the runId until done is true."),
+    description: "Start a higher-level MCP Scraper workflow (directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language). Use after workflow_suggest or workflow_list. Stepwise workflows return runId + nextStep \u2014 call workflow_step with the runId until done is true.",
     inputSchema: WorkflowRunInputSchema,
-    outputSchema: WorkflowRunOutputSchema,
+    outputSchema: recordOutputSchema("workflow_run", WorkflowRunOutputSchema),
     annotations: liveWebToolAnnotations("Run Workflow")
   }, async (input) => formatWorkflowRun(await executor.workflowRun(input), input));
   server2.registerTool("workflow_step", {
     title: "Advance Workflow Step",
-    description: withReportNote("Run the next leg of a stepwise workflow started with workflow_run. Pass the runId; each call executes one step and returns its output plus nextStep. Keep calling with the same runId until done is true."),
+    description: "Run the next leg of a stepwise workflow started with workflow_run. Pass the runId; each call executes one step and returns its output plus nextStep. Keep calling with the same runId until done is true.",
     inputSchema: WorkflowStepInputSchema,
-    outputSchema: WorkflowStepOutputSchema,
+    outputSchema: recordOutputSchema("workflow_step", WorkflowStepOutputSchema),
     annotations: liveWebToolAnnotations("Advance Workflow Step")
   }, async (input) => formatWorkflowStep(await executor.workflowStep(input), input));
   server2.registerTool("workflow_status", {
     title: "Workflow Status",
     description: "Fetch a hosted workflow run by id and list its current status and artifacts, to re-open a run or recover artifact ids. Use only a runId returned by workflow_run/workflow_step/workflow_status.",
     inputSchema: WorkflowStatusInputSchema,
-    outputSchema: WorkflowStatusOutputSchema,
+    outputSchema: recordOutputSchema("workflow_status", WorkflowStatusOutputSchema),
     annotations: liveWebToolAnnotations("Workflow Status")
   }, async (input) => formatWorkflowStatus(await executor.workflowStatus(input), input));
   server2.registerTool("workflow_artifact_read", {
     title: "Read Workflow Artifact",
     description: "Read a workflow artifact back into context by run id and artifact id, so final deliverables are grounded in generated evidence rather than memory. Use workflow_status first when artifact ids are unknown. Use maxBytes to limit large artifacts.",
     inputSchema: WorkflowArtifactReadInputSchema,
-    outputSchema: WorkflowArtifactReadOutputSchema,
+    outputSchema: recordOutputSchema("workflow_artifact_read", WorkflowArtifactReadOutputSchema),
     annotations: liveWebToolAnnotations("Read Workflow Artifact")
   }, async (input) => formatWorkflowArtifactRead(await executor.workflowArtifactRead(input), input));
+  server2.registerTool("report_artifact_read", {
+    title: "Read Report Artifact",
+    description: "Read back a stored report artifact by artifactId (returned by any tool whose result was too large to inline). Windowed: pass offset/maxBytes and keep reading until nextOffset is null.",
+    inputSchema: ReportArtifactReadInputSchema,
+    outputSchema: recordOutputSchema("report_artifact_read", ReportArtifactReadOutputSchema),
+    annotations: liveWebToolAnnotations("Read Report Artifact")
+  }, async (input) => {
+    const owner = artifactOwnerId(input.artifactId);
+    if (!owner || owner !== ownerId) {
+      return { content: [{ type: "text", text: "Artifact not found or not owned by this caller." }], isError: true };
+    }
+    const window = await readArtifactWindow(input.artifactId, input.offset ?? 0, input.maxBytes ?? 2e4);
+    if (!window) {
+      return { content: [{ type: "text", text: "Artifact not found or expired." }], isError: true };
+    }
+    return {
+      content: [{ type: "text", text: window.text }],
+      structuredContent: { artifactId: input.artifactId, text: window.text, totalBytes: window.totalBytes, nextOffset: window.nextOffset }
+    };
+  });
   server2.registerTool("rank_tracker_workflow", {
     title: "Rank Tracker Blueprint Builder",
     description: "Generate a build-ready database schema, cron plan, and implementation prompt for a rank tracker powered by MCP Scraper (Maps, organic, AI Overview, or PAA tracking). Local planning only \u2014 does not call the web or spend credits.",
     inputSchema: RankTrackerBlueprintInputSchema,
-    outputSchema: RankTrackerBlueprintOutputSchema,
+    outputSchema: recordOutputSchema("rank_tracker_workflow", RankTrackerBlueprintOutputSchema),
     annotations: localPlanningToolAnnotations("Rank Tracker Blueprint Builder")
   }, async (input) => buildRankTrackerBlueprint(input));
   server2.registerTool("credits_info", {
     title: "MCP Scraper Credits & Costs",
     description: "Answer questions about MCP Scraper credits, usage limits, and concurrency upgrades \u2014 balance, tool costs, concurrency limits, billing URL. Does not expose payment methods or card information.",
     inputSchema: CreditsInfoInputSchema,
-    outputSchema: CreditsInfoOutputSchema,
+    outputSchema: recordOutputSchema("credits_info", CreditsInfoOutputSchema),
     annotations: {
       title: "MCP Scraper Credits & Costs",
       readOnlyHint: true,
@@ -6319,10 +6579,10 @@ if (!forceStdio && (interactiveTerminal || wantsHelp)) {
 }
 function readApiKeyFile() {
   const explicitPath = process.env.MCP_SCRAPER_KEY_PATH?.trim();
-  const paths = [explicitPath, (0, import_node_path6.join)((0, import_node_os5.homedir)(), ".mcp-scraper-key")].filter(Boolean);
+  const paths = [explicitPath, (0, import_node_path7.join)((0, import_node_os6.homedir)(), ".mcp-scraper-key")].filter(Boolean);
   for (const path of paths) {
     try {
-      const value = (0, import_node_fs5.readFileSync)(path, "utf8").trim();
+      const value = (0, import_node_fs6.readFileSync)(path, "utf8").trim();
       if (value) return value;
     } catch {
     }