mcp-scraper 0.18.0 → 0.20.0

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`, return the resolved creative media, render bounded images as MCP image content, and provide exact explicit follow-up calls for video transcription or frame analysis when video media is present.
+- **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 organic post/reel candidates; hydrate image/video metadata; attach safe image bytes; recommend the appropriate explicit transcription route or existing asynchronous video-frame analysis workflow without spending those credits inside the read tool.
+- **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, unverified public-post candidate, media type, image assets, video assets, selected follow-up route, warnings, limitations, and next actions. Image content indices map descriptors to MCP content blocks. Transcript calls separately return their transcript signal.
+- **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.