@channel47/google-ads-mcp 1.0.6 → 1.0.8

package/README.md

@@ -3,7 +3,9 @@
 [![npm version](https://badge.fury.io/js/@channel47%2Fgoogle-ads-mcp.svg)](https://www.npmjs.com/package/@channel47/google-ads-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-MCP server for Google Ads API access via GAQL (Google Ads Query Language).
+MCP server for Google Ads API access via GAQL (Google Ads Query Language). Built by a practitioner managing 25+ ad accounts daily — not a demo.
+
+Part of [Channel 47](https://channel47.dev), the open-source ecosystem of profession plugins for Claude Code. [Get the newsletter](https://channel47.dev/subscribe) for weekly skill breakdowns from production use.
 
 ## Overview
 
@@ -13,7 +15,7 @@ This is a Model Context Protocol (MCP) server that provides tools for querying a
 
 ### For Claude Code Plugin Users
 
-This package is automatically installed when using the [google-ads-specialist Claude Code plugin](https://marketplace.claude.com/plugins/google-ads-specialist). No manual installation required!
+This package is bundled with the [media-buyer Claude Code plugin](https://channel47.dev). No manual installation required.
 
 ### Standalone Use
 
@@ -105,6 +107,132 @@ Execute write operations using GoogleAdsService.Mutate.
 }
 ```
 
+#### Working with Responsive Search Ads (RSAs)
+
+RSAs have two different resource types with different mutability:
+
+| Resource | Entity | Use Case |
+|----------|--------|----------|
+| `customers/{id}/ads/{ad_id}` | `ad` | Update ad **content** (headlines, descriptions, URLs) |
+| `customers/{id}/adGroupAds/{ad_group_id}~{ad_id}` | `ad_group_ad` | Change ad **status** (pause, enable, remove) |
+
+**Update RSA headlines/descriptions** (use `entity: 'ad'`):
+```javascript
+{
+  "operations": [{
+    "entity": "ad",
+    "operation": "update",
+    "resource": {
+      "resource_name": "customers/1234567890/ads/9876543210",
+      "responsive_search_ad": {
+        "headlines": [
+          {"text": "New Headline 1"},
+          {"text": "New Headline 2"},
+          {"text": "New Headline 3"}
+        ],
+        "descriptions": [
+          {"text": "New Description 1"},
+          {"text": "New Description 2"}
+        ]
+      },
+      "final_urls": ["https://example.com"]
+    }
+  }],
+  "dry_run": false
+}
+```
+
+**Change RSA status** (use `entity: 'ad_group_ad'`):
+```javascript
+{
+  "operations": [{
+    "entity": "ad_group_ad",
+    "operation": "update",
+    "resource": {
+      "resource_name": "customers/1234567890/adGroupAds/111222333~9876543210",
+      "status": "PAUSED"
+    }
+  }],
+  "dry_run": false
+}
+```
+
+#### Creating Image Assets with File Paths
+
+When creating image assets, you can provide a local file path instead of base64 data:
+
+```javascript
+{
+  "operations": [{
+    "entity": "asset",
+    "operation": "create",
+    "resource": {
+      "name": "My Image Asset",
+      "image_file_path": "/path/to/image.png"
+    }
+  }]
+}
+```
+
+The server will automatically read the file and convert it to the required base64 format.
+
+#### Creating Campaigns
+
+Campaign creation requires specific fields since Google Ads API v19.2 (September 2025):
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Campaign name |
+| `advertising_channel_type` | Yes | Campaign type (SEARCH, DISPLAY, etc.) |
+| `campaign_budget` | Yes | Reference to budget resource |
+| `bidding strategy` | Yes | One of: `manual_cpc`, `maximize_conversions`, `target_cpa`, etc. |
+| `contains_eu_political_advertising` | Auto | Auto-defaults to `DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING` |
+
+**Complete campaign creation example:**
+```javascript
+{
+  "operations": [
+    // 1. Create budget first (with temp ID for atomic creation)
+    {
+      "entity": "campaign_budget",
+      "operation": "create",
+      "resource": {
+        "resource_name": "customers/1234567890/campaignBudgets/-1",
+        "name": "My Budget",
+        "amount_micros": 10000000,
+        "delivery_method": "STANDARD"
+      }
+    },
+    // 2. Create campaign referencing the budget
+    {
+      "entity": "campaign",
+      "operation": "create",
+      "resource": {
+        "name": "My Search Campaign",
+        "advertising_channel_type": "SEARCH",
+        "status": "PAUSED",
+        "campaign_budget": "customers/1234567890/campaignBudgets/-1",
+        "manual_cpc": { "enhanced_cpc_enabled": false },
+        "network_settings": {
+          "target_google_search": true,
+          "target_search_network": true
+        }
+      }
+    }
+  ],
+  "dry_run": false
+}
+```
+
+**Supported bidding strategies:**
+- `manual_cpc` - Manual cost-per-click
+- `maximize_conversions` - Maximize conversions
+- `maximize_conversion_value` - Maximize conversion value (with optional `target_roas`)
+- `target_cpa` - Target cost-per-acquisition
+- `target_spend` - Maximize clicks (target spend)
+- `target_impression_share` - Target impression share
+- `bidding_strategy` - Reference to portfolio bidding strategy
+
 ## Resources & Prompts
 
 The server provides:
@@ -113,14 +241,11 @@ The server provides:
 
 ## Usage with Claude Code
 
-This server is designed to work with the [google-ads-specialist plugin](https://marketplace.claude.com/plugins/google-ads-specialist), which provides:
+This server is designed to work with the [media-buyer plugin](https://github.com/channel47/channel47), which provides:
 
-- **9 Skill Files**: Progressive disclosure of GAQL patterns and best practices
-  - Atomic skills for focused tasks (campaign performance, search terms, wasted spend, etc.)
-  - Playbooks for comprehensive workflows (account health audit)
-  - Troubleshooting guides for common errors
-- **PreToolUse Hook**: Validates skill references before query/mutate operations
-- **Comprehensive Documentation**: Setup guides and OAuth configuration help
+- **Skills** for campaign building, creative testing, and account audits
+- **PreToolUse Hook** that validates mutations before execution
+- **Reference docs** with GAQL patterns, ad copy formulas, and performance benchmarks
 
 The plugin ensures Claude consults domain knowledge before executing queries, preventing hallucinated GAQL.
 
@@ -135,8 +260,8 @@ The plugin ensures Claude consults domain knowledge before executing queries, pr
 ### Setup
 
 ```bash
-git clone https://github.com/channel47/google-ads-mcp-server.git
-cd google-ads-mcp-server
+git clone https://github.com/channel47/mcps.git
+cd mcps/google-ads
 npm install
 ```
 
@@ -177,9 +302,10 @@ Contributions welcome! Please:
 
 ## Links
 
+- [Channel 47](https://channel47.dev) — open-source profession plugins for Claude Code
+- [Build Notes Newsletter](https://channel47.dev/subscribe) — weekly skill breakdowns from production use
+- [Media Buyer Plugin](https://github.com/channel47/channel47) — the full paid-search toolkit this MCP powers
 - [NPM Package](https://www.npmjs.com/package/@channel47/google-ads-mcp)
-- [GitHub Repository](https://github.com/channel47/google-ads-mcp-server)
-- [Claude Code Plugin](https://marketplace.claude.com/plugins/google-ads-specialist)
 - [Google Ads API Documentation](https://developers.google.com/google-ads/api/docs/start)
 - [GAQL Reference](https://developers.google.com/google-ads/api/docs/query/overview)
 - [Model Context Protocol](https://modelcontextprotocol.io)
@@ -191,5 +317,5 @@ MIT - See [LICENSE](LICENSE) file for details.
 ## Support
 
 For issues or questions:
-- Plugin-related: [Plugin Repository Issues](https://github.com/ctrlswing/channel47-marketplace/issues)
-- Server-related: [Server Repository Issues](https://github.com/channel47/google-ads-mcp-server/issues)
+- Plugin-related: [Plugin Repository Issues](https://github.com/channel47/channel47/issues)
+- Server-related: [Server Repository Issues](https://github.com/channel47/mcps/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@channel47/google-ads-mcp",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Google Ads MCP Server - Query and mutate Google Ads data using GAQL",
   "main": "server/index.js",
   "bin": {
@@ -31,12 +31,13 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/channel47/google-ads-mcp-server.git"
+    "url": "https://github.com/channel47/mcps.git",
+    "directory": "google-ads"
   },
   "bugs": {
-    "url": "https://github.com/channel47/google-ads-mcp-server/issues"
+    "url": "https://github.com/channel47/mcps/issues"
   },
-  "homepage": "https://github.com/channel47/google-ads-mcp-server#readme",
+  "homepage": "https://github.com/channel47/mcps/tree/main/google-ads#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "google-ads-api": "^21.0.1",

package/server/tools/mutate.js

@@ -51,8 +51,8 @@ export async function mutate(params) {
   try {
     // Execute mutation with validation options
     response = await customer.mutateResources(normalizedOps, {
-      partialFailure: partial_failure,
-      validateOnly: dry_run
+      partial_failure: partial_failure,
+      validate_only: dry_run
     });
   } catch (error) {
     // The Opteo library throws exceptions with error.errors array for partial failures

package/server/utils/operation-transform.js

@@ -11,9 +11,36 @@ import { transformImageAssetResource } from './image-asset.js';
  * See: https://developers.google.com/google-ads/api/docs/mutating/overview
  */
 const ENTITIES_REQUIRING_RESOURCE_NAME_IN_CREATE = new Set([
-  'campaign_budget'  // Used for temp IDs when creating budget + campaign atomically
+  'campaign_budget',  // Used for temp IDs when creating budget + campaign atomically
+  'campaign'          // Used for temp IDs when creating campaign + asset group atomically (PMax)
 ]);
 
+/**
+ * Valid bidding strategy fields for campaigns.
+ * Exactly ONE must be present for campaign creation.
+ * See: https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
+ */
+const CAMPAIGN_BIDDING_STRATEGIES = [
+  'manual_cpc',
+  'manual_cpm',
+  'manual_cpv',
+  'maximize_conversions',
+  'maximize_conversion_value',
+  'target_cpa',
+  'target_roas',
+  'target_spend',
+  'target_impression_share',
+  'percent_cpc',
+  'commission',
+  'bidding_strategy'  // Portfolio bidding strategy reference
+];
+
+/**
+ * Default value for EU political advertising field.
+ * Required for all campaign creation since API v19.2 (September 2025).
+ */
+const DEFAULT_EU_POLITICAL_ADVERTISING = 'DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING';
+
 /**
  * Resource name URL path segments to entity type mapping
  * Based on Google Ads API resource name patterns
@@ -28,8 +55,8 @@ const RESOURCE_PATH_TO_ENTITY = {
   'sharedCriteria': 'shared_criterion',
   'campaignBudgets': 'campaign_budget',
   'biddingStrategies': 'bidding_strategy',
-  'ads': 'ad_group_ad',
-  'adGroupAds': 'ad_group_ad',
+  'ads': 'ad',              // For ad content updates (RSA headlines, descriptions, URLs)
+  'adGroupAds': 'ad_group_ad', // For ad group membership and status changes
   'assets': 'asset',
   'conversionActions': 'conversion_action',
   'customerNegativeCriteria': 'customer_negative_criterion',
@@ -121,6 +148,42 @@ function inferEntityFromCreateResource(resource) {
   return null;
 }
 
+/**
+ * Process campaign resource for CREATE operations.
+ * - Adds required contains_eu_political_advertising field if missing
+ * - Validates bidding strategy is present
+ * @param {Object} resource - Campaign resource object
+ * @param {number} index - Operation index for error messages
+ * @returns {{ resource: Object, warnings: string[] }} - Processed resource and warnings
+ * @throws {Error} - If validation fails
+ */
+function processCampaignCreate(resource, index) {
+  const warnings = [];
+  let processedResource = { ...resource };
+
+  // Add EU political advertising field if missing (required since API v19.2)
+  if (!processedResource.contains_eu_political_advertising) {
+    processedResource.contains_eu_political_advertising = DEFAULT_EU_POLITICAL_ADVERTISING;
+    warnings.push(
+      `Operation ${index}: Auto-added contains_eu_political_advertising='${DEFAULT_EU_POLITICAL_ADVERTISING}' (required since API v19.2)`
+    );
+  }
+
+  // Validate bidding strategy is present
+  const hasBiddingStrategy = CAMPAIGN_BIDDING_STRATEGIES.some(
+    field => processedResource[field] !== undefined
+  );
+
+  if (!hasBiddingStrategy) {
+    throw new Error(
+      `Operation ${index}: Campaign CREATE requires a bidding strategy. ` +
+      `Set one of: ${CAMPAIGN_BIDDING_STRATEGIES.join(', ')}`
+    );
+  }
+
+  return { resource: processedResource, warnings };
+}
+
 /**
  * Check if operation is already in Opteo format
  * @param {Object} operation
@@ -226,10 +289,19 @@ function transformToOpteoFormat(operation, index) {
     }
   }
 
+  // Process campaign CREATE operations (EU political advertising, bidding strategy validation)
+  let campaignWarnings = [];
+  if (opType === 'create' && entity === 'campaign') {
+    const campaignResult = processCampaignCreate(resource, index);
+    resource = campaignResult.resource;
+    campaignWarnings = campaignResult.warnings;
+  }
+
   return {
     entity,
     operation: opType,
-    resource
+    resource,
+    _campaignWarnings: campaignWarnings  // Pass warnings up for logging
   };
 }
 
@@ -248,6 +320,7 @@ export function normalizeOperations(operations) {
 
     if (isOpteoFormat(op)) {
       // Already in Opteo format - pass through, but normalize special cases
+      let normalizedOp = { ...op };
 
       // Handle image_file_path in Opteo format asset operations
       if (op.entity === 'asset' && op.operation === 'create' && op.resource?.image_file_path) {
@@ -256,28 +329,33 @@ export function normalizeOperations(operations) {
           throw new Error(`Operation ${i}: ${imageResult.error}`);
         }
         if (imageResult.processed) {
-          normalizedOps.push({
-            ...op,
-            resource: imageResult.resource
-          });
-          continue;
+          normalizedOp.resource = imageResult.resource;
         }
       }
 
+      // Handle campaign CREATE operations (EU political advertising, bidding strategy)
+      if (op.entity === 'campaign' && op.operation === 'create' && op.resource) {
+        const campaignResult = processCampaignCreate(op.resource, i);
+        normalizedOp.resource = campaignResult.resource;
+        warnings.push(...campaignResult.warnings);
+      }
+
       // For remove ops, ensure resource is the string, not an object
       if (op.operation === 'remove' && op.resource && typeof op.resource === 'object') {
-        normalizedOps.push({
-          ...op,
-          resource: op.resource.resource_name || op.resource
-        });
-      } else {
-        normalizedOps.push(op);
+        normalizedOp.resource = op.resource.resource_name || op.resource;
       }
+
+      normalizedOps.push(normalizedOp);
     } else {
       // Transform from standard format
       const transformed = transformToOpteoFormat(op, i);
-      normalizedOps.push(transformed);
-      warnings.push(`Operation ${i}: Transformed from standard format (entity: ${transformed.entity})`);
+      // Collect campaign warnings and strip internal property
+      if (transformed._campaignWarnings?.length > 0) {
+        warnings.push(...transformed._campaignWarnings);
+      }
+      const { _campaignWarnings, ...cleanTransformed } = transformed;
+      normalizedOps.push(cleanTransformed);
+      warnings.push(`Operation ${i}: Transformed from standard format (entity: ${cleanTransformed.entity})`);
     }
   }