mcp-scraper 0.18.0 → 0.19.0

package/dist/{worker-JQTS437L.js → worker-AM2DHUWG.js}

@@ -5,12 +5,12 @@ import {
   serializeHarvestProblem
 } from "./chunk-HE2LQPJ2.js";
 import {
-  harvest,
-  runWithCostContext
-} from "./chunk-RMPPYKUV.js";
+  harvest
+} from "./chunk-2HDMYW4B.js";
 import {
-  browserServiceApiKey
-} from "./chunk-HPV4VOQX.js";
+  browserServiceApiKey,
+  runWithCostContext
+} from "./chunk-D7ZT27HY.js";
 import "./chunk-K443GQY5.js";
 import "./chunk-XGIPATLV.js";
 import {
@@ -132,4 +132,4 @@ export {
   startWorker,
   tickOnce
 };
-//# sourceMappingURL=worker-JQTS437L.js.map
+//# sourceMappingURL=worker-AM2DHUWG.js.map

package/docs/mcp-tool-manifest.generated.json

@@ -1,12 +1,12 @@
 {
-  "generatedAt": "2026-07-13T01:12:59.720Z",
+  "generatedAt": "2026-07-13T04:02:37.913Z",
   "generatedFrom": "dist/bin/mcp-stdio-server.js",
   "serverInfo": {
     "name": "mcp-scraper",
-    "version": "0.18.0"
+    "version": "0.19.0"
   },
   "counts": {
-    "unified_stdio": 157
+    "unified_stdio": 158
   },
   "surfaces": {
     "unified_stdio": [
@@ -114,6 +114,7 @@
       "memory-search",
       "memory-suggest",
       "memory-upload",
+      "meta_ad_creative_media",
       "my-mentions",
       "pause-scheduled-action",
       "poll-channel",
@@ -7154,14 +7155,14 @@
     {
       "name": "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 — 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": {
         "type": "object",
         "properties": {
           "videoUrl": {
             "type": "string",
             "format": "uri",
-            "description": "Direct Facebook CDN video URL from facebook_page_intel. Do not pass a public post/reel/share URL — use facebook_video_transcribe for those."
+            "description": "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—use facebook_video_transcribe for those."
           }
         },
         "required": [
@@ -7217,6 +7218,65 @@
               "additionalProperties": false
             }
           },
+          "transcriptSignal": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "enum": [
+                  "speech_detected",
+                  "low_speech_signal",
+                  "empty"
+                ]
+              },
+              "speechDetected": {
+                "type": "boolean"
+              },
+              "confidence": {
+                "type": "string",
+                "enum": [
+                  "medium",
+                  "low"
+                ]
+              },
+              "basis": {
+                "type": "string",
+                "const": "transcript_word_count_and_timing"
+              },
+              "mediaDurationSec": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "wordsPerMinute": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "retryRecommended": {
+                "type": "boolean"
+              },
+              "warnings": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "status",
+              "speechDetected",
+              "confidence",
+              "basis",
+              "mediaDurationSec",
+              "wordsPerMinute",
+              "retryRecommended",
+              "warnings"
+            ],
+            "additionalProperties": false
+          },
           "resolvedInputs": {
             "type": "object",
             "properties": {
@@ -7238,6 +7298,7 @@
           "durationMs",
           "transcriptText",
           "chunks",
+          "transcriptSignal",
           "resolvedInputs"
         ],
         "additionalProperties": false,
@@ -7257,7 +7318,7 @@
     {
       "name": "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—use meta_ad_creative_media with the connected ad account for those. Direct Ad Library videoUrl values go to facebook_ad_transcribe.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -7271,7 +7332,7 @@
           },
           "query": {
             "type": "string",
-            "description": "Advertiser or brand name when pageId/libraryId is not known. One of pageId, libraryId, or query is required."
+            "description": "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": {
             "type": "integer",
@@ -7300,6 +7361,51 @@
               "null"
             ]
           },
+          "inputMode": {
+            "type": "string",
+            "enum": [
+              "pageId",
+              "libraryId",
+              "query"
+            ]
+          },
+          "matchConfidence": {
+            "type": "string",
+            "enum": [
+              "high",
+              "medium",
+              "low"
+            ]
+          },
+          "matchReason": {
+            "type": "string"
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "matchedAdvertisers": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "adCount": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              },
+              "required": [
+                "name",
+                "adCount"
+              ],
+              "additionalProperties": false
+            }
+          },
           "totalAds": {
             "type": "integer",
             "minimum": 0
@@ -7389,6 +7495,11 @@
         },
         "required": [
           "advertiserName",
+          "inputMode",
+          "matchConfidence",
+          "matchReason",
+          "warnings",
+          "matchedAdvertisers",
           "totalAds",
           "activeCount",
           "videoCount",
@@ -7412,14 +7523,14 @@
     {
       "name": "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": {
         "type": "object",
         "properties": {
           "url": {
             "type": "string",
             "format": "uri",
-            "description": "Organic Facebook reel/video/watch/post/share URL from facebook.com, m.facebook.com, or fb.watch."
+            "description": "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": {
             "type": "string",
@@ -7514,6 +7625,65 @@
               ],
               "additionalProperties": false
             }
+          },
+          "transcriptSignal": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "enum": [
+                  "speech_detected",
+                  "low_speech_signal",
+                  "empty"
+                ]
+              },
+              "speechDetected": {
+                "type": "boolean"
+              },
+              "confidence": {
+                "type": "string",
+                "enum": [
+                  "medium",
+                  "low"
+                ]
+              },
+              "basis": {
+                "type": "string",
+                "const": "transcript_word_count_and_timing"
+              },
+              "mediaDurationSec": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "wordsPerMinute": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "retryRecommended": {
+                "type": "boolean"
+              },
+              "warnings": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "status",
+              "speechDetected",
+              "confidence",
+              "basis",
+              "mediaDurationSec",
+              "wordsPerMinute",
+              "retryRecommended",
+              "warnings"
+            ],
+            "additionalProperties": false
           }
         },
         "required": [
@@ -7528,7 +7698,8 @@
           "wordCount",
           "chunkCount",
           "transcriptText",
-          "chunks"
+          "chunks",
+          "transcriptSignal"
         ],
         "additionalProperties": false,
         "$schema": "http://json-schema.org/draft-07/schema#"
