mcp-scraper 0.18.0 → 0.20.0

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

@@ -1,12 +1,12 @@
 {
-  "generatedAt": "2026-07-13T01:12:59.720Z",
+  "generatedAt": "2026-07-13T18:33:28.697Z",
   "generatedFrom": "dist/bin/mcp-stdio-server.js",
   "serverInfo": {
     "name": "mcp-scraper",
-    "version": "0.18.0"
+    "version": "0.20.0"
   },
   "counts": {
-    "unified_stdio": 157
+    "unified_stdio": 159
   },
   "surfaces": {
     "unified_stdio": [
@@ -55,6 +55,7 @@
       "call_service_connection_action",
       "capture_serp_page_snapshots",
       "capture_serp_snapshot",
+      "check_site_export",
       "cost-usage",
       "create-channel",
       "create-scheduled-action",
@@ -114,6 +115,7 @@
       "memory-search",
       "memory-suggest",
       "memory-upload",
+      "meta_ad_creative_media",
       "my-mentions",
       "pause-scheduled-action",
       "poll-channel",
@@ -1701,6 +1703,16 @@
             "minimum": 1,
             "maximum": 100,
             "description": "When rotateProxies is on, pages fetched per proxy before rotating. Default 30."
+          },
+          "background": {
+            "type": "boolean",
+            "default": false,
+            "description": "Run the audit as a background job instead of blocking this call, returning a jobId immediately — poll it with check_site_export to get a downloadable zip (full audit report, all page content, plus real image files if downloadImages is set) once ready. Use for large sites where a synchronous call would be slow."
+          },
+          "downloadImages": {
+            "type": "boolean",
+            "default": false,
+            "description": "Download every discovered image as a real file into the export bundle (not just image URLs/stats). OFF by default — must be explicitly set true. Implies background regardless of the background flag, since downloading a whole site's images is too slow to run synchronously. Capped at 20 images/page and 500 images/site."
           }
         },
         "required": [
@@ -1717,23 +1729,27 @@
           },
           "pageCount": {
             "type": "integer",
-            "minimum": 0
+            "minimum": 0,
+            "description": "Absent when background is true — the audit has not finished yet."
           },
           "durationMs": {
             "type": "number",
-            "minimum": 0
+            "minimum": 0,
+            "description": "Absent when background is true — the audit has not finished yet."
           },
           "bulkFolder": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Absent when background is true — the audit has not finished yet."
           },
           "issues": {
             "type": "object",
             "additionalProperties": {
               "type": "number"
-            }
+            },
+            "description": "Absent when background is true — the audit has not finished yet."
           },
           "images": {
             "type": "object",
@@ -1761,7 +1777,8 @@
               "over100kb",
               "legacyFormat"
             ],
-            "additionalProperties": false
+            "additionalProperties": false,
+            "description": "Absent when background is true — the audit has not finished yet."
           },
           "links": {
             "type": "object",
@@ -1794,7 +1811,8 @@
               "brokenInternal",
               "externalDomains"
             ],
-            "additionalProperties": false
+            "additionalProperties": false,
+            "description": "Absent when background is true — the audit has not finished yet."
           },
           "artifact": {
             "type": "object",
@@ -1820,16 +1838,25 @@
               "preview"
             ],
             "additionalProperties": false
+          },
+          "jobId": {
+            "type": "string",
+            "description": "Present when background (or downloadImages) was set — poll with check_site_export."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending"
+            ],
+            "description": "Present when background (or downloadImages) was set."
+          },
+          "statusUrl": {
+            "type": "string",
+            "description": "Present when background (or downloadImages) was set — informational; use check_site_export with jobId, not this URL directly."
           }
         },
         "required": [
-          "url",
-          "pageCount",
-          "durationMs",
-          "bulkFolder",
-          "issues",
-          "images",
-          "links"
+          "url"
         ],
         "additionalProperties": false,
         "$schema": "http://json-schema.org/draft-07/schema#"
@@ -4556,6 +4583,98 @@
         "taskSupport": "forbidden"
       }
     },
