mcp-scraper 0.18.0 → 0.19.0

package/dist/bin/api-server.cjs

@@ -13647,6 +13647,39 @@ var init_audio_resolver = __esm({
 });
 
 // src/services/media-transcription.ts
+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 fmtTs2 = (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, ""];
@@ -13676,7 +13709,8 @@ async function transcribeMediaUrl(mediaUrl, markdownTitle = "# Media Transcript"
     chunks,
     durationMs,
     costUsd,
-    markdown: transcriptMarkdown(markdownTitle, text, chunks, durationMs)
+    markdown: transcriptMarkdown(markdownTitle, text, chunks, durationMs),
+    transcriptSignal: assessTranscriptSignal(text, chunks)
   };
 }
 var import_client3;
@@ -14969,11 +15003,13 @@ var init_FacebookAdExtractor = __esm({
           if (n) nameFreq.set(n, (nameFreq.get(n) ?? 0) + 1);
         }
         const advertiserName = nameFreq.size ? [...nameFreq.entries()].sort((a, b) => b[1] - a[1])[0][0] : null;
+        const matchedAdvertisers = [...nameFreq.entries()].map(([name, adCount]) => ({ name, adCount })).sort((a, b) => b.adCount - a.adCount).slice(0, 20);
         return {
           listingUrl,
           scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
           advertiserPageId,
           advertiserName,
+          matchedAdvertisers,
           summary: {
             totalAds,
             activeCount,
@@ -15496,6 +15532,45 @@ function buildPageIntelUrl(body, country) {
   if (body.pageId?.trim()) return `https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=${country}&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=${body.pageId.trim()}`;
   return `https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=${country}&q=${encodeURIComponent(body.query.trim())}&search_type=keyword_unordered`;
 }
+function normalizeAdvertiserName(value) {
+  return value.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, " ").trim().replace(/\s+/g, " ");
+}
+function advertiserTokenOverlap(query, candidate) {
+  const queryTokens = new Set(normalizeAdvertiserName(query).split(" ").filter(Boolean));
+  const candidateTokens = new Set(normalizeAdvertiserName(candidate).split(" ").filter(Boolean));
+  if (queryTokens.size === 0 || candidateTokens.size === 0) return 0;
+  let overlap = 0;
+  for (const token of queryTokens) if (candidateTokens.has(token)) overlap++;
+  return overlap / queryTokens.size;
+}
+function assessPageIntelMatch(body, result) {
+  if (body.pageId) return { inputMode: "pageId", matchConfidence: "high", matchReason: "Exact Facebook page ID filter.", warnings: [] };
+  if (body.libraryId) return { inputMode: "libraryId", matchConfidence: "high", matchReason: "Exact Ad Library archive ID filter.", warnings: [] };
+  const query = body.query?.trim() ?? "";
+  const normalizedQuery = normalizeAdvertiserName(query);
+  const matches = result.matchedAdvertisers ?? [];
+  const exact = matches.find((match) => normalizeAdvertiserName(match.name) === normalizedQuery);
+  const top = matches[0];
+  const topShare = top && result.summary.totalAds > 0 ? top.adCount / result.summary.totalAds : 0;
+  const overlap = top ? advertiserTokenOverlap(query, top.name) : 0;
+  const warnings = [];
+  let matchConfidence;
+  let matchReason;
+  if (exact && exact.adCount / Math.max(1, result.summary.totalAds) >= 0.7) {
+    matchConfidence = "high";
+    matchReason = "The exact advertiser name accounts for most returned ads.";
+  } else if (top && overlap >= 0.75 && topShare >= 0.5) {
+    matchConfidence = "medium";
+    matchReason = "The leading advertiser overlaps strongly with the query, but keyword search is not page-scoped.";
+  } else {
+    matchConfidence = "low";
+    matchReason = "Keyword search did not identify one dominant exact advertiser match.";
+  }
+  if (matches.length > 1) warnings.push(`Keyword search mixed ${matches.length} advertiser names. Confirm the intended pageId before using these ads for performance or creative analysis.`);
+  if (matchConfidence === "low") warnings.push("Low-specificity Ad Library match: treat these results as discovery candidates, not as verified ads from the requested brand.");
+  warnings.push("Paused, cancelled, or otherwise inactive non-political ads may be absent from Ad Library. Use meta_ad_creative_media for connected ad-account creatives.");
+  return { inputMode: "query", matchConfidence, matchReason, warnings };
+}
 function configuredKernelProxy() {
   return (process.env.BROWSER_SERVICE_PROXY_ID ?? process.env.KERNEL_PROXY_ID)?.trim() || void 0;
 }
@@ -15643,8 +15718,10 @@ var init_facebook_ad_routes = __esm({
           await logRequestEvent({ userId: fbUser.id, source: "facebook_page_intel", status: "failed", query: body.pageId ?? body.query ?? body.libraryId ?? "", error: "soft-block: empty result refunded" });
           return c.json({ error: "soft-block: no ads returned (refunded)" }, 503);
         }
-        await logRequestEvent({ userId: fbUser.id, source: "facebook_page_intel", status: "done", query: body.pageId ?? body.query ?? body.libraryId ?? "", resultCount: result.ads.length, result });
-        return c.json(result);
+        const match = assessPageIntelMatch(body, result);
+        const output = { ...result, ...match };
+        await logRequestEvent({ userId: fbUser.id, source: "facebook_page_intel", status: "done", query: body.pageId ?? body.query ?? body.libraryId ?? "", resultCount: result.ads.length, result: output });
+        return c.json(output);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         if (debited && !refunded) await creditMc(fbUser.id, MC_COSTS.fb_ad, LedgerOperation.FB_AD_REFUND, "failed call");
@@ -15745,7 +15822,8 @@ var init_facebook_ad_routes = __esm({
           text: transcript.text,
           chunks: transcript.chunks,
           durationMs: transcript.durationMs,
-          markdown: transcript.markdown
+          markdown: transcript.markdown,
+          transcriptSignal: assessTranscriptSignal(transcript.text, transcript.chunks, video.durationSec)
         };
         await logRequestEvent({ userId: fbUser.id, source: "facebook_video_transcribe", status: "done", query: sourceUrl.href, resultCount: transcript.chunks.length, result });
         return c.json(result);
@@ -20257,6 +20335,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}` : "",
@@ -20269,19 +20348,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,
@@ -21210,6 +21298,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");
@@ -21218,7 +21307,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}`,
@@ -21240,6 +21331,7 @@ ${chunkRows}` : "",
       durationMs: typeof d.durationMs === "number" ? d.durationMs : null,
       transcriptText: text,
       chunks: structuredTranscriptChunks(chunks),
+      transcriptSignal: signal,
       resolvedInputs: {
         videoUrl: input.videoUrl
       }
@@ -21256,6 +21348,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");
@@ -21266,6 +21359,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}\`` : "",
     `
@@ -21298,7 +21394,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
     }
   };
 }
@@ -21614,6 +21711,7 @@ var init_mcp_response_formatter = __esm({
     init_image_audit();
     init_report_artifact_offload();
     init_rates();
+    init_media_transcription();
     INLINE_BUDGET_BYTES = Number(process.env.MCP_SCRAPER_INLINE_BUDGET ?? 5e4);
     STRUCTURED_ARRAY_CAP = 25;
     reportSavingEnabled = true;
@@ -27642,7 +27740,7 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.18.0";
+    PACKAGE_VERSION = "0.19.0";
   }
 });
 
@@ -27682,10 +27780,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).
@@ -27727,8 +27829,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\`.
 
@@ -27737,6 +27839,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.
 
@@ -27814,8 +27918,216 @@ var init_output_schema_registry = __esm({
   }
 });
 
+// src/mcp/meta-ad-creative-media.ts
+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((suffix2) => host === suffix2 || host.endsWith(`.${suffix2}`))) 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 location2 = response.headers.get("location");
+      if (!location2 || redirect === MAX_REDIRECTS) throw new Error("image_redirect_rejected");
+      url = allowedMetaImageUrl(new URL(location2, 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
+    }
+  };
+}
+var META_IMAGE_HOSTS, MAX_IMAGE_BYTES, MAX_TOTAL_IMAGE_BYTES, MAX_REDIRECTS;
+var init_meta_ad_creative_media = __esm({
+  "src/mcp/meta-ad-creative-media.ts"() {
+    "use strict";
+    META_IMAGE_HOSTS = ["facebook.com", "fbcdn.net", "fbsbx.com", "cdninstagram.com"];
+    MAX_IMAGE_BYTES = 15e5;
+    MAX_TOTAL_IMAGE_BYTES = 25e5;
+    MAX_REDIRECTS = 3;
+  }
+});
+
 // src/mcp/mcp-tool-schemas.ts
-var import_zod33, HarvestPaaInputSchema, ExtractUrlInputSchema, DiffPageInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, AuditSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, RedditThreadInputSchema, VideoFrameAnalysisInputSchema, VideoFrameAnalysisStatusInputSchema, FacebookAdTranscribeInputSchema, FacebookVideoTranscribeInputSchema, GoogleAdsSearchInputSchema, GoogleAdsPageIntelInputSchema, GoogleAdsTranscribeInputSchema, InstagramProfileContentInputSchema, InstagramMediaDownloadInputSchema, MapsPlaceIntelInputSchema, TrustpilotReviewsInputSchema, G2ReviewsInputSchema, ReviewCardSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, ArtifactPointerOutputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, DiffPageOutputSchema, ExtractSiteOutputSchema, AuditSiteOutputSchema, MapsPlaceIntelOutputSchema, TrustpilotReviewsOutputSchema, G2ReviewsOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, VideoFrameAnalysisOutputSchema, VideoFrameAnalysisStatusOutputSchema, RedditThreadOutputSchema, FacebookPageIntelOutputSchema, GoogleAdsSearchOutputSchema, GoogleAdsPageIntelOutputSchema, FacebookVideoTranscribeOutputSchema, TranscriptChunkOutput, InstagramBrowserOutput, InstagramPaginationOutput, InstagramProfileContentOutputSchema, InstagramMediaTrackOutput, InstagramDownloadOutput, InstagramMediaDownloadOutputSchema, YoutubeTranscribeOutputSchema, FacebookAdTranscribeOutputSchema, GoogleAdsTranscribeOutputSchema, CaptureSerpSnapshotOutputSchema, CaptureSerpPageSnapshotsOutputSchema, CreditsInfoInputSchema, WorkflowIdSchema2, WorkflowListInputSchema, WorkflowSuggestInputSchema, WorkflowRunInputSchema, WorkflowStepInputSchema, WorkflowStatusInputSchema, WorkflowArtifactReadInputSchema, WorkflowRecipeOutput, WorkflowDefinitionOutput, WorkflowArtifactOutput, WorkflowListOutputSchema, WorkflowSuggestOutputSchema, WorkflowRunOutputSchema, WorkflowStepOutputSchema, WorkflowStatusOutputSchema, WorkflowArtifactReadOutputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema, ReportArtifactReadInputSchema, ReportArtifactReadOutputSchema, ListServiceConnectionsInputSchema, ListServiceConnectionsOutputSchema, ReadServiceConnectionInputSchema, ReadServiceConnectionOutputSchema, ImportServiceConnectionToMemoryInputSchema, ImportServiceConnectionToMemoryOutputSchema, DescribeServiceConnectionToolInputSchema, DescribeServiceConnectionToolOutputSchema, ConnectedDataContinuationSchema, ExportConnectedServiceDataInputSchema, ConnectedDataArtifactSchema, ExportConnectedServiceDataOutputSchema, RenewConnectedDataExportDownloadInputSchema, RenewConnectedDataExportDownloadOutputSchema, CallServiceConnectionActionInputSchema, CallServiceConnectionActionOutputSchema, SetScheduledActionConnectionsInputSchema, SetScheduledActionConnectionsOutputSchema, SlackSendMessageInputSchema, SlackSendMessageOutputSchema, GmailSendMessageInputSchema, GmailSendMessageOutputSchema, GoogleCalendarCreateEventInputSchema, GoogleCalendarCreateEventOutputSchema, ZoomCreateMeetingInputSchema, ZoomCreateMeetingOutputSchema;
+var import_zod33, HarvestPaaInputSchema, ExtractUrlInputSchema, DiffPageInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, AuditSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, RedditThreadInputSchema, VideoFrameAnalysisInputSchema, VideoFrameAnalysisStatusInputSchema, FacebookAdTranscribeInputSchema, FacebookVideoTranscribeInputSchema, GoogleAdsSearchInputSchema, GoogleAdsPageIntelInputSchema, GoogleAdsTranscribeInputSchema, InstagramProfileContentInputSchema, InstagramMediaDownloadInputSchema, MapsPlaceIntelInputSchema, TrustpilotReviewsInputSchema, G2ReviewsInputSchema, ReviewCardSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, ArtifactPointerOutputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, DiffPageOutputSchema, ExtractSiteOutputSchema, AuditSiteOutputSchema, MapsPlaceIntelOutputSchema, TrustpilotReviewsOutputSchema, G2ReviewsOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, VideoFrameAnalysisOutputSchema, VideoFrameAnalysisStatusOutputSchema, RedditThreadOutputSchema, FacebookPageIntelOutputSchema, GoogleAdsSearchOutputSchema, GoogleAdsPageIntelOutputSchema, TranscriptSignalOutput, FacebookVideoTranscribeOutputSchema, TranscriptChunkOutput, InstagramBrowserOutput, InstagramPaginationOutput, InstagramProfileContentOutputSchema, InstagramMediaTrackOutput, InstagramDownloadOutput, InstagramMediaDownloadOutputSchema, YoutubeTranscribeOutputSchema, FacebookAdTranscribeOutputSchema, GoogleAdsTranscribeOutputSchema, CaptureSerpSnapshotOutputSchema, CaptureSerpPageSnapshotsOutputSchema, CreditsInfoInputSchema, WorkflowIdSchema2, WorkflowListInputSchema, WorkflowSuggestInputSchema, WorkflowRunInputSchema, WorkflowStepInputSchema, WorkflowStatusInputSchema, WorkflowArtifactReadInputSchema, WorkflowRecipeOutput, WorkflowDefinitionOutput, WorkflowArtifactOutput, WorkflowListOutputSchema, WorkflowSuggestOutputSchema, WorkflowRunOutputSchema, WorkflowStepOutputSchema, WorkflowStatusOutputSchema, WorkflowArtifactReadOutputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema, ReportArtifactReadInputSchema, ReportArtifactReadOutputSchema, ListServiceConnectionsInputSchema, ListServiceConnectionsOutputSchema, ReadServiceConnectionInputSchema, ReadServiceConnectionOutputSchema, MetaAdCreativeMediaInputSchema, MetaAdCreativeMediaOutputSchema, ImportServiceConnectionToMemoryInputSchema, ImportServiceConnectionToMemoryOutputSchema, DescribeServiceConnectionToolInputSchema, DescribeServiceConnectionToolOutputSchema, ConnectedDataContinuationSchema, ExportConnectedServiceDataInputSchema, ConnectedDataArtifactSchema, ExportConnectedServiceDataOutputSchema, RenewConnectedDataExportDownloadInputSchema, RenewConnectedDataExportDownloadOutputSchema, CallServiceConnectionActionInputSchema, CallServiceConnectionActionOutputSchema, SetScheduledActionConnectionsInputSchema, SetScheduledActionConnectionsOutputSchema, SlackSendMessageInputSchema, SlackSendMessageOutputSchema, GmailSendMessageInputSchema, GmailSendMessageOutputSchema, GoogleCalendarCreateEventInputSchema, GoogleCalendarCreateEventOutputSchema, ZoomCreateMeetingInputSchema, ZoomCreateMeetingOutputSchema;
 var init_mcp_tool_schemas = __esm({
   "src/mcp/mcp-tool-schemas.ts"() {
     "use strict";
@@ -27878,7 +28190,7 @@ var init_mcp_tool_schemas = __esm({
     FacebookPageIntelInputSchema = {
       pageId: import_zod33.z.string().optional().describe("Facebook advertiser/page ID. Use only a value returned by facebook_ad_search or copied from Ad Library."),
       libraryId: import_zod33.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: import_zod33.z.string().optional().describe("Advertiser or brand name when pageId/libraryId is not known. One of pageId, libraryId, or query is required."),
+      query: import_zod33.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: import_zod33.z.number().int().min(1).max(200).default(50).describe("Maximum ads to inspect. Default 50, maximum 200."),
       country: import_zod33.z.string().length(2).default("US").describe("Two-letter Ad Library country code. Default US.")
     };
@@ -27902,10 +28214,10 @@ var init_mcp_tool_schemas = __esm({
       runId: import_zod33.z.string().min(1).describe("The runId returned by video_frame_analysis.")
     };
     FacebookAdTranscribeInputSchema = {
-      videoUrl: import_zod33.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: import_zod33.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.")
     };
     FacebookVideoTranscribeInputSchema = {
-      url: import_zod33.z.string().url().describe("Organic Facebook reel/video/watch/post/share URL from facebook.com, m.facebook.com, or fb.watch."),
+      url: import_zod33.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: import_zod33.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.")
     };
     GoogleAdsSearchInputSchema = {
@@ -28460,6 +28772,11 @@ var init_mcp_tool_schemas = __esm({
     };
     FacebookPageIntelOutputSchema = {
       advertiserName: NullableString,
+      inputMode: import_zod33.z.enum(["pageId", "libraryId", "query"]),
+      matchConfidence: import_zod33.z.enum(["high", "medium", "low"]),
+      matchReason: import_zod33.z.string(),
+      warnings: import_zod33.z.array(import_zod33.z.string()),
+      matchedAdvertisers: import_zod33.z.array(import_zod33.z.object({ name: import_zod33.z.string(), adCount: import_zod33.z.number().int().min(0) })),
       totalAds: import_zod33.z.number().int().min(0),
       activeCount: import_zod33.z.number().int().min(0),
       videoCount: import_zod33.z.number().int().min(0),
@@ -28514,6 +28831,16 @@ var init_mcp_tool_schemas = __esm({
         variations: import_zod33.z.number().int().nullable()
       }))
     };
+    TranscriptSignalOutput = import_zod33.z.object({
+      status: import_zod33.z.enum(["speech_detected", "low_speech_signal", "empty"]),
+      speechDetected: import_zod33.z.boolean(),
+      confidence: import_zod33.z.enum(["medium", "low"]),
+      basis: import_zod33.z.literal("transcript_word_count_and_timing"),
+      mediaDurationSec: import_zod33.z.number().nullable(),
+      wordsPerMinute: import_zod33.z.number().nullable(),
+      retryRecommended: import_zod33.z.boolean(),
+      warnings: import_zod33.z.array(import_zod33.z.string())
+    });
     FacebookVideoTranscribeOutputSchema = {
       sourceUrl: import_zod33.z.string().url(),
       pageUrl: import_zod33.z.string().url(),
@@ -28530,7 +28857,8 @@ var init_mcp_tool_schemas = __esm({
         startSec: import_zod33.z.number(),
         endSec: import_zod33.z.number(),
         text: import_zod33.z.string()
-      }))
+      })),
+      transcriptSignal: TranscriptSignalOutput
     };
     TranscriptChunkOutput = import_zod33.z.object({
       startSec: import_zod33.z.number(),
@@ -28652,6 +28980,7 @@ var init_mcp_tool_schemas = __esm({
       durationMs: import_zod33.z.number().nullable(),
       transcriptText: import_zod33.z.string(),
       chunks: import_zod33.z.array(TranscriptChunkOutput),
+      transcriptSignal: TranscriptSignalOutput,
       resolvedInputs: import_zod33.z.object({
         videoUrl: import_zod33.z.string().url()
       })
@@ -28884,6 +29213,43 @@ var init_mcp_tool_schemas = __esm({
       result: import_zod33.z.unknown().optional(),
       error: NullableString
     };
+    MetaAdCreativeMediaInputSchema = {
+      connectionId: import_zod33.z.string().min(1).describe("Tenant-owned Meta Marketing connectionId from list_service_connections."),
+      adId: import_zod33.z.string().regex(/^\d{5,30}$/).describe("Meta ad ID from the connected ad account. This is not an Ad Library archive ID."),
+      imageMode: import_zod33.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: import_zod33.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.")
+    };
+    MetaAdCreativeMediaOutputSchema = {
+      ok: import_zod33.z.boolean(),
+      adId: import_zod33.z.string(),
+      adName: NullableString,
+      adAccountId: NullableString,
+      creativeId: import_zod33.z.string(),
+      creativeName: NullableString,
+      effectiveObjectStoryId: NullableString,
+      sourceFacebookPostId: NullableString,
+      objectStoryId: NullableString,
+      pageId: NullableString,
+      postId: NullableString,
+      publicPostCandidateUrl: NullableString,
+      publicPostStatus: import_zod33.z.literal("unverified"),
+      mediaType: import_zod33.z.enum(["image", "video", "carousel", "mixed", "unknown"]),
+      images: import_zod33.z.array(import_zod33.z.record(import_zod33.z.string(), import_zod33.z.unknown())),
+      videos: import_zod33.z.array(import_zod33.z.record(import_zod33.z.string(), import_zod33.z.unknown())),
+      inlineImages: import_zod33.z.array(import_zod33.z.object({
+        sourceUrl: import_zod33.z.string().url(),
+        mimeType: import_zod33.z.string(),
+        bytes: import_zod33.z.number().int().min(0),
+        contentIndex: import_zod33.z.number().int().min(1)
+      })),
+      nextActions: import_zod33.z.array(import_zod33.z.object({
+        tool: import_zod33.z.enum(["facebook_ad_transcribe", "facebook_video_transcribe", "video_frame_analysis"]),
+        args: import_zod33.z.record(import_zod33.z.string(), import_zod33.z.unknown()),
+        reason: import_zod33.z.string()
+      })),
+      warnings: import_zod33.z.array(import_zod33.z.string()),
+      limitations: import_zod33.z.array(import_zod33.z.string())
+    };
     ImportServiceConnectionToMemoryInputSchema = {
       connectionId: import_zod33.z.string().min(1).max(200).describe("A tenant-owned connectionId from list_service_connections."),
       providerConfigKey: import_zod33.z.string().min(1).max(200).describe("The exact providerConfigKey returned with that connection. It is matched together with connectionId against the authenticated caller."),
@@ -29569,7 +29935,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")
@@ -29604,7 +29970,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")
@@ -29632,7 +29998,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")
@@ -29810,6 +30176,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.",
@@ -29866,6 +30239,7 @@ var init_paa_mcp_server = __esm({
     init_server_instructions();
     init_output_schema_registry();
     init_report_artifact_offload();
+    init_meta_ad_creative_media();
     init_mcp_tool_schemas();
     init_rank_tracker_blueprint();
     init_mcp_response_formatter();
@@ -40070,7 +40444,7 @@ function cleanString(value, max = 300) {
   const trimmed = value.trim();
   return trimmed ? trimmed.slice(0, max) : null;
 }
-function firstString(record, keys, max = 300) {
+function firstString2(record, keys, max = 300) {
   for (const key of keys) {
     const value = cleanString(record[key], max);
     if (value) return value;
@@ -40134,10 +40508,10 @@ function safeControlErrorPayload(body, responseStatus) {
   const status = controlErrorStatus(responseStatus);
   const unwrapped = unwrapData(body);
   const record = isRecord2(unwrapped) ? unwrapped : isRecord2(body) ? body : null;
-  const candidateCode = record ? firstString(record, ["code", "errorCode", "error_code"], 100) : null;
+  const candidateCode = record ? firstString2(record, ["code", "errorCode", "error_code"], 100) : null;
   const normalizedCandidateCode = candidateCode ? CONTROL_ERROR_CODE_ALIASES.get(candidateCode) ?? candidateCode : null;
   const code = normalizedCandidateCode && SAFE_CONTROL_ERROR_CODES.has(normalizedCandidateCode) ? normalizedCandidateCode : defaultControlErrorCode(status);
-  const candidateMessage = record ? firstString(record, ["error", "message"], 500) : null;
+  const candidateMessage = record ? firstString2(record, ["error", "message"], 500) : null;
   const message = normalizedCandidateCode && SAFE_CONTROL_ERROR_CODES.has(normalizedCandidateCode) && candidateMessage ? candidateMessage.replace(/[\u0000-\u001f\u007f]/g, " ") : defaultControlErrorMessage(status);
   const retryable = record && typeof record.retryable === "boolean" ? record.retryable : status === 429 || status >= 500;
   return { status, code, message, retryable };
@@ -40182,8 +40556,8 @@ function sanitizeScheduleConnectionSelections(value) {
   const seen = /* @__PURE__ */ new Set();
   for (const item of value) {
     if (!isRecord2(item)) throw new ScheduleConnectionValidationError("Each service connection must be an object.");
-    const connectionId = firstString(item, ["connectionId", "connection_id"]);
-    const providerConfigKey = firstString(item, ["providerConfigKey", "provider_config_key", "integrationId", "integration_id"]);
+    const connectionId = firstString2(item, ["connectionId", "connection_id"]);
+    const providerConfigKey = firstString2(item, ["providerConfigKey", "provider_config_key", "integrationId", "integration_id"]);
     const allowedTools = cleanTools(item.allowedTools ?? item.allowed_tools ?? item.allowedCapabilities ?? item.allowed_capabilities);
     if (!connectionId || !providerConfigKey) throw new ScheduleConnectionValidationError("Each service connection needs a connectionId and providerConfigKey.");
     if (allowedTools.length === 0) throw new ScheduleConnectionValidationError("Each selected service needs at least one allowed tool.");
@@ -40200,14 +40574,14 @@ async function getNangoCatalog() {
   const result = [];
   for (const row of rows) {
     if (!isRecord2(row)) continue;
-    const providerConfigKey = firstString(row, ["providerConfigKey", "provider_config_key", "integrationId", "integration_id", "id"]);
+    const providerConfigKey = firstString2(row, ["providerConfigKey", "provider_config_key", "integrationId", "integration_id", "id"]);
     if (!providerConfigKey) continue;
-    const provider = firstString(row, ["provider"]);
-    const label = firstString(row, ["label", "displayName", "display_name", "name"]) || providerConfigKey;
-    const description = firstString(row, ["description"], 500);
+    const provider = firstString2(row, ["provider"]);
+    const label = firstString2(row, ["label", "displayName", "display_name", "name"]) || providerConfigKey;
+    const description = firstString2(row, ["description"], 500);
     const logoUrl = cleanHttpsUrl(row.logoUrl ?? row.logo_url ?? row.logo);
     const docsUrl = cleanHttpsUrl(row.docsUrl ?? row.docs_url ?? row.docs);
-    const authMode = firstString(row, ["authMode", "auth_mode"], 100);
+    const authMode = firstString2(row, ["authMode", "auth_mode"], 100);
     const categories = cleanStringArray(row.categories);
     const disabledTools = DISABLED_NANGO_TOOLS[providerConfigKey];
     const safeDefaultAllowedTools = cleanTools(
@@ -40234,14 +40608,14 @@ async function getNangoCatalog() {
         requiredFeaturesByTool[cleanTool] = cleanStringArray(features, 32, 200);
       }
     }
-    const platformSetupStatus = firstString(row, [
+    const platformSetupStatus = firstString2(row, [
       "platformSetupStatus",
       "platform_setup_status",
       "setupStatus",
       "setup_status"
     ], 100);
-    const appReviewStatus = row.appReviewLimited === true || row.app_review_limited === true ? "limited" : firstString(row, ["appReviewStatus", "app_review_status", "reviewStatus", "review_status"], 100);
-    const appReviewNote = firstString(row, ["appReviewNote", "app_review_note", "reviewNote", "review_note"], 500);
+    const appReviewStatus = row.appReviewLimited === true || row.app_review_limited === true ? "limited" : firstString2(row, ["appReviewStatus", "app_review_status", "reviewStatus", "review_status"], 100);
+    const appReviewNote = firstString2(row, ["appReviewNote", "app_review_note", "reviewNote", "review_note"], 500);
     const connectionSyncRequiredTools = [...CONNECTION_SYNC_REQUIRED_TOOLS[providerConfigKey] ?? []];
     const connectionSyncOptionalTools = [...CONNECTION_SYNC_OPTIONAL_TOOLS[providerConfigKey] ?? []];
     result.push({
@@ -40275,12 +40649,12 @@ async function getNangoConnections(identity) {
   const result = [];
   for (const row of rows) {
     if (!isRecord2(row)) continue;
-    const connectionId = firstString(row, ["connectionId", "connection_id", "id"]);
-    const providerConfigKey = firstString(row, ["providerConfigKey", "provider_config_key", "integrationId", "integration_id", "provider"]);
+    const connectionId = firstString2(row, ["connectionId", "connection_id", "id"]);
+    const providerConfigKey = firstString2(row, ["providerConfigKey", "provider_config_key", "integrationId", "integration_id", "provider"]);
     if (!connectionId || !providerConfigKey) continue;
-    const provider = firstString(row, ["provider"]);
-    const label = firstString(row, ["label", "accountLabel", "account_label", "displayName", "display_name", "endUserEmail", "end_user_email"]) || providerConfigKey;
-    const rawStatus = firstString(row, ["status"], 64) || "connected";
+    const provider = firstString2(row, ["provider"]);
+    const label = firstString2(row, ["label", "accountLabel", "account_label", "displayName", "display_name", "endUserEmail", "end_user_email"]) || providerConfigKey;
+    const rawStatus = firstString2(row, ["status"], 64) || "connected";
     const reconnectRequired = row.reconnectRequired === true || row.reconnect_required === true || rawStatus === "needs_reauth" || rawStatus === "reauth_required" || rawStatus === "invalid" || rawStatus === "error" || rawStatus === "revoked" || rawStatus === "disabled";
     const toolCapabilities = [];
     const rawToolCapabilities = row.toolCapabilities ?? row.tool_capabilities;
@@ -40322,11 +40696,11 @@ async function getNangoConnections(identity) {
       permissionVerification,
       mcpEndpoint: null,
       schemaDiscovery: "compatibility_describe",
-      toolRevision: firstString(row, ["toolRevision", "tool_revision"], 200),
-      vaultName: firstString(row, ["vaultName", "vault_name"], 100),
-      tableName: firstString(row, ["tableName", "table_name"], 100),
-      createdAt: firstString(row, ["createdAt", "created_at"], 100),
-      updatedAt: firstString(row, ["updatedAt", "updated_at"], 100)
+      toolRevision: firstString2(row, ["toolRevision", "tool_revision"], 200),
+      vaultName: firstString2(row, ["vaultName", "vault_name"], 100),
+      tableName: firstString2(row, ["tableName", "table_name"], 100),
+      createdAt: firstString2(row, ["createdAt", "created_at"], 100),
+      updatedAt: firstString2(row, ["updatedAt", "updated_at"], 100)
     });
   }
   return result;
@@ -40334,12 +40708,12 @@ async function getNangoConnections(identity) {
 function sanitizeConnectSession(body) {
   const data = unwrapData(body);
   if (!isRecord2(data)) throw new NangoControlError("The connection service returned an invalid connect session.");
-  const connectLink = firstString(data, ["connectLink", "connect_link"], 2e3);
+  const connectLink = firstString2(data, ["connectLink", "connect_link"], 2e3);
   if (!connectLink) throw new NangoControlError("The connection service did not return a connect link.");
   return {
     connectLink,
-    sessionToken: firstString(data, ["sessionToken", "session_token", "token"], 2e3),
-    expiresAt: firstString(data, ["expiresAt", "expires_at"], 100)
+    sessionToken: firstString2(data, ["sessionToken", "session_token", "token"], 2e3),
+    expiresAt: firstString2(data, ["expiresAt", "expires_at"], 100)
   };
 }
 async function createNangoConnectSession(identity, providerConfigKey) {
@@ -40367,7 +40741,7 @@ function sanitizeBindingRows(body, defaultScheduleActionId) {
     const rows = arrayFromPayload(data, ["bindings", "connections"]);
     for (const row of rows) {
       if (isRecord2(row) && Array.isArray(row.connections)) {
-        const scheduleActionId = firstString(row, ["scheduleActionId", "schedule_action_id", "scheduleId", "schedule_id"]) || defaultScheduleActionId;
+        const scheduleActionId = firstString2(row, ["scheduleActionId", "schedule_action_id", "scheduleId", "schedule_id"]) || defaultScheduleActionId;
         row.connections.forEach((connection) => flattened.push({ row: connection, scheduleActionId }));
       } else {
         flattened.push({ row, scheduleActionId: defaultScheduleActionId });
@@ -40377,15 +40751,15 @@ function sanitizeBindingRows(body, defaultScheduleActionId) {
   const result = [];
   for (const item of flattened) {
     if (!isRecord2(item.row)) continue;
-    const connectionId = firstString(item.row, ["connectionId", "connection_id"]);
-    const providerConfigKey = firstString(item.row, ["providerConfigKey", "provider_config_key", "integrationId", "integration_id", "provider"]);
+    const connectionId = firstString2(item.row, ["connectionId", "connection_id"]);
+    const providerConfigKey = firstString2(item.row, ["providerConfigKey", "provider_config_key", "integrationId", "integration_id", "provider"]);
     if (!connectionId || !providerConfigKey) continue;
     result.push({
-      scheduleActionId: firstString(item.row, ["scheduleActionId", "schedule_action_id", "scheduleId", "schedule_id"]) || item.scheduleActionId,
+      scheduleActionId: firstString2(item.row, ["scheduleActionId", "schedule_action_id", "scheduleId", "schedule_id"]) || item.scheduleActionId,
       connectionId,
       providerConfigKey,
       allowedTools: cleanTools(item.row.allowedTools ?? item.row.allowed_tools ?? item.row.allowedCapabilities ?? item.row.allowed_capabilities),
-      label: firstString(item.row, ["label", "accountLabel", "account_label", "displayName", "display_name"])
+      label: firstString2(item.row, ["label", "accountLabel", "account_label", "displayName", "display_name"])
     });
   }
   return result;
@@ -40767,7 +41141,7 @@ function cleanString2(value, max = 300) {
   const trimmed = value.trim();
   return trimmed ? trimmed.slice(0, max) : null;
 }
-function firstString2(record, keys, max = 300) {
+function firstString3(record, keys, max = 300) {
   for (const key of keys) {
     const value = cleanString2(record[key], max);
     if (value) return value;
@@ -40839,7 +41213,7 @@ async function getResendCatalog() {
   const result = [];
   for (const row of rows) {
     if (!isRecord3(row)) continue;
-    const id = firstString2(row, ["providerConfigKey", "provider_config_key", "id"]);
+    const id = firstString3(row, ["providerConfigKey", "provider_config_key", "id"]);
     if (id !== RESEND_PROVIDER_CONFIG_KEY) continue;
     const safeDefaultAllowedTools = cleanTools2(
       row.safeDefaultAllowedTools ?? row.safe_default_allowed_tools ?? row.readTools ?? row.read_tools
@@ -40849,8 +41223,8 @@ async function getResendCatalog() {
     result.push({
       providerConfigKey: RESEND_PROVIDER_CONFIG_KEY,
       provider: RESEND_PROVIDER_CONFIG_KEY,
-      label: firstString2(row, ["label", "displayName", "display_name", "name"]) || "Resend",
-      description: firstString2(row, ["description"], 500) || "Connect Resend through its official remote MCP to read email operations and run explicitly enabled delivery workflows.",
+      label: firstString3(row, ["label", "displayName", "display_name", "name"]) || "Resend",
+      description: firstString3(row, ["description"], 500) || "Connect Resend through its official remote MCP to read email operations and run explicitly enabled delivery workflows.",
       logoUrl: cleanHttpsUrl2(row.logoUrl ?? row.logo_url ?? row.logo) || RESEND_LOGO_URL,
       docsUrl: cleanHttpsUrl2(row.docsUrl ?? row.docs_url ?? row.docs) || RESEND_DOCS_URL,
       authMode: "REMOTE_MCP_OAUTH2",
@@ -40860,7 +41234,7 @@ async function getResendCatalog() {
       adminBlockedTools: adminBlockedTools.length > 0 ? adminBlockedTools : [...RESEND_ADMIN_BLOCKED_TOOLS],
       connectionSyncSupported: true,
       connectionSyncRequiredTools: [...RESEND_CONNECTION_SYNC_REQUIRED_TOOLS],
-      platformSetupStatus: firstString2(row, ["platformSetupStatus", "platform_setup_status", "setupStatus", "setup_status"], 100) || "ready",
+      platformSetupStatus: firstString3(row, ["platformSetupStatus", "platform_setup_status", "setupStatus", "setup_status"], 100) || "ready",
       appReviewStatus: null,
       appReviewNote: "Secret-returning webhook creation, API-key, OAuth-grant, and raw editor-session access is permanently blocked from agents and schedules.",
       transport: "remote_mcp"
@@ -40875,10 +41249,10 @@ async function getResendConnections(identity) {
   const result = [];
   for (const row of rows) {
     if (!isRecord3(row)) continue;
-    const connectionId = firstString2(row, ["connectionId", "connection_id", "id"]);
-    const providerConfigKey = firstString2(row, ["providerConfigKey", "provider_config_key", "provider"]) || RESEND_PROVIDER_CONFIG_KEY;
+    const connectionId = firstString3(row, ["connectionId", "connection_id", "id"]);
+    const providerConfigKey = firstString3(row, ["providerConfigKey", "provider_config_key", "provider"]) || RESEND_PROVIDER_CONFIG_KEY;
     if (!connectionId || providerConfigKey !== RESEND_PROVIDER_CONFIG_KEY) continue;
-    const rawStatus = (firstString2(row, ["status"], 64) || "needs_reauth").toLowerCase();
+    const rawStatus = (firstString3(row, ["status"], 64) || "needs_reauth").toLowerCase();
     const pending = ["pending", "pending_oauth", "authorizing", "authorization_pending"].includes(rawStatus);
     const active = ["active", "connected", "ready"].includes(rawStatus);
     const reconnectRequired = row.reconnectRequired === true || row.reconnect_required === true || !pending && !active;
@@ -40886,7 +41260,7 @@ async function getResendConnections(identity) {
       connectionId,
       providerConfigKey: RESEND_PROVIDER_CONFIG_KEY,
       provider: RESEND_PROVIDER_CONFIG_KEY,
-      label: firstString2(row, ["label", "accountLabel", "account_label", "displayName", "display_name"]) || "Resend account",
+      label: firstString3(row, ["label", "accountLabel", "account_label", "displayName", "display_name"]) || "Resend account",
       status: pending ? "pending_oauth" : reconnectRequired ? "needs_reauth" : "connected",
       reconnectRequired,
       actionsEnabled: row.actionsEnabled === true || row.actions_enabled === true,
@@ -40895,11 +41269,11 @@ async function getResendConnections(identity) {
       adminBlockedTools: cleanTools2(row.adminBlockedTools ?? row.admin_blocked_tools).length > 0 ? cleanTools2(row.adminBlockedTools ?? row.admin_blocked_tools) : [...RESEND_ADMIN_BLOCKED_TOOLS],
       mcpEndpoint: null,
       schemaDiscovery: "compatibility_describe",
-      toolRevision: firstString2(row, ["toolRevision", "tool_revision"], 200),
-      vaultName: firstString2(row, ["vaultName", "vault_name"], 100),
-      tableName: firstString2(row, ["tableName", "table_name"], 100),
-      createdAt: firstString2(row, ["createdAt", "created_at"], 100),
-      updatedAt: firstString2(row, ["updatedAt", "updated_at"], 100),
+      toolRevision: firstString3(row, ["toolRevision", "tool_revision"], 200),
+      vaultName: firstString3(row, ["vaultName", "vault_name"], 100),
+      tableName: firstString3(row, ["tableName", "table_name"], 100),
+      createdAt: firstString3(row, ["createdAt", "created_at"], 100),
+      updatedAt: firstString3(row, ["updatedAt", "updated_at"], 100),
       transport: "remote_mcp"
     });
   }
@@ -40913,7 +41287,7 @@ function sanitizeConnectSession2(body) {
   return {
     connectLink,
     sessionToken: null,
-    expiresAt: firstString2(data, ["expiresAt", "expires_at"], 100)
+    expiresAt: firstString3(data, ["expiresAt", "expires_at"], 100)
   };
 }
 async function createResendConnectSession(identity, redirectUri) {
@@ -40975,16 +41349,16 @@ async function describeResendTool(identity, connectionId, tool) {
   const data = unwrapData2(body);
   const rawTool = isRecord3(data) && isRecord3(data.tool) ? data.tool : data;
   if (!isRecord3(rawTool)) throw new ResendControlError("Resend returned an invalid tool description.");
-  const name = firstString2(rawTool, ["name"], 200);
-  const classification = firstString2(rawTool, ["classification", "kind"], 20);
+  const name = firstString3(rawTool, ["name"], 200);
+  const classification = firstString3(rawTool, ["classification", "kind"], 20);
   const inputSchema = rawTool.inputSchema ?? rawTool.input_schema;
   if (!name || name !== tool || classification !== "read" && classification !== "action" || !isRecord3(inputSchema)) {
     throw new ResendControlError("Resend returned an invalid tool description.");
   }
   return {
     name,
-    title: firstString2(rawTool, ["title"], 300),
-    description: firstString2(rawTool, ["description"], 2e3),
+    title: firstString3(rawTool, ["title"], 300),
+    description: firstString3(rawTool, ["description"], 2e3),
     inputSchema,
     classification
   };