@revclamp/google-ads-transparency-mcp 1.0.11 → 1.0.12

package/.actor/input_schema.json

@@ -42,13 +42,15 @@
       "title": "Include Creative Region & Legal Details",
       "type": "boolean",
       "description": "When enabled, fetches detailed regional presence and legal entity records for up to 10 returned creatives (default 5).",
-      "default": false
+      "default": true,
+      "prefill": true
     },
     "includeAdCopy": {
       "title": "Include Static Ad Copy (Optional)",
       "type": "boolean",
       "description": "When enabled alongside Include Creative Region & Legal Details, extracts static headline, body text, CTA, and destination domain from allowlisted preview scripts without eval.",
-      "default": false
+      "default": true,
+      "prefill": true
     },
     "maxEntities": {
       "title": "Max Advertiser Entities",
@@ -65,7 +67,7 @@
       "minimum": 1,
       "maximum": 200,
       "default": 40,
-      "prefill": 10
+      "prefill": 5
     },
     "pageToken": {
       "title": "Next-Page Cursor Token (Optional)",

package/README.md

@@ -23,12 +23,38 @@ Find verified Google Ads advertiser entities and extract active or historical ad
 
 ---
 
-## Quick Start (MCP Server for Claude Desktop, Cursor, Windsurf)
+## 1. Apify Store Cloud, Clay / n8n & REST API Quick Start
 
-Run directly via `npx`:
+Run **RevClamp AdPulse** in the cloud on [Apify Store (`revclamp/google-ads-transparency-mcp`)](https://apify.com/revclamp/google-ads-transparency-mcp) with zero local installation, or trigger it directly from **Clay**, **n8n**, **Make**, or any HTTP pipeline via the Apify REST API:
 
 ```bash
-npx @revclamp/google-ads-transparency-mcp --mcp-stdio
+curl -s -X POST \
+  "https://api.apify.com/v2/acts/revclamp~google-ads-transparency-mcp/run-sync-get-dataset-items" \
+  -H "Authorization: Bearer $APIFY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "Stripe",
+    "formatFilter": "ALL",
+    "includeCreativeDetails": true,
+    "includeAdCopy": true,
+    "maxResults": 5
+  }'
+```
+
+### Transparent Pay-per-Event Pricing & Free-Tier Credit Math
+
+- **Event Price:** `$0.0012` per extracted ad creative (`ad-creative-extracted`).
+- **What `$1.00` in Free Apify Credits Gets You:** Approximately **`~830` verified Google Ads creatives** (including advertiser entity disambiguation, `TEXT`/`IMAGE`/`VIDEO` format classification, regional presence, and static ad copy extraction).
+- **Zero-Waste Billing Guarantee:** You pay **`$0.00`** on `EMPTY_RESULT` (`0` matching creatives), `INVALID_INPUT`, or upstream rate limits (`UPSTREAM_RATE_LIMITED`). Charges apply strictly to verified, deduplicated ad creatives delivered to your Dataset.
+
+---
+
+## 2. Local AI Agent & MCP Server Quick Start (Claude Desktop, Cursor, Windsurf)
+
+Run directly via `npx` (supports natural parameter aliases `query`, `domain`, `brand`, `company`, or `url`):
+
+```bash
+npx -y @revclamp/google-ads-transparency-mcp --mcp-stdio
 ```
 
 ### Claude Desktop / Cursor Configuration (`claude_desktop_config.json`)

package/actor_config.json

@@ -21,7 +21,7 @@
   ],
   "manifest": {
     "name": "google-ads-transparency-mcp",
-    "version": "1.0.11",
+    "version": "1.0.12",
     "title": "RevClamp AdPulse - Google Ads Transparency Scraper & MCP",
     "websiteUrl": "https://revclamp.com",
     "description": "Find verified Google Ads advertiser entities and extract active or historical ad creatives (Text, Image, Video), preview links, and run dates without browser or proxy overhead. Independent intelligence tool by RevClamp; not affiliated with or endorsed by Google LLC."

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@revclamp/google-ads-transparency-mcp",
   "mcpName": "com.revclamp/google-ads-transparency-mcp",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "type": "module",
   "description": "RevClamp AdPulse - Google Ads Transparency Scraper & MCP. Find verified advertiser entities and extract active or historical ad creatives (Text, Image, Video), preview links, and run dates. Independent B2B tool by RevClamp.",
   "homepage": "https://revclamp.com",

package/server.json

@@ -3,7 +3,7 @@
   "name": "com.revclamp/google-ads-transparency-mcp",
   "title": "RevClamp AdPulse - Google Ads Transparency Scraper & MCP",
   "description": "Google Ads Transparency Center advertiser & creative intelligence MCP server by RevClamp.",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "websiteUrl": "https://revclamp.com",
   "repository": {
     "url": "https://github.com/lhphong09t2/revclamp-mcp",
@@ -27,7 +27,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@revclamp/google-ads-transparency-mcp",
-      "version": "1.0.11",
+      "version": "1.0.12",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/src/mcp_server.mjs

@@ -12,6 +12,7 @@
  *     for a specific `(advertiserId, creativeId)` pair, including regional presence and legal name.
  */
 
+import fs from 'node:fs';
 import {
   resolveAdvertiserEntities,
   getCreativeDetailsById,
@@ -26,6 +27,10 @@ import {
 } from './rpc_client.mjs';
 import { runGoogleAdsTransparencyActor } from './apify_actor.mjs';
 
+const PKG_VERSION = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+).version;
+
 export const MCP_MAX_ENVELOPE_BYTES = 30000;
 export const MCP_MAX_ITEMS_LIMIT = 25;
 export const MCP_MAX_REQ_ID_BYTES = 256;
@@ -43,7 +48,7 @@ export const ENCODED_BRAND_ICON_DATA_URI = `data:image/svg+xml;utf8,${encodeURIC
 export const MCP_SERVER_INFO = Object.freeze({
   name: 'google-ads-transparency-mcp',
   title: 'RevClamp AdPulse - Google Ads Transparency Scraper & MCP',
-  version: '1.0.9',
+  version: PKG_VERSION,
   description:
     'Find verified Google Ads advertiser entities and extract active or historical ad creatives (Text, Image, Video), preview links, and run dates. Independent intelligence tool by RevClamp; not affiliated with or endorsed by Google LLC.',
   // Forward-compatible MCP Registry & Glama metadata extensions (ignored by older stdio clients)
@@ -90,6 +95,30 @@ export const MCP_TOOLS_MANIFEST = Object.freeze([
           maxLength: 512,
           description: 'Brand name or domain to search (e.g. "nike.com", "Stripe", "Booking.com").',
         },
+        domain: {
+          title: 'Brand Domain (Alias)',
+          type: 'string',
+          maxLength: 512,
+          description: 'Alias for query (advertiser domain, e.g. "nike.com", "stripe.com").',
+        },
+        brand: {
+          title: 'Brand Name (Alias)',
+          type: 'string',
+          maxLength: 512,
+          description: 'Alias for query (brand name, e.g. "Nike", "Stripe").',
+        },
+        company: {
+          title: 'Company Name (Alias)',
+          type: 'string',
+          maxLength: 512,
+          description: 'Alias for query (company name, e.g. "Stripe", "Shopify").',
+        },
+        url: {
+          title: 'Advertiser or Transparency URL (Alias)',
+          type: 'string',
+          maxLength: 512,
+          description: 'Alias for query (website URL or adstransparency.google.com URL).',
+        },
         advertiserId: {
           title: 'Advertiser ID (Optional)',
           type: 'string',
@@ -171,6 +200,30 @@ export const MCP_TOOLS_MANIFEST = Object.freeze([
           maxLength: 512,
           description: 'Brand name or domain to resolve (e.g. "nike.com", "Stripe", "Apple").',
         },
+        domain: {
+          title: 'Brand Domain (Alias)',
+          type: 'string',
+          maxLength: 512,
+          description: 'Alias for query (advertiser domain, e.g. "nike.com", "stripe.com").',
+        },
+        brand: {
+          title: 'Brand Name (Alias)',
+          type: 'string',
+          maxLength: 512,
+          description: 'Alias for query (brand name, e.g. "Nike", "Stripe").',
+        },
+        company: {
+          title: 'Company Name (Alias)',
+          type: 'string',
+          maxLength: 512,
+          description: 'Alias for query (company name, e.g. "Stripe", "Shopify").',
+        },
+        url: {
+          title: 'Advertiser or Transparency URL (Alias)',
+          type: 'string',
+          maxLength: 512,
+          description: 'Alias for query (website URL or adstransparency.google.com URL).',
+        },
         countryCode: {
           title: 'Preferred Country (Optional)',
           type: 'string',
@@ -191,7 +244,6 @@ export const MCP_TOOLS_MANIFEST = Object.freeze([
           description: 'Maximum number of verified regional legal entities to select (1 to 3).',
         },
       },
-      required: ['query'],
       additionalProperties: false,
     },
   },
@@ -650,6 +702,10 @@ function validateJsonRpcRequestId(rawId) {
 
 const SEARCH_ALLOWED_ARG_KEYS = new Set([
   'query',
+  'domain',
+  'brand',
+  'company',
+  'url',
   'advertiserId',
   'countryCode',
   'formatFilter',
@@ -665,6 +721,10 @@ const SEARCH_ALLOWED_ARG_KEYS = new Set([
 
 const RESOLVE_ALLOWED_ARG_KEYS = new Set([
   'query',
+  'domain',
+  'brand',
+  'company',
+  'url',
   'countryCode',
   'includeSubsidiaries',
   'maxEntities',
@@ -683,11 +743,13 @@ export function validateMcpToolArguments(toolName, rawArgs) {
   if (rawArgs !== undefined && (!rawArgs || typeof rawArgs !== 'object' || Array.isArray(rawArgs))) {
     return { ok: false, message: 'Tool arguments must be a JSON object' };
   }
-  const args = rawArgs || {};
+  const canonicalToolName =
+    toolName === 'search_google_ads_creatives' ? 'search_google_ads_transparency' : toolName;
+  const args = { ...(rawArgs || {}) };
   const allowedSet =
-    toolName === 'search_google_ads_transparency'
+    canonicalToolName === 'search_google_ads_transparency'
       ? SEARCH_ALLOWED_ARG_KEYS
-      : toolName === 'resolve_google_ads_advertiser'
+      : canonicalToolName === 'resolve_google_ads_advertiser'
         ? RESOLVE_ALLOWED_ARG_KEYS
         : DETAIL_ALLOWED_ARG_KEYS;
 
@@ -700,6 +762,20 @@ export function validateMcpToolArguments(toolName, rawArgs) {
     }
   }
 
+  for (const aliasKey of ['domain', 'brand', 'company', 'url']) {
+    if (args[aliasKey] !== undefined && typeof args[aliasKey] !== 'string') {
+      return { ok: false, message: `Invalid ${aliasKey}: expected a string` };
+    }
+  }
+  if (args.query === undefined || args.query === null || String(args.query).trim() === '') {
+    const aliasValue = [args.domain, args.brand, args.company, args.url].find(
+      (v) => typeof v === 'string' && v.trim().length > 0
+    );
+    if (aliasValue) {
+      args.query = aliasValue.trim();
+    }
+  }
+
   if (toolName === 'get_google_ads_creative_detail') {
     if (
       typeof args.advertiserId !== 'string' ||
@@ -977,11 +1053,15 @@ export async function handleMcpJsonRpcRequest(request, options = {}) {
 
     const rawToolName = String(request.params.name ?? '');
     const safeReflectedToolName = sliceUtf8Safe(rawToolName, 64);
+    const canonicalToolName =
+      rawToolName === 'search_google_ads_creatives'
+        ? 'search_google_ads_transparency'
+        : rawToolName;
 
     if (
-      rawToolName !== 'search_google_ads_transparency' &&
-      rawToolName !== 'resolve_google_ads_advertiser' &&
-      rawToolName !== 'get_google_ads_creative_detail'
+      canonicalToolName !== 'search_google_ads_transparency' &&
+      canonicalToolName !== 'resolve_google_ads_advertiser' &&
+      canonicalToolName !== 'get_google_ads_creative_detail'
     ) {
       return {
         jsonrpc: '2.0',
@@ -993,7 +1073,7 @@ export async function handleMcpJsonRpcRequest(request, options = {}) {
       };
     }
 
-    const argValidation = validateMcpToolArguments(rawToolName, request.params.arguments);
+    const argValidation = validateMcpToolArguments(canonicalToolName, request.params.arguments);
     if (!argValidation.ok) {
       return {
         jsonrpc: '2.0',

package/src/rpc_client.mjs

@@ -838,6 +838,42 @@ export function parseBrandQueryTokens(rawQuery) {
   let candidateHost = trimmed;
   let isDomainQuery = false;
 
+  if (/^(?:https?:\/\/)?(?:www\.)?adstransparency\.google\.com(?:\/|\?|$)/i.test(candidateHost)) {
+    try {
+      const normalizedUrl = /^https?:\/\//i.test(candidateHost)
+        ? candidateHost
+        : `https://${candidateHost}`;
+      const parsed = new URL(normalizedUrl);
+      const arPathMatch = /\/advertiser\/(AR\d{10,25})\b/i.exec(parsed.pathname);
+      if (arPathMatch) {
+        const extractedArId = arPathMatch[1].toUpperCase();
+        return {
+          rawQuery: trimmed,
+          cleanedQuery: extractedArId,
+          brandStem: extractedArId.toLowerCase(),
+          brandStemWithoutHq: extractedArId.toLowerCase(),
+          brandTokens: [extractedArId.toLowerCase()],
+          isDomainQuery: false,
+          extractedAdvertiserId: extractedArId,
+        };
+      }
+      const paramQuery = (
+        parsed.searchParams.get('domain') ||
+        parsed.searchParams.get('q') ||
+        parsed.searchParams.get('query') ||
+        ''
+      ).trim();
+      if (paramQuery) {
+        return {
+          ...parseBrandQueryTokens(paramQuery),
+          rawQuery: trimmed,
+        };
+      }
+    } catch {
+      // Fall back to standard URL/text tokenization
+    }
+  }
+
   if (/^https?:\/\//i.test(candidateHost)) {
     try {
       const parsed = new URL(candidateHost);
@@ -2054,7 +2090,18 @@ export async function executeGoogleAdsRpcPost(endpointUrl, fReqPayload, options
  * @returns {Promise<{ok: boolean, status: string, queryMeta: object, primaryEntity: object|null, selectedEntities: object[], allCandidates: object[], rpcAttempts: number, billableCount: number, reason?: string}>}
  */
 export async function resolveAdvertiserEntities(options = {}) {
-  const explicitAdvertiserId = String(options.advertiserId ?? '').trim();
+  let explicitAdvertiserId = String(options.advertiserId ?? '').trim();
+  if (!explicitAdvertiserId && typeof options.query === 'string') {
+    const qTrim = options.query.trim();
+    if (ADVERTISER_ID_RE.test(qTrim)) {
+      explicitAdvertiserId = qTrim.toUpperCase();
+    } else if (/adstransparency\.google\.com/i.test(qTrim)) {
+      const arUrlMatch = /\/advertiser\/(AR\d{10,25})\b/i.exec(qTrim);
+      if (arUrlMatch) {
+        explicitAdvertiserId = arUrlMatch[1].toUpperCase();
+      }
+    }
+  }
   const rawCountryNorm = String(options.countryCode ?? '').trim().toUpperCase();
   const rawCountry = rawCountryNorm === 'ALL' ? '' : rawCountryNorm;