@revclamp/google-ads-transparency-mcp 1.0.8 → 1.0.10

package/README.md

@@ -122,6 +122,7 @@ npm test
 | **[RevClamp Enterprise](https://revclamp.com/mcp)** | [`revclamp-mcp`](https://www.npmjs.com/package/revclamp-mcp) | Pre-deploy subscription revenue, webhook idempotency & compliance guard (`Stripe`, `Paddle`, `Lemon Squeezy`, `Shopify`) |
 | **[RevClamp AdPulse](https://apify.com/revclamp/google-ads-transparency-mcp)** | [`@revclamp/google-ads-transparency-mcp`](https://www.npmjs.com/package/@revclamp/google-ads-transparency-mcp) | Verified Google Ads advertiser entity disambiguation & active/historical creative intelligence |
 | **[RevClamp TalentPulse](https://apify.com/revclamp/unified-ats-jobs-mcp)** | [`@revclamp/unified-ats-jobs-mcp`](https://www.npmjs.com/package/@revclamp/unified-ats-jobs-mcp) | Unified 5-in-1 B2B ATS job postings, salary ranges & tech-stack hiring signals (`Greenhouse`, `Workday CXS`, `Ashby`, `Lever`, `SmartRecruiters`) |
+| **[RevClamp ContactPulse](https://apify.com/revclamp/b2b-domain-contact-enricher-mcp)** | [`@revclamp/b2b-domain-contact-enricher-mcp`](https://www.npmjs.com/package/@revclamp/b2b-domain-contact-enricher-mcp) | B2B domain role-contact enrichment, RFC 9116 `security.txt` audit & DNS-over-HTTPS MX/SPF/DMARC deliverability posture |
 
 ## Terms of Use, Data Provenance & Independent Tool Disclaimer
 

package/actor_config.json

@@ -21,7 +21,7 @@
   ],
   "manifest": {
     "name": "google-ads-transparency-mcp",
-    "version": "1.0.8",
+    "version": "1.0.10",
     "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/index.mjs

@@ -28,6 +28,7 @@ import {
   COMPOSITE_CURSOR_PREFIX,
   MAX_CURSOR_LENGTH,
   MAX_QUERY_LENGTH,
+  KNOWN_ADVERTISER_DIRECTORY,
   CORPORATE_LEGAL_SUFFIX_TOKENS,
   collapseDottedAcronyms,
   foldBrandText,
@@ -100,6 +101,7 @@ export {
   COMPOSITE_CURSOR_PREFIX,
   MAX_CURSOR_LENGTH,
   MAX_QUERY_LENGTH,
+  KNOWN_ADVERTISER_DIRECTORY,
   CORPORATE_LEGAL_SUFFIX_TOKENS,
   collapseDottedAcronyms,
   foldBrandText,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@revclamp/google-ads-transparency-mcp",
   "mcpName": "com.revclamp/google-ads-transparency-mcp",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "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 with zero browser overhead. Independent tool by RevClamp; not affiliated with Google LLC.",
   "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.8",
+  "version": "1.0.10",
   "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.8",
+      "version": "1.0.10",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/src/mcp_server.mjs

@@ -43,7 +43,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.8',
+  version: '1.0.9',
   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)

package/src/rpc_client.mjs

@@ -56,6 +56,261 @@ export const MAX_QUERY_LENGTH = 512;
 const MIN_VALID_EPOCH_SEC = 946684800; // 2000-01-01T00:00:00Z
 const MAX_VALID_EPOCH_SEC = 4102444800; // 2100-01-01T00:00:00Z
 
+/**
+ * Curated directory of verified Google Ads Transparency legal entities (`AR...`)
+ * for top global brands so common queries resolve in 0 SearchSuggestions RPC calls
+ * and degrade gracefully if upstream SearchSuggestions encounters rate-limiting.
+ */
+export const KNOWN_ADVERTISER_DIRECTORY = Object.freeze(
+  Object.assign(Object.create(null), {
+  nike: Object.freeze({
+    advertiserId: 'AR16735076323512287233',
+    advertiserName: 'Nike, Inc.',
+    regionCode: 'US',
+    minAds: 9000,
+    maxAds: 10000,
+  }),
+  stripe: Object.freeze({
+    advertiserId: 'AR16951989901585285121',
+    advertiserName: 'Stripe, Inc.',
+    regionCode: 'US',
+    minAds: 8000,
+    maxAds: 9000,
+  }),
+  shopify: Object.freeze({
+    advertiserId: 'AR01625195283841286145',
+    advertiserName: 'Shopify Inc.',
+    regionCode: 'CA',
+    minAds: 40000,
+    maxAds: 50000,
+  }),
+  apple: Object.freeze({
+    advertiserId: 'AR03186575737440174081',
+    advertiserName: 'Apple Inc.',
+    regionCode: 'US',
+    minAds: 1000,
+    maxAds: 2000,
+  }),
+  openai: Object.freeze({
+    advertiserId: 'AR02788840342533701633',
+    advertiserName: 'OpenAI OpCo, LLC',
+    regionCode: 'US',
+    minAds: 40000,
+    maxAds: 50000,
+  }),
+  hubspot: Object.freeze({
+    advertiserId: 'AR10072600183532683265',
+    advertiserName: 'Hubspot, Inc.',
+    regionCode: 'US',
+    minAds: 2000,
+    maxAds: 3000,
+  }),
+  google: Object.freeze({
+    advertiserId: 'AR00753945370957971457',
+    advertiserName: 'Google LLC',
+    regionCode: 'US',
+    minAds: 21,
+    maxAds: 21,
+  }),
+  microsoft: Object.freeze({
+    advertiserId: 'AR15495076796520464385',
+    advertiserName: 'Microsoft Corporation',
+    regionCode: 'US',
+    minAds: 60000,
+    maxAds: 70000,
+  }),
+  amazon: Object.freeze({
+    advertiserId: 'AR12815412684405080065',
+    advertiserName: 'Amazon',
+    regionCode: 'US',
+    minAds: 2000,
+    maxAds: 3000,
+  }),
+  meta: Object.freeze({
+    advertiserId: 'AR17753757646030110721',
+    advertiserName: 'Meta',
+    regionCode: 'US',
+    minAds: 500,
+    maxAds: 600,
+  }),
+  netflix: Object.freeze({
+    advertiserId: 'AR11279752625278418945',
+    advertiserName: 'Netflix, Inc.',
+    regionCode: 'US',
+    minAds: 9000,
+    maxAds: 10000,
+  }),
+  airbnb: Object.freeze({
+    advertiserId: 'AR15908226811872411649',
+    advertiserName: 'Airbnb, Inc.',
+    regionCode: 'US',
+    minAds: 1000000,
+    maxAds: 1100000,
+  }),
+  uber: Object.freeze({
+    advertiserId: 'AR10766558596670947329',
+    advertiserName: 'Uber B.V.',
+    regionCode: 'NL',
+    minAds: 20000,
+    maxAds: 30000,
+  }),
+  salesforce: Object.freeze({
+    advertiserId: 'AR14047752120044617729',
+    advertiserName: 'Salesforce, Inc.',
+    regionCode: 'US',
+    minAds: 20000,
+    maxAds: 30000,
+  }),
+  adobe: Object.freeze({
+    advertiserId: 'AR15000638237259595777',
+    advertiserName: 'Adobe, Inc',
+    regionCode: 'US',
+    minAds: 100000,
+    maxAds: 200000,
+  }),
+  cloudflare: Object.freeze({
+    advertiserId: 'AR10379917531786772481',
+    advertiserName: 'Cloudflare, Inc.',
+    regionCode: 'US',
+    minAds: 500,
+    maxAds: 600,
+  }),
+  datadog: Object.freeze({
+    advertiserId: 'AR02089091059349979137',
+    advertiserName: 'DATADOG, INC.',
+    regionCode: 'US',
+    minAds: 9000,
+    maxAds: 10000,
+  }),
+  datadoghq: Object.freeze({
+    advertiserId: 'AR02089091059349979137',
+    advertiserName: 'DATADOG, INC.',
+    regionCode: 'US',
+    minAds: 9000,
+    maxAds: 10000,
+  }),
+  vercel: Object.freeze({
+    advertiserId: 'AR03920035274037395457',
+    advertiserName: 'Vercel Inc.',
+    regionCode: 'US',
+    minAds: 200,
+    maxAds: 300,
+  }),
+  figma: Object.freeze({
+    advertiserId: 'AR15466204033491927041',
+    advertiserName: 'Figma INC',
+    regionCode: 'US',
+    minAds: 1000,
+    maxAds: 2000,
+  }),
+  atlassian: Object.freeze({
+    advertiserId: 'AR16220030717323640833',
+    advertiserName: 'Atlassian US, Inc.',
+    regionCode: 'US',
+    minAds: 20000,
+    maxAds: 30000,
+  }),
+  snowflake: Object.freeze({
+    advertiserId: 'AR00247099845179867137',
+    advertiserName: 'Snowflake Inc.',
+    regionCode: 'US',
+    minAds: 4000,
+    maxAds: 5000,
+  }),
+  twilio: Object.freeze({
+    advertiserId: 'AR18227580619968217089',
+    advertiserName: 'Twilio Inc.',
+    regionCode: 'US',
+    minAds: 1000,
+    maxAds: 2000,
+  }),
+  booking: Object.freeze({
+    advertiserId: 'AR02934798844673654785',
+    advertiserName: 'Booking.com',
+    regionCode: 'NL',
+    minAds: 16500000,
+    maxAds: 16600000,
+  }),
+  oracle: Object.freeze({
+    advertiserId: 'AR08687048956523315201',
+    advertiserName: 'Oracle America, Inc.',
+    regionCode: 'US',
+    minAds: 3000,
+    maxAds: 4000,
+  }),
+  sap: Object.freeze({
+    advertiserId: 'AR14859734842907557889',
+    advertiserName: 'SAP SE',
+    regionCode: 'DE',
+    minAds: 2000,
+    maxAds: 3000,
+  }),
+  cisco: Object.freeze({
+    advertiserId: 'AR13942224429984514049',
+    advertiserName: 'Cisco Systems, Inc.',
+    regionCode: 'US',
+    minAds: 7000,
+    maxAds: 8000,
+  }),
+  nvidia: Object.freeze({
+    advertiserId: 'AR01839840586606051329',
+    advertiserName: 'NVIDIA Corporation',
+    regionCode: 'US',
+    minAds: 600,
+    maxAds: 700,
+  }),
+  canva: Object.freeze({
+    advertiserId: 'AR06374349942554624001',
+    advertiserName: 'Canva, Pty Ltd',
+    regionCode: 'AU',
+    minAds: 30000,
+    maxAds: 40000,
+  }),
+  asana: Object.freeze({
+    advertiserId: 'AR06554691289986629633',
+    advertiserName: 'Asana, Inc.',
+    regionCode: 'US',
+    minAds: 6000,
+    maxAds: 7000,
+  }),
+  zendesk: Object.freeze({
+    advertiserId: 'AR13756467712907804673',
+    advertiserName: 'Zendesk, Inc.',
+    regionCode: 'US',
+    minAds: 3000,
+    maxAds: 4000,
+  }),
+  okta: Object.freeze({
+    advertiserId: 'AR10734849505959608321',
+    advertiserName: 'Okta, Inc',
+    regionCode: 'US',
+    minAds: 1000,
+    maxAds: 2000,
+  }),
+  crowdstrike: Object.freeze({
+    advertiserId: 'AR13642683652595777537',
+    advertiserName: 'CROWDSTRIKE, INC.',
+    regionCode: 'US',
+    minAds: 8000,
+    maxAds: 9000,
+  }),
+  servicenow: Object.freeze({
+    advertiserId: 'AR04119835984416210945',
+    advertiserName: 'ServiceNow, Inc',
+    regionCode: 'US',
+    minAds: 10000,
+    maxAds: 20000,
+  }),
+  workday: Object.freeze({
+    advertiserId: 'AR09563861960156512257',
+    advertiserName: 'Workday, Inc.',
+    regionCode: 'US',
+    minAds: 5000,
+    maxAds: 6000,
+  }),
+  })
+);
+
 /**
  * Canonical Google Ads Geo Target Criterion IDs mapped by ISO 3166-1 alpha-2 country code.
  * Verified against live `LookupService/GetCreativeById` field `17` (`{ "1": 2840, "5": 20261104 }`)
@@ -429,6 +684,13 @@ export const CORPORATE_LEGAL_SUFFIX_TOKENS = new Set([
   'lp',
   'holdings',
   'holding',
+  'opco',
+  'holdco',
+  'topco',
+  'bidco',
+  'midco',
+  'newco',
+  'finco',
   'group',
   'international',
   'global',
@@ -651,10 +913,18 @@ export function parseBrandQueryTokens(rawQuery) {
       : rawBrandTokens;
 
   const brandStem = brandTokens[0] || foldedStemSource.replace(/[^\p{L}\p{N}]/gu, '');
-  const brandStemWithoutHq =
-    isDomainQuery && brandStem.length >= 6 && brandStem.endsWith('hq')
+  const candidateStemWithoutHq =
+    brandStem.length >= 6 && brandStem.endsWith('hq')
       ? brandStem.slice(0, -2)
       : brandStem;
+  const brandStemWithoutHq =
+    candidateStemWithoutHq !== brandStem &&
+    brandTokens.length === 1 &&
+    (isDomainQuery ||
+      Object.hasOwn(KNOWN_ADVERTISER_DIRECTORY, brandStem) ||
+      Object.hasOwn(KNOWN_ADVERTISER_DIRECTORY, candidateStemWithoutHq))
+      ? candidateStemWithoutHq
+      : brandStem;
 
   return {
     rawQuery: trimmed,
@@ -1273,8 +1543,18 @@ export function scoreAdvertiserCandidate(candidate, queryMeta, preferredCountry
       ? Boolean(leadingEntityWords[0] === brandTokens[0] && allBrandTokensPresentAsWords)
       : firstWordMatchesStem;
 
+  const hasHqStemReduction = Boolean(
+    brandTokens.length === 1 &&
+      brandStemWithoutHq &&
+      brandStemWithoutHq !== brandStem &&
+      brandStemWithoutHq.length >= 2
+  );
   let domainConcatPrefixWords = [];
-  if (queryMeta?.isDomainQuery && brandStemWithoutHq && brandStemWithoutHq.length >= 2) {
+  if (
+    (queryMeta?.isDomainQuery || hasHqStemReduction) &&
+    brandStemWithoutHq &&
+    brandStemWithoutHq.length >= 2
+  ) {
     for (const wordList of [leadingEntityWords, nameWords]) {
       let acc = '';
       for (let k = 0; k < Math.min(5, wordList.length); k += 1) {
@@ -1294,12 +1574,11 @@ export function scoreAdvertiserCandidate(candidate, queryMeta, preferredCountry
   }
 
   const domainStemPrefixMatch = Boolean(
-    queryMeta?.isDomainQuery &&
+    (queryMeta?.isDomainQuery || hasHqStemReduction) &&
       brandStemWithoutHq &&
       brandStemWithoutHq.length >= 2 &&
-      ((leadingEntityWords[0] === brandStemWithoutHq &&
-        (brandTokens.length <= 1 || allBrandTokensPresentAsWords)) ||
-        domainConcatPrefixWords.length > 0)
+      (brandTokens.length <= 1 || allBrandTokensPresentAsWords) &&
+      (leadingEntityWords[0] === brandStemWithoutHq || domainConcatPrefixWords.length > 0)
   );
 
   const matchedCoreTokens = exactBrandWordMatch
@@ -1529,10 +1808,15 @@ export async function executeGoogleAdsRpcPost(endpointUrl, fReqPayload, options
           headers: {
             'content-type': 'application/x-www-form-urlencoded;charset=UTF-8',
             accept: 'application/json, text/plain, */*',
+            'accept-language': 'en-US,en;q=0.9',
             origin: 'https://adstransparency.google.com',
             referer: 'https://adstransparency.google.com/',
+            'sec-fetch-dest': 'empty',
+            'sec-fetch-mode': 'cors',
+            'sec-fetch-site': 'same-origin',
+            'x-same-domain': '1',
             'user-agent':
-              'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36',
+              'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36',
           },
           body: encodedBody,
           redirect: 'manual',
@@ -1942,12 +2226,66 @@ export async function resolveAdvertiserEntities(options = {}) {
     };
   }
 
-  // Multi-token domains (e.g. on-running.com) join all tokens ("on running") rather than truncating to first token
+  // Match single-brand or domain stem against KNOWN_ADVERTISER_DIRECTORY when !includeSubsidiaries
+  const directoryKey =
+    queryMeta.brandTokens.length === 1 ? String(queryMeta.brandStem || '').toLowerCase() : '';
+  const fallbackDirectoryKey =
+    queryMeta.brandTokens.length === 1
+      ? String(queryMeta.brandStemWithoutHq || '').toLowerCase()
+      : '';
+  const rawKnownEntry = directoryKey
+    ? (Object.hasOwn(KNOWN_ADVERTISER_DIRECTORY, directoryKey)
+        ? KNOWN_ADVERTISER_DIRECTORY[directoryKey]
+        : null) ||
+      (fallbackDirectoryKey && Object.hasOwn(KNOWN_ADVERTISER_DIRECTORY, fallbackDirectoryKey)
+        ? KNOWN_ADVERTISER_DIRECTORY[fallbackDirectoryKey]
+        : null) ||
+      null
+    : null;
+  const normalizedFilterCountry = rawCountry === 'UK' ? 'GB' : rawCountry;
+  const knownDirectoryEntity =
+    rawKnownEntry &&
+    (!normalizedFilterCountry ||
+      normalizedFilterCountry === 'ALL' ||
+      normalizedFilterCountry === rawKnownEntry.regionCode)
+      ? scoreAdvertiserCandidate(rawKnownEntry, queryMeta, normalizedFilterCountry)
+      : null;
+
+  const singleEntityDirectoryEligible = maxEntities === 1;
+  const shouldUseDirectoryBeforeRpc =
+    Boolean(knownDirectoryEntity) &&
+    singleEntityDirectoryEligible &&
+    options.preferDirectory === true;
+
+  if (shouldUseDirectoryBeforeRpc) {
+    return {
+      ok: true,
+      status: 'OK',
+      resolutionSource: 'KNOWN_ADVERTISER_DIRECTORY',
+      queryMeta,
+      primaryEntity: knownDirectoryEntity,
+      selectedEntities: [knownDirectoryEntity],
+      allCandidates: [knownDirectoryEntity],
+      rpcAttempts: 0,
+      billableCount: 0,
+    };
+  }
+
+  // Multi-token domains (e.g. on-running.com) join all tokens ("on running") rather than truncating to first token;
+  // single-token -hq domains/queries (e.g. datadoghq.com, datadoghq) search by brandStemWithoutHq ("datadog").
+  const effectiveSingleTokenStem =
+    queryMeta.brandStemWithoutHq && queryMeta.brandStemWithoutHq !== queryMeta.brandStem
+      ? queryMeta.brandStemWithoutHq
+      : queryMeta.brandStem;
   const searchQueryStr = queryMeta.isDomainQuery
     ? queryMeta.brandTokens.length > 1
       ? queryMeta.brandTokens.join(' ')
-      : queryMeta.brandStem
-    : queryMeta.rawQuery;
+      : effectiveSingleTokenStem
+    : queryMeta.brandTokens.length === 1 &&
+        queryMeta.brandStemWithoutHq &&
+        queryMeta.brandStemWithoutHq !== queryMeta.brandStem
+      ? queryMeta.brandStemWithoutHq
+      : queryMeta.rawQuery;
 
   const endpointUrl = options.endpointUrl || GOOGLE_ADS_RPC_ENDPOINTS.SearchSuggestions;
   const rpcRes = await executeGoogleAdsRpcPost(
@@ -1957,6 +2295,24 @@ export async function resolveAdvertiserEntities(options = {}) {
   );
 
   if (!rpcRes.ok) {
+    if (
+      rpcRes.status === 'UPSTREAM_RATE_LIMITED' &&
+      knownDirectoryEntity &&
+      singleEntityDirectoryEligible &&
+      options.fallbackToDirectoryOnRateLimit !== false
+    ) {
+      return {
+        ok: true,
+        status: 'OK',
+        resolutionSource: 'KNOWN_ADVERTISER_DIRECTORY_FALLBACK',
+        queryMeta,
+        primaryEntity: knownDirectoryEntity,
+        selectedEntities: [knownDirectoryEntity],
+        allCandidates: [knownDirectoryEntity],
+        rpcAttempts: rpcRes.attempts,
+        billableCount: 0,
+      };
+    }
     return {
       ok: false,
       status: rpcRes.status,
@@ -2760,7 +3116,13 @@ export async function fetchAndExtractStaticAdCopy(previewUrl, options = {}) {
           method: 'GET',
           headers: {
             accept: 'application/javascript, text/javascript, text/plain, */*',
+            'accept-language': 'en-US,en;q=0.9',
             referer: 'https://adstransparency.google.com/',
+            'sec-fetch-dest': 'script',
+            'sec-fetch-mode': 'no-cors',
+            'sec-fetch-site': 'cross-site',
+            'user-agent':
+              'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36',
           },
           redirect: 'manual',
           signal: controller.signal,