mcpscraper-cli 0.7.0 → 0.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 Command-line interface for [mcpscraper.dev](https://mcpscraper.dev) and [memory.mcpscraper.dev](https://memory.mcpscraper.dev).
 
-The CLI provides friendly shortcuts for common operations plus universal discovery and invocation for every one of the 157 unified MCP tools (72 MCP Scraper plus 85 mirrored memory tools).
+The CLI provides friendly shortcuts for common operations plus universal discovery and invocation for every one of the 158 unified MCP tools (73 MCP Scraper plus 85 mirrored memory tools).
 
 ## Install
 
@@ -32,7 +32,9 @@ mcpscraper tools call describe_service_connection_tool --args '{"connectionId":"
 mcpscraper tools call renew_connected_data_download --args '{"artifactId":"artifact_123"}' --json
 ```
 
-`tools list` contains exactly 157 manifest-backed names. `tools call` accepts any one of them. Tools marked destructive require `--yes`.
+`tools list` contains exactly 158 manifest-backed names. `tools call` accepts any one of them. Tools marked destructive require `--yes`.
+
+When a tool returns inline MCP media, the CLI writes each block to a private local file and prints its path instead of dumping base64. Use `--media-dir <path>` to choose the destination; the default is `~/Downloads/mcp-scraper`.
 
 ### `mcpscraper search <query>`
 

package/dist/bin/cli.js

@@ -3,11 +3,13 @@
 // src/cli.ts
 import { Command } from "commander";
 import { fileURLToPath } from "url";
-import { realpathSync } from "fs";
+import { mkdirSync, realpathSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 import { ScraperClient, ScraperApiError } from "mcpscraper-sdk";
 
 // src/version.ts
-var CLI_VERSION = "0.7.0";
+var CLI_VERSION = "0.8.0";
 
 // src/generated-tools.ts
 var MCP_TOOL_CATALOG = [
@@ -510,7 +512,7 @@ var MCP_TOOL_CATALOG = [
     "name": "facebook_page_intel",
     "category": "facebook",
     "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": {
       "type": "object",
       "properties": {
@@ -524,7 +526,7 @@ var MCP_TOOL_CATALOG = [
         },
         "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",
@@ -714,14 +716,14 @@ var MCP_TOOL_CATALOG = [
     "name": "facebook_ad_transcribe",
     "category": "facebook",
     "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": {
       "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 \u2014 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\u2014use facebook_video_transcribe for those."
         }
       },
       "required": [
@@ -854,14 +856,14 @@ var MCP_TOOL_CATALOG = [
     "name": "facebook_video_transcribe",
     "category": "facebook",
     "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",
@@ -7027,6 +7029,57 @@ var MCP_TOOL_CATALOG = [
       "idempotentHint": true,
       "openWorldHint": true
     }
+  },
+  {
+    "name": "meta_ad_creative_media",
+    "category": "connections",
+    "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#"
+    },
+    "annotations": {
+      "title": "View Meta Ad Creative Media",
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": true
+    }
   }
 ];
 var MCP_TOOL_NAMES = MCP_TOOL_CATALOG.map((tool) => tool.name);
@@ -7052,6 +7105,106 @@ function parseToolArgs(value) {
   }
   return parsed;
 }
+function mediaExtension(mimeType) {
+  switch (mimeType?.toLowerCase()) {
+    case "image/png":
+      return "png";
+    case "image/jpeg":
+      return "jpg";
+    case "image/gif":
+      return "gif";
+    case "image/webp":
+      return "webp";
+    case "image/avif":
+      return "avif";
+    case "audio/mpeg":
+      return "mp3";
+    case "audio/mp4":
+      return "m4a";
+    case "audio/wav":
+    case "audio/x-wav":
+      return "wav";
+    case "audio/ogg":
+      return "ogg";
+    case "audio/flac":
+      return "flac";
+    case "audio/aac":
+      return "aac";
+    case "application/pdf":
+      return "pdf";
+    default:
+      return "bin";
+  }
+}
+function safeToolName(name) {
+  return name.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "tool";
+}
+function decodeBase64(data) {
+  const normalized = data.replace(/\s+/g, "");
+  if (normalized.length === 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)) {
+    throw new Error("Refusing to save malformed base64 content from an MCP tool result");
+  }
+  const unpadded = normalized.replace(/=+$/, "");
+  const remainder = unpadded.length % 4;
+  const expectedPadding = remainder === 0 ? 0 : 4 - remainder;
+  const providedPadding = normalized.length - unpadded.length;
+  if (remainder === 1 || providedPadding > 0 && providedPadding !== expectedPadding) {
+    throw new Error("Refusing to save malformed base64 content from an MCP tool result");
+  }
+  return Buffer.from(unpadded.padEnd(unpadded.length + expectedPadding, "="), "base64");
+}
+function saveToolMedia(name, result, mediaDir) {
+  const outputDirectory = mediaDir ?? process.env.MCP_SCRAPER_OUTPUT_DIR ?? join(homedir(), "Downloads", "mcp-scraper");
+  let mediaNumber = 0;
+  const saveBinary = (data, mimeType, kind) => {
+    const bytes = decodeBase64(data);
+    if (bytes.byteLength > 10 * 1024 * 1024) {
+      throw new Error(`Refusing to save inline MCP ${kind} larger than 10 MiB (${bytes.byteLength} bytes)`);
+    }
+    mkdirSync(outputDirectory, { recursive: true });
+    mediaNumber += 1;
+    const filename = `${safeToolName(name)}-${Date.now()}-${mediaNumber}.${mediaExtension(mimeType)}`;
+    const savedPath = join(outputDirectory, filename);
+    writeFileSync(savedPath, bytes, { mode: 384 });
+    return { bytes: bytes.byteLength, savedPath };
+  };
+  const content = (result.content ?? []).map((block) => {
+    if ((block.type === "image" || block.type === "audio") && typeof block.data === "string") {
+      return {
+        ...block,
+        data: void 0,
+        ...saveBinary(block.data, block.mimeType, block.type)
+      };
+    }
+    if (block.type === "resource" && block.resource && typeof block.resource === "object") {
+      const resource = block.resource;
+      if (typeof resource.blob === "string") {
+        return {
+          ...block,
+          resource: {
+            ...resource,
+            blob: void 0,
+            ...saveBinary(resource.blob, typeof resource.mimeType === "string" ? resource.mimeType : void 0, "resource")
+          }
+        };
+      }
+    }
+    return block;
+  });
+  return { ...result, content };
+}
+function printableToolResult(result) {
+  const hasNonTextContent = result.content?.some((block) => block.type !== "text") ?? false;
+  if (hasNonTextContent) return result;
+  if (result.structuredContent !== void 0) return result.structuredContent;
+  const text = result.content?.find((block) => block.type === "text")?.text;
+  if (typeof text !== "string") return result;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
 async function run(fn) {
   try {
     await fn();
@@ -7079,7 +7232,7 @@ function createProgram(fetchImpl = globalThis.fetch) {
   }
   const program = new Command();
   program.name("mcpscraper").description(`CLI for all ${MCP_TOOL_COUNT} mcpscraper.dev MCP tools plus ergonomic shortcuts`).version(CLI_VERSION).option("--api-key <key>", "mcpscraper.dev API key (or set MCPSCRAPER_API_KEY)");
-  program.command("search <query>").description("Run a Google SERP search").option("--location <location>", "geographic location to search from").option("--json", "print raw JSON").action(async (query, opts, cmd) => {
+  program.command("search <query>").description("Run a Google SERP search").option("--location <location>", "geographic location to search from").option("--json", "print the complete JSON result (inline binary data is saved and replaced with file metadata)").action(async (query, opts, cmd) => {
     await run(async () => {
       const result = await client(cmd).searchSerp({
         query,
@@ -7175,7 +7328,7 @@ Vault deposit: ${page.memory.deposited ? `saved to ${page.memory.vault}` : "fail
       });
     });
   });
-  const memory = program.command("memory").description("Ergonomic memory shortcuts; use tools list/call for the complete 157-tool surface");
+  const memory = program.command("memory").description(`Ergonomic memory shortcuts; use tools list/call for the complete ${MCP_TOOL_COUNT}-tool surface`);
   memory.command("search <query>").description("Semantic search across your mcp-memory vaults").option("--json", "print raw JSON").action(async (query, opts, cmd) => {
     await run(async () => {
       const result = await client(cmd).memoryTools.memory.search({ query });
@@ -7198,7 +7351,7 @@ Vault deposit: ${page.memory.deposited ? `saved to ${page.memory.vault}` : "fail
     });
   });
   const tools = program.command("tools").description(`Discover, inspect, and call every unified MCP tool (${MCP_TOOL_COUNT} total)`);
-  tools.command("list").description("List the complete local 157-tool catalog").option("--category <name>", "filter by SDK category").option("--json", "print the complete catalog as JSON").action((opts) => {
+  tools.command("list").description(`List the complete local ${MCP_TOOL_COUNT}-tool catalog`).option("--category <name>", "filter by SDK category").option("--json", "print the complete catalog as JSON").action((opts) => {
     const catalog = opts.category ? MCP_TOOL_CATALOG.filter((tool) => tool.category === opts.category) : MCP_TOOL_CATALOG;
     if (opts.json) {
       console.log(JSON.stringify(catalog, null, 2));
@@ -7213,7 +7366,7 @@ ${catalog.length}/${MCP_TOOL_COUNT} tools`);
     if (!tool) throw new Error(`Unknown tool "${name}". Run "mcpscraper tools list" for all ${MCP_TOOL_COUNT} names.`);
     console.log(JSON.stringify(tool, null, 2));
   });