+    {
+      "name": "check_site_export",
+      "title": "Check Site Export",
+      "description": "Poll the status of a background extract_site or audit_site job (one started with background or downloadImages set). Returns a downloadable zip URL (all page content, plus real image files if downloadImages was set) once status is complete.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "jobId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The jobId returned by extract_site or audit_site when called with background (or downloadImages) set — poll this until status is \"complete\" (or \"failed\")."
+          }
+        },
+        "required": [
+          "jobId"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": {
+          "jobId": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "running",
+              "complete",
+              "failed"
+            ]
+          },
+          "startUrl": {
+            "type": "string"
+          },
+          "totalUrls": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "doneUrls": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "bundleUrl": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Downloadable zip URL once status is complete; null otherwise."
+          },
+          "bundleBytes": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": 0
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Zip size in bytes once status is complete; null otherwise."
+          },
+          "error": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Present with a message when status is failed."
+          }
+        },
+        "required": [
+          "jobId",
+          "status",
+          "bundleUrl",
+          "bundleBytes"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "title": "Check Site Export",
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
     {
       "name": "cost-usage",
       "title": "Cost & Usage",
@@ -6748,6 +6867,16 @@
               ]
             },
             "description": "Per-page output formats: markdown, links, json, images are captured cheaply from HTML; branding (site-level logo/colors/fonts) requires a browser and adds time. Defaults to markdown+links."
+          },
+          "background": {
+            "type": "boolean",
+            "default": false,
+            "description": "Run the crawl as a background job instead of blocking this call, returning a jobId immediately — poll it with check_site_export to get a downloadable zip (all page content, plus real image files if downloadImages is set) once ready. Use for large sites where a synchronous call would be slow."
+          },
+          "downloadImages": {
+            "type": "boolean",
+            "default": false,
+            "description": "Download every discovered image as a real file into the export bundle (not just image URLs/stats). OFF by default — must be explicitly set true. Implies background regardless of the background flag, since downloading a whole site's images is too slow to run synchronously. Capped at 20 images/page and 500 images/site."
           }
         },
         "required": [
@@ -6764,7 +6893,8 @@
           },
           "pageCount": {
             "type": "integer",
-            "minimum": 0
+            "minimum": 0,
+            "description": "Absent when background is true — the crawl has not finished yet."
           },
           "pages": {
             "type": "array",
@@ -6793,11 +6923,13 @@
                 "schemaTypes"
               ],
               "additionalProperties": false
-            }
+            },
+            "description": "Absent when background is true — the crawl has not finished yet."
           },
           "durationMs": {
             "type": "number",
-            "minimum": 0
+            "minimum": 0,
+            "description": "Absent when background is true — the crawl has not finished yet."
           },
           "truncatedCount": {
             "type": "integer",
@@ -6827,13 +6959,25 @@
               "preview"
             ],
             "additionalProperties": false
+          },
+          "jobId": {
+            "type": "string",
+            "description": "Present when background (or downloadImages) was set — poll with check_site_export."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending"
+            ],
+            "description": "Present when background (or downloadImages) was set."
+          },
+          "statusUrl": {
+            "type": "string",
+            "description": "Present when background (or downloadImages) was set — informational; use check_site_export with jobId, not this URL directly."
           }
         },
         "required": [
-          "url",
-          "pageCount",
-          "pages",
-          "durationMs"
+          "url"
         ],
         "additionalProperties": false,
         "$schema": "http://json-schema.org/draft-07/schema#"
@@ -7154,14 +7298,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 +7361,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 +7441,7 @@
           "durationMs",
           "transcriptText",
           "chunks",
+          "transcriptSignal",
           "resolvedInputs"
         ],
         "additionalProperties": false,
@@ -7257,7 +7461,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 +7475,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 +7504,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 +7638,11 @@
         },
         "required": [
           "advertiserName",
+          "inputMode",
+          "matchConfidence",
+          "matchReason",
+          "warnings",
+          "matchedAdvertisers",
           "totalAds",
           "activeCount",
           "videoCount",
@@ -7412,14 +7666,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 +7768,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 +7841,8 @@
           "wordCount",
           "chunkCount",
           "transcriptText",
-          "chunks"
+          "chunks",
+          "transcriptSignal"
         ],
         "additionalProperties": false,
         "$schema": "http://json-schema.org/draft-07/schema#"
@@ -13295,6 +13609,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",