@@ -13295,6 +13466,226 @@
         "taskSupport": "forbidden"
       }
     },
+    {
+      "name": "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": {
+        "type": "object",
+        "properties": {
+          "connectionId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Tenant-owned Meta Marketing connectionId from list_service_connections."
+          },
+          "adId": {
+            "type": "string",
+            "pattern": "^\\d{5,30}$",
+            "description": "Meta ad ID from the connected ad account. This is not an Ad Library archive ID."
+          },
+          "imageMode": {
+            "type": "string",
+            "enum": [
+              "inline_preview",
+              "resource_only",
+              "none"
+            ],
+            "default": "inline_preview",
+            "description": "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": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 4,
+            "default": 2,
+            "description": "Maximum creative image/thumbnail previews to attach as MCP image blocks. Default 2; maximum 4."
+          }
+        },
+        "required": [
+          "connectionId",
+          "adId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "adId": {
+            "type": "string"
+          },
+          "adName": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "adAccountId": {
+            "$ref": "#/properties/adName"
+          },
+          "creativeId": {
+            "type": "string"
+          },
+          "creativeName": {
+            "$ref": "#/properties/adName"
+          },
+          "effectiveObjectStoryId": {
+            "$ref": "#/properties/adName"
+          },
+          "sourceFacebookPostId": {
+            "$ref": "#/properties/adName"
+          },
+          "objectStoryId": {
+            "$ref": "#/properties/adName"
+          },
+          "pageId": {
+            "$ref": "#/properties/adName"
+          },
+          "postId": {
+            "$ref": "#/properties/adName"
+          },
+          "publicPostCandidateUrl": {
+            "$ref": "#/properties/adName"
+          },
+          "publicPostStatus": {
+            "type": "string",
+            "const": "unverified"
+          },
+          "mediaType": {
+            "type": "string",
+            "enum": [
+              "image",
+              "video",
+              "carousel",
+              "mixed",
+              "unknown"
+            ]
+          },
+          "images": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": {}
+            }
+          },
+          "videos": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": {}
+            }
+          },
+          "inlineImages": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "sourceUrl": {
+                  "type": "string",
+                  "format": "uri"
+                },
+                "mimeType": {
+                  "type": "string"
+                },
+                "bytes": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "contentIndex": {
+                  "type": "integer",
+                  "minimum": 1
+                }
+              },
+              "required": [
+                "sourceUrl",
+                "mimeType",
+                "bytes",
+                "contentIndex"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "nextActions": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "tool": {
+                  "type": "string",
+                  "enum": [
+                    "facebook_ad_transcribe",
+                    "facebook_video_transcribe",
+                    "video_frame_analysis"
+                  ]
+                },
+                "args": {
+                  "type": "object",
+                  "additionalProperties": {}
+                },
+                "reason": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "tool",
+                "args",
+                "reason"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "limitations": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "ok",
+          "adId",
+          "adName",
+          "adAccountId",
+          "creativeId",
+          "creativeName",
+          "effectiveObjectStoryId",
+          "sourceFacebookPostId",
+          "objectStoryId",
+          "pageId",
+          "postId",
+          "publicPostCandidateUrl",
+          "publicPostStatus",
+          "mediaType",
+          "images",
+          "videos",
+          "inlineImages",
+          "nextActions",
+          "warnings",
+          "limitations"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "title": "View Meta Ad Creative Media",
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
     {
       "name": "my-mentions",
       "title": "My Mentions",

package/docs/specs/meta-ad-creative-media-resolution-spec.md

@@ -0,0 +1,31 @@
+# Canonical Build Spec — Meta Ad Creative Media Resolution
+
+- **Request:** Replace the brittle manual path from a connected Meta ad-account ad to visible creative images, playable/transcribable video, and trustworthy analysis signals. Preserve the generic connected-service tools, but make the correct path directly discoverable and callable from the external MCP and scheduled Mastra agents.
+- **Lane:** MCP Build using Mastra, with a provider-native Nango read primitive and an external MCP composition tool.
+- **Capability:** `meta_ad_creative_media` for media buyers, ad directors, analysts, and agents. Given a tenant-owned Meta connection plus an `adId` or creative reference, return the resolved creative media, render bounded images as MCP image content, and optionally transcribe or start frame analysis for the video.
+- **Inputs:** This report; the MCP Scraper, scheduler, Nango integration, and SDK repositories; current Meta Graph API behavior; current MCP content/result specification; existing `facebook_page_intel`, `facebook_ad_transcribe`, `facebook_video_transcribe`, `video_frame_analysis`, `get-ad`, `get-ad-creative`, `get-ad-image`, and `get-ad-video` implementations.
+- **Missing Context:** None that blocks implementation. Default behavior is read-only resolution with image inclusion. Transcription and frame analysis are explicit opt-ins because they spend credits; ad mutations remain outside this tool.
+- **Evidence Plan:** Inspect current source and live schemas; verify Meta media fields against primary sources; verify MCP image content against the protocol/SDK; test a connected Meta ad when a safe fixture or user-owned ad ID is available; never run a write operation during verification.
+- **Target Runtime:** `mcp-scraper` hosted MCP and npm stdio package; `mcp-scraper-scheduler` on Vercel/Mastra; source-controlled Nango functions deployed to the Meta Marketing integration; generated Node/Python/CLI/cURL SDK contracts.
+- **Agents:** Existing scheduled-action Mastra agent receives the provider-native resolver through its per-run connection toolset. No new supervisor or model route is required; creative interpretation remains with the calling vision-capable model.
+- **Skills:** Existing MCP Scraper and Mastra operating guidance. No new workspace skill is required.
+- **Workflows:** Resolve ad and creative deterministically; collect bounded media descriptors; derive durable organic post/reel candidates; hydrate image/video metadata; attach safe image bytes; optionally call the appropriate transcription route or start the existing asynchronous video-frame analysis workflow.
+- **Tools:**
+  - Provider read: `resolve-ad-creative-media` in the Meta Nango integration.
+  - External MCP composition: `meta_ad_creative_media`.
+  - Existing lower-level tools remain available and cross-reference the new path.
+- **MCP:** `meta_ad_creative_media` returns text plus structured content. Successfully fetched creative images are additional MCP `image` content blocks with MIME type and base64 data. Videos remain URL/metadata plus transcript or asynchronous analysis receipt; raw video is not embedded in context.
+- **Data Shape:** Stable media descriptor with ad/creative IDs, account/page/post IDs, public post URL, media type, image assets, video assets, selected transcription route, transcript signal, warnings, and next actions. Image content indices map descriptors to MCP content blocks.
+- **Signals:** Not required. Video frame analysis continues through its existing asynchronous status tool.
+- **Background Tasks:** Resolution and transcription are foreground bounded calls. Deep video analysis uses the existing asynchronous `video_frame_analysis` run/status path.
+- **Guardrails:** Tenant ownership and live provider policy; read-only provider function; explicit opt-in for credit-spending work; SSRF-safe HTTPS image fetching; Meta/CDN host allowlist; redirect validation; MIME allowlist; per-image and image-count limits; no tokens or signed query strings in logs; untrusted-provider-data labeling; action switch is not required for reads.
+- **Observability:** Existing MCP/API request logging, provider call logs, transcription cost telemetry, frame-analysis run IDs, plus structured warnings and route selection.
+- **Enforcement:** Nango compile/source tests; resolver mapping tests; MCP registration/schema tests; image-fetch safety tests; transcript-signal tests; fuzzy advertiser-match warning tests; scheduler policy/binding tests; generated-manifest and SDK parity; local/remote MCP discovery and safe connected-account smoke test.
+- **Done Contract:**
+  1. A vision-capable MCP client receives actual image content for a connected Meta ad creative without manually fetching a URL.
+  2. A paused ad with `effectiveObjectStoryId` produces a public post candidate and the correct organic transcription route automatically.
+  3. Video-only/dark creatives return the best provider source available or an explicit non-playable limitation, never ambiguous partial success.
+  4. Transcript results include a low-signal assessment and actionable warning.
+  5. Query-based Ad Library results disclose match confidence and mixed-advertiser risk.
+  6. The capability exists in the actual MCP, Mastra scheduled toolsets, Vercel production, npm, MCPB, and generated SDK contracts.
+- **Receipt:** Report shipped tool names, callable surfaces, deployment/package versions, test evidence, live safe-read evidence, image delivery result, transcription routing result, and any Meta/provider limitations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-scraper",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "MCP server for MCP Scraper web intelligence tools",
   "type": "module",
   "main": "./dist/index.cjs",