-  tools.command("call <name>").description("Call any of the 157 MCP tools by exact wire name").option("--args <json>", "tool arguments as a JSON object", "{}").option("--yes", "confirm a tool marked destructive").option("--json", "print raw JSON").action(async (name, opts, cmd) => {
+  tools.command("call <name>").description(`Call any of the ${MCP_TOOL_COUNT} MCP tools by exact wire name`).option("--args <json>", "tool arguments as a JSON object", "{}").option("--yes", "confirm a tool marked destructive").option("--media-dir <path>", "directory for inline MCP images (defaults to ~/Downloads/mcp-scraper)").option("--json", "print raw JSON").action(async (name, opts, cmd) => {
     await run(async () => {
       const tool = MCP_TOOL_CATALOG.find((entry) => entry.name === name);
       if (!tool) throw new Error(`Unknown tool "${name}". Run "mcpscraper tools list" for all ${MCP_TOOL_COUNT} names.`);
@@ -7221,7 +7374,8 @@ ${catalog.length}/${MCP_TOOL_COUNT} tools`);
       if (annotations.destructiveHint && !opts.yes) {
         throw new Error(`Tool "${name}" is marked destructive. Re-run with --yes to confirm.`);
       }
-      const result = await client(cmd).tools.callTool(name, parseToolArgs(opts.args));
+      const rawResult = await client(cmd).tools.callToolResult(name, parseToolArgs(opts.args));
+      const result = printableToolResult(saveToolMedia(name, rawResult, opts.mediaDir));
       if (opts.json || typeof result !== "string") console.log(JSON.stringify(result, null, 2));
       else console.log(result);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpscraper-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Command-line interface for mcpscraper.dev and memory.mcpscraper.dev",
   "license": "MIT",
   "type": "module",
@@ -17,8 +17,8 @@
     "test": "tsx --test test/*.test.ts"
   },
   "dependencies": {
-    "mcpscraper-sdk": "^0.10.0",
-    "commander": "^12.0.0"
+    "commander": "^12.0.0",
+    "mcpscraper-sdk": "^0.11.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"