mcp-scraper 0.18.0 → 0.19.0

package/dist/{chunk-FMEDPBIV.js → chunk-O2S5TOCG.js}

@@ -9,15 +9,17 @@ import {
 } from "./chunk-R7EETU7Z.js";
 import {
   browserServiceProfileName,
-  browserServiceProfileSaveChanges
-} from "./chunk-HPV4VOQX.js";
+  browserServiceProfileSaveChanges,
+  recordVendorUsage,
+  vendorCostUsd
+} from "./chunk-D7ZT27HY.js";
 import {
   DEFAULT_MAPS_PROXY_MODE,
   DEFAULT_PROXY_MODE
 } from "./chunk-XGIPATLV.js";
 import {
   PACKAGE_VERSION
-} from "./chunk-RLWCHLV3.js";
+} from "./chunk-OQHYDW4Q.js";
 import {
   MC_PER_CREDIT
 } from "./chunk-HL33CGJF.js";
@@ -317,10 +319,14 @@ seam is noted so you can chain them.
 
 ## Facebook
 - Find advertisers -> **facebook_ad_search** (returns \`advertisers[]\` with pageId, libraryId).
-- One advertiser's ads -> **facebook_page_intel** (takes pageId, libraryId, or query; returns
-  \`ads[].videoUrl\`).
-- Transcribe an ad video -> **facebook_ad_transcribe** (takes a videoUrl from \`facebook_page_intel\`).
-- Transcribe an organic reel/video/post -> **facebook_video_transcribe** (takes the Facebook url directly).
+- Public Ad Library scan -> **facebook_page_intel**. Prefer pageId/libraryId. Query mode is broad discovery,
+  can mix advertisers, and must be checked through matchConfidence/warnings. Paused non-political ads may
+  be absent even when the connected ad account still has them.
+- Connected ad-account creative -> **meta_ad_creative_media** (takes connectionId + adId). This is the
+  preferred paused/dark-ad path and returns actual image content plus exact video follow-up arguments.
+- Direct Graph/Ad Library CDN video -> **facebook_ad_transcribe**. Use transient source URLs immediately.
+- Public reel/video/post -> **facebook_video_transcribe**. Use the public candidate returned by
+  \`meta_ad_creative_media\` when Graph did not provide a direct source; dark posts may not resolve publicly.
 
 ## Google Ads (Ads Transparency Center)
 - Find advertisers by domain or brand -> **google_ads_search** (returns \`advertisers[]\` with advertiserId).
@@ -362,8 +368,8 @@ Multi-step orchestrations \u2014 prefer these over hand-chaining primitives when
   recording) locates a DOM target and returns a ready-to-use timed annotation -> **browser_replay_stop**
   ends it -> feed collected annotations to **browser_replay_annotate**, or just
   **browser_replay_download** the plain MP4. **browser_list_replays** recovers replay ids.
-- Video breakdown is async: **video_frame_analysis** takes a DIRECT media file URL (resolve
-  YouTube/Facebook/Instagram page URLs to one first, e.g. via \`facebook_page_intel\`'s \`videoUrl\`) and
+- Video breakdown is async: **video_frame_analysis** takes a supported public video page or direct media URL
+  (for connected Meta ads, use the exact sourceUrl/public candidate returned by \`meta_ad_creative_media\`) and
   returns a \`runId\` immediately -> poll **video_frame_analysis_status** with that \`runId\` until \`status\`
   is \`done\`.
 
@@ -372,6 +378,8 @@ 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).
+- Use the hosted browser as a controlled resolver for validated public Facebook post/reel redirects only
+  when connected Graph media did not provide a playable source. It is not a bypass for URL/SSRF restrictions.
 - 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.
 
@@ -704,6 +712,75 @@ function summaryEnvelope(executiveSummary, offloaded) {
   ].join("\n");
 }
 
+// src/services/media-transcription.ts
+import { fal } from "@fal-ai/client";
+function transcriptWordCount(text) {
+  return text.trim() ? text.trim().split(/\s+/).length : 0;
+}
+function assessTranscriptSignal(text, chunks, durationHintSec) {
+  const words = transcriptWordCount(text);
+  const chunkDurationSec = chunks.reduce((max, chunk) => {
+    const end = Number(chunk.timestamp?.[1]);
+    return Number.isFinite(end) && end > max ? end : max;
+  }, 0);
+  const mediaDurationSec = typeof durationHintSec === "number" && Number.isFinite(durationHintSec) && durationHintSec > 0 ? durationHintSec : chunkDurationSec > 0 ? chunkDurationSec : null;
+  const wordsPerMinute = mediaDurationSec && mediaDurationSec > 0 ? Math.round(words / mediaDurationSec * 600) / 10 : null;
+  const status = words === 0 ? "empty" : words < 5 ? "low_speech_signal" : "speech_detected";
+  const retryRecommended = words <= 2;
+  const warnings = [];
+  if (status === "empty") {
+    warnings.push("No speech was transcribed. This does not distinguish silent media from an inaccessible or expired playback URL.");
+  } else if (status === "low_speech_signal") {
+    warnings.push("Very little speech was transcribed. Review the media or retry from a durable public post/reel URL before treating this as a complete transcript.");
+  }
+  if (retryRecommended) {
+    warnings.push("For a connected Meta ad, resolve the creative effectiveObjectStoryId and retry with facebook_video_transcribe when a public post URL is available.");
+  }
+  return {
+    status,
+    speechDetected: status === "speech_detected",
+    confidence: status === "speech_detected" ? "medium" : "low",
+    basis: "transcript_word_count_and_timing",
+    mediaDurationSec,
+    wordsPerMinute,
+    retryRecommended,
+    warnings
+  };
+}
+function transcriptMarkdown(title, text, chunks, durationMs) {
+  const fmtTs = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
+  const lines = [title, "", `*Transcribed in ${(durationMs / 1e3).toFixed(1)}s*`, "", "## Full Text", "", text, ""];
+  if (chunks.length) {
+    lines.push("## Timestamped Segments", "");
+    for (const ch of chunks) {
+      lines.push(`**[${fmtTs(ch.timestamp[0])} -> ${fmtTs(ch.timestamp[1])}]** ${ch.text.trim()}`, "");
+    }
+  }
+  return lines.join("\n");
+}
+async function transcribeMediaUrl(mediaUrl, markdownTitle = "# Media Transcript") {
+  const startMs = Date.now();
+  const result = await fal.subscribe("fal-ai/wizper", {
+    input: { audio_url: mediaUrl, task: "transcribe", language: "en" },
+    logs: false,
+    pollInterval: 3e3
+  });
+  const data = result.data;
+  const text = data.text ?? "";
+  const chunks = data.chunks ?? [];
+  const durationMs = Date.now() - startMs;
+  void recordVendorUsage({ vendor: "fal_wizper", model: "fal-ai/wizper", units: durationMs / 1e3, unitType: "compute_sec" });
+  const costUsd = vendorCostUsd("fal_wizper", durationMs / 1e3);
+  return {
+    text,
+    chunks,
+    durationMs,
+    costUsd,
+    markdown: transcriptMarkdown(markdownTitle, text, chunks, durationMs),
+    transcriptSignal: assessTranscriptSignal(text, chunks)
+  };
+}
+
 // src/mcp/mcp-response-formatter.ts
 var INLINE_BUDGET_BYTES = Number(process.env.MCP_SCRAPER_INLINE_BUDGET ?? 5e4);
 var STRUCTURED_ARRAY_CAP = 25;
@@ -1671,6 +1748,7 @@ function formatFacebookPageIntel(raw, input) {
   const advertiser = d.advertiserName ?? input.query ?? input.pageId ?? input.libraryId ?? "Advertiser";
   const ads = d.ads ?? [];
   const s = d.summary ?? { totalAds: 0, activeCount: 0, videoCount: 0, imageCount: 0 };
+  const warnings = d.warnings ?? [];
   const adBlocks = ads.map((ad, i) => [
     `### Ad ${i + 1}${ad.libraryId ? ` \xB7 \`${ad.libraryId}\`` : ""} \u2014 ${ad.status ?? "\u2014"} \xB7 ${ad.creativeType ?? "\u2014"} \xB7 ${ad.startDate ?? ad.started ?? "\u2014"}`,
     ad.headline ? `**Headline:** ${ad.headline}` : "",
@@ -1683,19 +1761,28 @@ function formatFacebookPageIntel(raw, input) {
   const full = [
     `# Facebook Ad Intel: ${advertiser}`,
     `**${s.totalAds} ads** \xB7 ${s.activeCount} active \xB7 ${s.videoCount} video \xB7 ${s.imageCount} image`,
+    d.matchConfidence ? `**Match confidence:** ${d.matchConfidence}${d.matchReason ? ` \u2014 ${d.matchReason}` : ""}` : "",
+    warnings.length ? `
+> \u26A0\uFE0F ${warnings.join("\n> \u26A0\uFE0F ")}` : "",
     `
 ${adBlocks}`,
     `
 ---
 \u{1F4A1} **Tips**
-- Transcribe video ads: use \`facebook_ad_transcribe\` with the direct \`videoUrl\` above
-- Transcribe organic Facebook reels/posts: use \`facebook_video_transcribe\` with the public Facebook URL
-- Find other advertisers: use \`facebook_ad_search\``
+- Connected, paused, or dark ad: use \`meta_ad_creative_media\` with its adId
+- Ad Library direct video URL: use \`facebook_ad_transcribe\` immediately
+- Public Facebook post/reel URL: use \`facebook_video_transcribe\`
+- Find the exact advertiser pageId first: use \`facebook_ad_search\``
   ].filter(Boolean).join("\n");
   return {
     ...oneBlock(full),
     structuredContent: {
       advertiserName: d.advertiserName ?? null,
+      inputMode: d.inputMode ?? (input.pageId ? "pageId" : input.libraryId ? "libraryId" : "query"),
+      matchConfidence: d.matchConfidence ?? (input.query ? "low" : "high"),
+      matchReason: d.matchReason ?? (input.query ? "Keyword search result was not confidence-scored by the server." : "Exact identifier filter."),
+      warnings,
+      matchedAdvertisers: d.matchedAdvertisers ?? [],
       totalAds: s.totalAds ?? 0,
       activeCount: s.activeCount ?? 0,
       videoCount: s.videoCount ?? 0,
@@ -2624,6 +2711,7 @@ function formatFacebookAdTranscribe(raw, input) {
   const chunks = d.chunks ?? [];
   const durSec = d.durationMs ? (d.durationMs / 1e3).toFixed(0) : "\u2014";
   const words = wordCount(text);
+  const signal = d.transcriptSignal ?? assessTranscriptSignal(text, chunks);
   const chunkRows = chunks.slice(0, 50).map((c) => {
     const sec = Number.isFinite(c.timestamp[0]) ? Math.floor(c.timestamp[0]) : 0;
     const mm = String(Math.floor(sec / 60)).padStart(2, "0");
@@ -2632,7 +2720,9 @@ function formatFacebookAdTranscribe(raw, input) {
   }).join("\n");
   const full = [
     `# Facebook Ad Transcript`,
-    `**Duration:** ${durSec}s \xB7 **${words} words**`,
+    `**Transcription elapsed:** ${durSec}s \xB7 **${words} words** \xB7 **Signal:** ${signal.status}`,
+    signal.warnings.length ? `
+> \u26A0\uFE0F ${signal.warnings.join("\n> \u26A0\uFE0F ")}` : "",
     `
 ## Full Transcript
 ${text}`,
@@ -2654,6 +2744,7 @@ ${chunkRows}` : "",
       durationMs: typeof d.durationMs === "number" ? d.durationMs : null,
       transcriptText: text,
       chunks: structuredTranscriptChunks(chunks),
+      transcriptSignal: signal,
       resolvedInputs: {
         videoUrl: input.videoUrl
       }
@@ -2670,6 +2761,7 @@ function formatFacebookVideoTranscribe(raw, input) {
   const durSec = d.durationMs ? (d.durationMs / 1e3).toFixed(0) : "\u2014";
   const videoDuration = typeof d.videoDurationSec === "number" ? `${Math.round(d.videoDurationSec)}s` : "\u2014";
   const label = d.videoId ? `Facebook Organic Video \`${d.videoId}\`` : "Facebook Organic Video";
+  const signal = d.transcriptSignal ?? assessTranscriptSignal(text, chunks, d.videoDurationSec);
   const chunkRows = chunks.slice(0, 50).map((c) => {
     const sec = Number.isFinite(c.timestamp[0]) ? Math.floor(c.timestamp[0]) : 0;
     const mm = String(Math.floor(sec / 60)).padStart(2, "0");
@@ -2680,6 +2772,9 @@ function formatFacebookVideoTranscribe(raw, input) {
     `# ${label} Transcript`,
     d.ownerName ? `**Owner:** ${d.ownerName}` : "",
     `**Video duration:** ${videoDuration} \xB7 **Transcribed in:** ${durSec}s \xB7 **${wordCount2} words**`,
+    `**Transcript signal:** ${signal.status} (${signal.confidence} heuristic confidence)`,
+    signal.warnings.length ? `
+> \u26A0\uFE0F ${signal.warnings.join("\n> \u26A0\uFE0F ")}` : "",
     d.pageUrl ? `**Page URL:** ${d.pageUrl}` : `**Page URL:** ${input.url}`,
     d.videoUrl ? `**Extracted MP4:** \`${d.videoUrl}\`` : "",
     `
@@ -2712,7 +2807,8 @@ ${chunkRows}` : "",
         startSec: Number.isFinite(c.timestamp[0]) ? c.timestamp[0] : 0,
         endSec: Number.isFinite(c.timestamp[1]) ? c.timestamp[1] : 0,
         text: c.text
-      }))
+      })),
+      transcriptSignal: signal
     }
   };
 }
@@ -3022,6 +3118,208 @@ function recordOutputSchema(name, schema) {
   return ADVERTISE_OUTPUT_SCHEMAS ? schema : void 0;
 }
 
+// src/mcp/meta-ad-creative-media.ts
+var META_IMAGE_HOSTS = ["facebook.com", "fbcdn.net", "fbsbx.com", "cdninstagram.com"];
+var MAX_IMAGE_BYTES = 15e5;
+var MAX_TOTAL_IMAGE_BYTES = 25e5;
+var MAX_REDIRECTS = 3;
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function parseToolPayload(result) {
+  const structured = asRecord(result.structuredContent);
+  if (structured) return structured;
+  for (const block of result.content ?? []) {
+    if (block.type !== "text") continue;
+    try {
+      const parsed = JSON.parse(block.text);
+      const row = asRecord(parsed);
+      if (row) return row;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function allowedMetaImageUrl(raw) {
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== "https:") return null;
+    const host = url.hostname.toLowerCase().replace(/\.$/, "");
+    if (!META_IMAGE_HOSTS.some((suffix) => host === suffix || host.endsWith(`.${suffix}`))) return null;
+    return url;
+  } catch {
+    return null;
+  }
+}
+function detectImageMime(bytes) {
+  if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return "image/jpeg";
+  if (bytes.length >= 8 && bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71 && bytes[4] === 13 && bytes[5] === 10 && bytes[6] === 26 && bytes[7] === 10) return "image/png";
+  if (bytes.length >= 12 && String.fromCharCode(...bytes.slice(0, 4)) === "RIFF" && String.fromCharCode(...bytes.slice(8, 12)) === "WEBP") return "image/webp";
+  if (bytes.length >= 6) {
+    const signature = String.fromCharCode(...bytes.slice(0, 6));
+    if (signature === "GIF87a" || signature === "GIF89a") return "image/gif";
+  }
+  return null;
+}
+async function readBoundedBody(response, maxBytes) {
+  const contentLength = Number(response.headers.get("content-length") ?? "");
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) throw new Error("image_too_large");
+  if (!response.body) {
+    const bytes2 = new Uint8Array(await response.arrayBuffer());
+    if (bytes2.byteLength > maxBytes) throw new Error("image_too_large");
+    return bytes2;
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      if (total > maxBytes) throw new Error("image_too_large");
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+async function fetchMetaImage(rawUrl, maxBytes) {
+  let url = allowedMetaImageUrl(rawUrl);
+  if (!url) throw new Error("image_host_not_allowed");
+  for (let redirect = 0; redirect <= MAX_REDIRECTS; redirect++) {
+    const response = await fetch(url, {
+      redirect: "manual",
+      headers: { Accept: "image/jpeg,image/png,image/webp,image/gif;q=0.8" },
+      signal: AbortSignal.timeout(12e3)
+    });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      const location = response.headers.get("location");
+      if (!location || redirect === MAX_REDIRECTS) throw new Error("image_redirect_rejected");
+      url = allowedMetaImageUrl(new URL(location, url).href);
+      if (!url) throw new Error("image_redirect_host_not_allowed");
+      continue;
+    }
+    if (!response.ok) throw new Error(`image_fetch_${response.status}`);
+    const bytes = await readBoundedBody(response, maxBytes);
+    const mimeType = detectImageMime(bytes);
+    if (!mimeType) throw new Error("image_content_invalid");
+    return { bytes, mimeType, finalUrl: url.href };
+  }
+  throw new Error("image_redirect_rejected");
+}
+function firstString(row, keys) {
+  for (const key of keys) {
+    const value = row[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return null;
+}
+function displayUrl(raw) {
+  try {
+    const url = new URL(raw);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return "[invalid media URL]";
+  }
+}
+async function buildMetaAdCreativeMediaResult(executor, input) {
+  const providerResult = await executor.readServiceConnection({
+    connectionId: input.connectionId,
+    tool: "resolve-ad-creative-media",
+    args: { adId: input.adId }
+  });
+  if (providerResult.isError) return providerResult;
+  const payload = parseToolPayload(providerResult);
+  const resolved = asRecord(payload?.["result"]) ?? payload;
+  if (!resolved || typeof resolved["creativeId"] !== "string") {
+    return {
+      content: [{ type: "text", text: "Meta returned an invalid creative-media result. Confirm that resolve-ad-creative-media is deployed and this connection can read the ad." }],
+      isError: true
+    };
+  }
+  const warnings = Array.isArray(resolved["warnings"]) ? resolved["warnings"].filter((value) => typeof value === "string") : [];
+  const limitations = Array.isArray(resolved["limitations"]) ? resolved["limitations"].filter((value) => typeof value === "string") : [];
+  const images = Array.isArray(resolved["images"]) ? resolved["images"].map(asRecord).filter((value) => value !== null) : [];
+  const videos = Array.isArray(resolved["videos"]) ? resolved["videos"].map(asRecord).filter((value) => value !== null) : [];
+  const nextActions = Array.isArray(resolved["nextActions"]) ? resolved["nextActions"].map(asRecord).filter((value) => value !== null) : [];
+  const content = [];
+  const inlineImages = [];
+  if (input.imageMode === "inline_preview") {
+    let remaining = MAX_TOTAL_IMAGE_BYTES;
+    const seen = /* @__PURE__ */ new Set();
+    for (const image of images) {
+      if (inlineImages.length >= input.maxInlineImages || remaining <= 0) break;
+      const sourceUrl = firstString(image, ["url", "thumbnailUrl", "permalinkUrl"]);
+      if (!sourceUrl || seen.has(sourceUrl)) continue;
+      seen.add(sourceUrl);
+      try {
+        const fetched = await fetchMetaImage(sourceUrl, Math.min(MAX_IMAGE_BYTES, remaining));
+        const contentIndex = content.length + 1;
+        content.push({ type: "image", data: Buffer.from(fetched.bytes).toString("base64"), mimeType: fetched.mimeType });
+        inlineImages.push({ sourceUrl: fetched.finalUrl, mimeType: fetched.mimeType, bytes: fetched.bytes.byteLength, contentIndex });
+        remaining -= fetched.bytes.byteLength;
+      } catch (error) {
+        const code = error instanceof Error ? error.message : "image_fetch_failed";
+        warnings.push(`Creative image preview could not be attached (${code}) for ${displayUrl(sourceUrl)}.`);
+      }
+    }
+  }
+  const mediaType = typeof resolved["mediaType"] === "string" ? resolved["mediaType"] : "unknown";
+  const publicPostCandidateUrl = typeof resolved["publicPostCandidateUrl"] === "string" ? resolved["publicPostCandidateUrl"] : null;
+  const summary = [
+    "# Meta Ad Creative Media",
+    `**Ad:** ${typeof resolved["adName"] === "string" ? resolved["adName"] : input.adId} (\`${input.adId}\`)`,
+    `**Creative:** ${typeof resolved["creativeName"] === "string" ? resolved["creativeName"] : resolved["creativeId"]} (\`${resolved["creativeId"]}\`)`,
+    `**Media:** ${mediaType} \xB7 ${images.length} image descriptor(s) \xB7 ${videos.length} video descriptor(s) \xB7 ${inlineImages.length} inline visual preview(s)`,
+    publicPostCandidateUrl ? `**Public post candidate:** ${publicPostCandidateUrl} (unverified; dark/paused ads may not be public)` : "",
+    nextActions.length ? `
+## Recommended next calls
+${nextActions.map((action) => `- \`${String(action["tool"] ?? "")}\`: ${String(action["reason"] ?? "")}`).join("\n")}` : "",
+    warnings.length ? `
+## Warnings
+${warnings.map((warning) => `- ${warning}`).join("\n")}` : "",
+    limitations.length ? `
+## Limitations
+${limitations.map((limitation) => `- ${limitation}`).join("\n")}` : ""
+  ].filter(Boolean).join("\n");
+  content.unshift({ type: "text", text: summary });
+  return {
+    content,
+    structuredContent: {
+      ok: true,
+      adId: String(resolved["adId"] ?? input.adId),
+      adName: typeof resolved["adName"] === "string" ? resolved["adName"] : null,
+      adAccountId: typeof resolved["adAccountId"] === "string" ? resolved["adAccountId"] : null,
+      creativeId: String(resolved["creativeId"]),
+      creativeName: typeof resolved["creativeName"] === "string" ? resolved["creativeName"] : null,
+      effectiveObjectStoryId: typeof resolved["effectiveObjectStoryId"] === "string" ? resolved["effectiveObjectStoryId"] : null,
+      sourceFacebookPostId: typeof resolved["sourceFacebookPostId"] === "string" ? resolved["sourceFacebookPostId"] : null,
+      objectStoryId: typeof resolved["objectStoryId"] === "string" ? resolved["objectStoryId"] : null,
+      pageId: typeof resolved["pageId"] === "string" ? resolved["pageId"] : null,
+      postId: typeof resolved["postId"] === "string" ? resolved["postId"] : null,
+      publicPostCandidateUrl,
+      publicPostStatus: "unverified",
+      mediaType,
+      images,
+      videos,
+      inlineImages,
+      nextActions,
+      warnings,
+      limitations
+    }
+  };
+}
+
 // src/mcp/mcp-tool-schemas.ts
 import { z } from "zod";
 var HarvestPaaInputSchema = {
@@ -3081,7 +3379,7 @@ var YoutubeTranscribeInputSchema = {
 var FacebookPageIntelInputSchema = {
   pageId: z.string().optional().describe("Facebook advertiser/page ID. Use only a value returned by facebook_ad_search or copied from Ad Library."),
   libraryId: z.string().optional().describe("Facebook Ad Library archive ID. Use a value returned by facebook_ad_search, or a libraryId/adArchiveId visible in Ad Library."),
-  query: z.string().optional().describe("Advertiser or brand name when pageId/libraryId is not known. One of pageId, libraryId, or query is required."),
+  query: z.string().optional().describe("Broad Ad Library keyword discovery when pageId/libraryId is not known. Results can mix unrelated advertisers; inspect matchConfidence, matchedAdvertisers, and warnings before analysis. One of pageId, libraryId, or query is required."),
   maxAds: z.number().int().min(1).max(200).default(50).describe("Maximum ads to inspect. Default 50, maximum 200."),
   country: z.string().length(2).default("US").describe("Two-letter Ad Library country code. Default US.")
 };
@@ -3105,10 +3403,10 @@ var VideoFrameAnalysisStatusInputSchema = {
   runId: z.string().min(1).describe("The runId returned by video_frame_analysis.")
 };
 var FacebookAdTranscribeInputSchema = {
-  videoUrl: z.string().url().describe("Direct Facebook CDN video URL from facebook_page_intel. Do not pass a public post/reel/share URL \u2014 use facebook_video_transcribe for those.")
+  videoUrl: z.string().url().describe("Direct Meta/Facebook CDN video URL from facebook_page_intel or meta_ad_creative_media. Use transient sources immediately. Do not pass a public post/reel/share URL\u2014use facebook_video_transcribe for those.")
 };
 var FacebookVideoTranscribeInputSchema = {
-  url: z.string().url().describe("Organic Facebook reel/video/watch/post/share URL from facebook.com, m.facebook.com, or fb.watch."),
+  url: z.string().url().describe("Public Facebook reel/video/watch/post/share URL from facebook.com, m.facebook.com, or fb.watch. For connected account ads, get the correct public candidate from meta_ad_creative_media instead of guessing URL structure."),
   quality: z.enum(["best", "hd", "sd"]).default("best").describe("Preferred progressive MP4 quality. Use best by default; hd prefers the highest HD progressive URL; sd forces the SD URL.")
 };
 var GoogleAdsSearchInputSchema = {
@@ -3663,6 +3961,11 @@ var RedditThreadOutputSchema = {
 };
 var FacebookPageIntelOutputSchema = {
   advertiserName: NullableString,
+  inputMode: z.enum(["pageId", "libraryId", "query"]),
+  matchConfidence: z.enum(["high", "medium", "low"]),
+  matchReason: z.string(),
+  warnings: z.array(z.string()),
+  matchedAdvertisers: z.array(z.object({ name: z.string(), adCount: z.number().int().min(0) })),
   totalAds: z.number().int().min(0),
   activeCount: z.number().int().min(0),
   videoCount: z.number().int().min(0),
@@ -3717,6 +4020,16 @@ var GoogleAdsPageIntelOutputSchema = {
     variations: z.number().int().nullable()
   }))
 };
+var TranscriptSignalOutput = z.object({
+  status: z.enum(["speech_detected", "low_speech_signal", "empty"]),
+  speechDetected: z.boolean(),
+  confidence: z.enum(["medium", "low"]),
+  basis: z.literal("transcript_word_count_and_timing"),
+  mediaDurationSec: z.number().nullable(),
+  wordsPerMinute: z.number().nullable(),
+  retryRecommended: z.boolean(),
+  warnings: z.array(z.string())
+});
 var FacebookVideoTranscribeOutputSchema = {
   sourceUrl: z.string().url(),
   pageUrl: z.string().url(),
@@ -3733,7 +4046,8 @@ var FacebookVideoTranscribeOutputSchema = {
     startSec: z.number(),
     endSec: z.number(),
     text: z.string()
-  }))
+  })),
+  transcriptSignal: TranscriptSignalOutput
 };
 var TranscriptChunkOutput = z.object({
   startSec: z.number(),
@@ -3855,6 +4169,7 @@ var FacebookAdTranscribeOutputSchema = {
   durationMs: z.number().nullable(),
   transcriptText: z.string(),
   chunks: z.array(TranscriptChunkOutput),
+  transcriptSignal: TranscriptSignalOutput,
   resolvedInputs: z.object({
     videoUrl: z.string().url()
   })
@@ -4087,6 +4402,43 @@ var ReadServiceConnectionOutputSchema = {
   result: z.unknown().optional(),
   error: NullableString
 };
+var MetaAdCreativeMediaInputSchema = {
+  connectionId: z.string().min(1).describe("Tenant-owned Meta Marketing connectionId from list_service_connections."),
+  adId: z.string().regex(/^\d{5,30}$/).describe("Meta ad ID from the connected ad account. This is not an Ad Library archive ID."),
+  imageMode: z.enum(["inline_preview", "resource_only", "none"]).default("inline_preview").describe("inline_preview returns bounded MCP image content that a vision-capable client can inspect. resource_only returns descriptors/URLs only. none skips image delivery."),
+  maxInlineImages: z.number().int().min(1).max(4).default(2).describe("Maximum creative image/thumbnail previews to attach as MCP image blocks. Default 2; maximum 4.")
+};
+var MetaAdCreativeMediaOutputSchema = {
+  ok: z.boolean(),
+  adId: z.string(),
+  adName: NullableString,
+  adAccountId: NullableString,
+  creativeId: z.string(),
+  creativeName: NullableString,
+  effectiveObjectStoryId: NullableString,
+  sourceFacebookPostId: NullableString,
+  objectStoryId: NullableString,
+  pageId: NullableString,
+  postId: NullableString,
+  publicPostCandidateUrl: NullableString,
+  publicPostStatus: z.literal("unverified"),
+  mediaType: z.enum(["image", "video", "carousel", "mixed", "unknown"]),
+  images: z.array(z.record(z.string(), z.unknown())),
+  videos: z.array(z.record(z.string(), z.unknown())),
+  inlineImages: z.array(z.object({
+    sourceUrl: z.string().url(),
+    mimeType: z.string(),
+    bytes: z.number().int().min(0),
+    contentIndex: z.number().int().min(1)
+  })),
+  nextActions: z.array(z.object({
+    tool: z.enum(["facebook_ad_transcribe", "facebook_video_transcribe", "video_frame_analysis"]),
+    args: z.record(z.string(), z.unknown()),
+    reason: z.string()
+  })),
+  warnings: z.array(z.string()),
+  limitations: z.array(z.string())
+};
 var ImportServiceConnectionToMemoryInputSchema = {
   connectionId: z.string().min(1).max(200).describe("A tenant-owned connectionId from list_service_connections."),
   providerConfigKey: z.string().min(1).max(200).describe("The exact providerConfigKey returned with that connection. It is matched together with connectionId against the authenticated caller."),
@@ -4764,7 +5116,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => formatYoutubeTranscribe(await executor.youtubeTranscribe(input), input));
   server.registerTool("facebook_page_intel", {
     title: "Facebook Advertiser Ad Intel",
-    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.",
+    description: "Harvest public Ad Library creatives. Prefer exact pageId/libraryId; query is broad keyword discovery and can mix unrelated advertisers, so inspect matchConfidence/warnings before analysis. Paused or inactive non-political ads may be absent from Ad Library\u2014use meta_ad_creative_media with the connected ad account for those. Direct Ad Library videoUrl values go to facebook_ad_transcribe.",
     inputSchema: FacebookPageIntelInputSchema,
     outputSchema: recordOutputSchema("facebook_page_intel", FacebookPageIntelOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Advertiser Ad Intel")
@@ -4799,7 +5151,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => executor.videoFrameAnalysisStatus(input));
   server.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).",
+    description: "Transcribe a direct Meta/Facebook CDN video source returned by facebook_page_intel or meta_ad_creative_media. CDN sources can expire, so use them immediately. Do not pass public post/reel/share URLs; use facebook_video_transcribe for those. For a paused/account-owned ad, start with meta_ad_creative_media: it selects the direct Graph source when available and otherwise returns the effective organic-post candidate.",
     inputSchema: FacebookAdTranscribeInputSchema,
     outputSchema: recordOutputSchema("facebook_ad_transcribe", FacebookAdTranscribeOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Ad Transcription")
@@ -4827,7 +5179,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => formatGoogleAdsTranscribe(await executor.googleAdsTranscribe(input), input));
   server.registerTool("facebook_video_transcribe", {
     title: "Facebook Organic Video Transcription",
-    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.",
+    description: "Transcribe audio from a public Facebook reel/video/post/share URL (including fb.watch). Renders the public page, selects the best progressive MP4, and returns transcript plus resolved metadata and a low-speech signal. For a connected paused ad, use meta_ad_creative_media first; pass its public post/permalink candidate here only when no direct Graph source is available. Dark/unpublished ads may not have a public route.",
     inputSchema: FacebookVideoTranscribeInputSchema,
     outputSchema: recordOutputSchema("facebook_video_transcribe", FacebookVideoTranscribeOutputSchema),
     annotations: liveWebToolAnnotations("Facebook Organic Video Transcription")
@@ -5005,6 +5357,13 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
     outputSchema: recordOutputSchema("read_service_connection", ReadServiceConnectionOutputSchema),
     annotations: { title: "Read Connected Service", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
   }, async (input) => executor.readServiceConnection(input));
+  server.registerTool("meta_ad_creative_media", {
+    title: "View Meta Ad Creative Media",
+    description: "Preferred connected-account path for viewing a Meta ad creative, especially paused or dark ads that may be absent from Ad Library. Given a tenant-owned Meta connectionId and adId, resolves the ad, creative, effective story/post candidate, image assets, video assets, and transient Graph playback source. Bounded creative images are returned as actual MCP image content for vision-capable clients. For video, follow the returned exact nextActions with facebook_ad_transcribe when Graph returned a direct source, facebook_video_transcribe when only a public post/video candidate is available, or video_frame_analysis for visual breakdown. This tool is read-only and does not itself spend transcription/analysis credits.",
+    inputSchema: MetaAdCreativeMediaInputSchema,
+    outputSchema: recordOutputSchema("meta_ad_creative_media", MetaAdCreativeMediaOutputSchema),
+    annotations: { title: "View Meta Ad Creative Media", readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+  }, async (input) => buildMetaAdCreativeMediaResult(executor, input));
   server.registerTool("import_service_connection_to_memory", {
     title: "Import Connected Service Snapshot to Memory",
     description: "Run exactly one bounded, approved read on a tenant-owned connected service and upsert the redacted result into an existing ordinary Memory vault at a server-generated stable path. The saved document is embedded for RAG and marked as untrusted provider data, never instructions. This is a one-result snapshot: it does not paginate, bulk-import an account, continuously sync changes, propagate deletions, or create normalized tables. Use list_service_connections first and supply an exact current readTools entry; action and admin tools are rejected.",
@@ -9316,6 +9675,8 @@ export {
   sanitizeAttempts,
   sanitizeHarvestResult,
   buildLinkGraph,
+  assessTranscriptSignal,
+  transcribeMediaUrl,
   createConnectedDataArtifact,
   renewConnectedDataArtifactDownload,
   cleanupExpiredConnectedDataArtifacts,
@@ -9332,4 +9693,4 @@ export {
   registerMemoryMcpTools,
   MemoryMcpToolExecutor
 };
-//# sourceMappingURL=chunk-FMEDPBIV.js.map
+//# sourceMappingURL=chunk-O2S5TOCG.js.map