@channel47/google-ads-mcp 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@channel47/google-ads-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Google Ads MCP Server - Query and mutate Google Ads data using GAQL",
   "main": "server/index.js",
   "bin": {

package/server/index.js

@@ -91,7 +91,19 @@ const TOOLS = [
   },
   {
     name: 'mutate',
-    description: 'Execute write operations using GoogleAdsService.Mutate. Supports all operation types. Default dry_run=true for safety.',
+    description: `Execute write operations using GoogleAdsService.Mutate. Default dry_run=true for safety.
+
+Supports two operation formats:
+
+1. Standard Google Ads format (auto-transformed):
+   { "update": { "resource_name": "customers/123/campaigns/456", "status": "PAUSED" } }
+   { "create": { "ad_group": "customers/123/adGroups/456", "keyword": {...} } }
+   { "remove": "customers/123/labels/789" }
+
+2. Opteo library format:
+   { "entity": "campaign", "operation": "update", "resource": { "resource_name": "...", "status": "PAUSED" } }
+
+Entity types are auto-inferred from resource_name patterns for updates/removes.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -101,7 +113,7 @@ const TOOLS = [
         },
         operations: {
           type: 'array',
-          description: 'Array of mutation operation objects',
+          description: 'Array of mutation operations. Supports standard format ({ create/update/remove: ... }) or Opteo format ({ entity, operation, resource }).',
           items: {
             type: 'object'
           }

package/server/tools/mutate.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { getCustomerClient } from '../auth.js';
+import { formatSuccess, formatError } from '../utils/response-format.js';
+import { normalizeOperations } from '../utils/operation-transform.js';
 
 /**
  * Execute mutation operations using GoogleAdsService.Mutate
@@ -22,43 +24,118 @@ export async function mutate(params) {
 
   // Validate required parameters
   if (!customer_id) {
-    return {
-      success: false,
-      error: 'customer_id is required (either as parameter or GOOGLE_ADS_CUSTOMER_ID env var)'
-    };
+    return formatError(new Error('customer_id is required (either as parameter or GOOGLE_ADS_CUSTOMER_ID env var)'));
   }
 
   if (!operations || !Array.isArray(operations) || operations.length === 0) {
-    return {
-      success: false,
-      error: 'operations array is required and must contain at least one operation'
-    };
+    return formatError(new Error('operations array is required and must contain at least one operation'));
   }
 
+  const customer = getCustomerClient(customer_id);
+  let response;
+  let partialFailureErrors = [];
+
+  // Transform operations to Opteo library format if needed
+  let normalizedOps;
   try {
-    const customer = getCustomerClient(customer_id);
+    const result = normalizeOperations(operations);
+    normalizedOps = result.operations;
+    // Log transformation warnings for debugging
+    if (result.warnings.length > 0) {
+      console.error('Operation format transformations:', result.warnings);
+    }
+  } catch (transformError) {
+    return formatError(transformError);
+  }
 
+  try {
     // Execute mutation with validation options
-    const response = await customer.mutateResources(operations, {
+    response = await customer.mutateResources(normalizedOps, {
       partialFailure: partial_failure,
       validateOnly: dry_run
     });
-
-    return {
-      success: true,
-      dry_run,
-      results: response,
-      message: dry_run
-        ? 'Validation successful - no changes made'
-        : 'Mutations applied successfully',
-      operations_count: operations.length
-    };
   } catch (error) {
+    // The Opteo library throws exceptions with error.errors array for partial failures
+    // Extract failure details if available
+    if (partial_failure && error.errors && Array.isArray(error.errors)) {
+      for (const err of error.errors) {
+        const opIndex = err.location?.field_path_elements?.[0]?.index ?? -1;
+        partialFailureErrors.push({
+          message: err.message || JSON.stringify(err.error_code),
+          error_code: err.error_code,
+          operation_index: opIndex
+        });
+      }
+
+      // If not all operations failed, treat as partial success
+      if (partialFailureErrors.length < operations.length) {
+        response = { mutate_operation_responses: [], partial_failure_error: null };
+      } else {
+        // All operations failed
+        const errorMessages = partialFailureErrors.map(e => e.message).join('; ');
+        return formatError(new Error(`All operations failed: ${errorMessages}`));
+      }
+    } else {
+      // Not a partial failure - re-throw as regular error
+      return formatError(error);
+    }
+  }
+
+  // Extract results from response
+  const results = response.mutate_operation_responses || [];
+
+  // Check for partial failure errors in response body (alternative structure)
+  if (response.partial_failure_error) {
+    const errorDetails = response.partial_failure_error.errors
+      || response.partial_failure_error.details
+      || [];
+
+    for (const error of errorDetails) {
+      partialFailureErrors.push({
+        message: error.message || error.error_message || JSON.stringify(error),
+        error_code: error.error_code || error.code,
+        operation_index: error.location?.field_path_elements?.[0]?.index ?? -1
+      });
+    }
+  }
+
+  // Calculate success/failure counts
+  const failCount = partialFailureErrors.length;
+  const successCount = operations.length - failCount;
+
+  // Extract resource names from nested result structure
+  // Results come as: { campaign_result: { resource_name: "..." }, response: "campaign_result" }
+  const extractedResults = results.map(r => {
+    // Find the result field (campaign_result, ad_group_result, etc.)
+    const resultKey = r?.response;
+    const resultData = resultKey ? r[resultKey] : r;
     return {
-      success: false,
-      dry_run,
-      error: error.message,
-      error_details: error.errors || null
+      resource_name: resultData?.resource_name || null
     };
+  });
+
+  // Build appropriate message
+  let message;
+  if (dry_run) {
+    message = failCount > 0
+      ? `Validation completed with ${failCount} error(s) - no changes made`
+      : 'Validation successful - no changes made';
+  } else {
+    message = failCount > 0
+      ? `Mutations completed: ${successCount} succeeded, ${failCount} failed`
+      : 'Mutations applied successfully';
   }
+
+  return formatSuccess({
+    summary: `${message} (${operations.length} operation${operations.length !== 1 ? 's' : ''})`,
+    data: extractedResults,
+    metadata: {
+      dry_run,
+      operations_count: operations.length,
+      success_count: successCount,
+      failure_count: failCount,
+      customer_id,
+      ...(partialFailureErrors.length > 0 && { errors: partialFailureErrors })
+    }
+  });
 }

package/server/utils/operation-transform.js

@@ -0,0 +1,237 @@
+/**
+ * Operation format transformation utility
+ * Converts standard Google Ads API format to Opteo library format
+ */
+
+/**
+ * Resource name URL path segments to entity type mapping
+ * Based on Google Ads API resource name patterns
+ */
+const RESOURCE_PATH_TO_ENTITY = {
+  'campaigns': 'campaign',
+  'adGroups': 'ad_group',
+  'adGroupCriteria': 'ad_group_criterion',
+  'campaignCriteria': 'campaign_criterion',
+  'labels': 'label',
+  'sharedSets': 'shared_set',
+  'sharedCriteria': 'shared_criterion',
+  'campaignBudgets': 'campaign_budget',
+  'biddingStrategies': 'bidding_strategy',
+  'ads': 'ad_group_ad',
+  'adGroupAds': 'ad_group_ad',
+  'assets': 'asset',
+  'conversionActions': 'conversion_action',
+  'customerNegativeCriteria': 'customer_negative_criterion',
+  'campaignLabels': 'campaign_label',
+  'adGroupLabels': 'ad_group_label',
+  'customerLabels': 'customer_label',
+  'keywordPlanCampaigns': 'keyword_plan_campaign',
+  'keywordPlanAdGroups': 'keyword_plan_ad_group',
+  'keywordPlanAdGroupKeywords': 'keyword_plan_ad_group_keyword',
+  'extensionFeedItems': 'extension_feed_item',
+  'campaignExtensionSettings': 'campaign_extension_setting',
+  'adGroupExtensionSettings': 'ad_group_extension_setting',
+  'remarketingActions': 'remarketing_action',
+  'userLists': 'user_list',
+};
+
+/**
+ * Extract entity type from resource_name URL pattern
+ * @param {string} resourceName - e.g., "customers/123/campaigns/456"
+ * @returns {string|null} - e.g., "campaign" or null if not found
+ */
+function inferEntityFromResourceName(resourceName) {
+  if (!resourceName || typeof resourceName !== 'string') return null;
+
+  // Parse: customers/{customer_id}/{resource_type}/{resource_id}
+  const parts = resourceName.split('/');
+  if (parts.length >= 3 && parts[0] === 'customers') {
+    const resourceType = parts[2]; // e.g., "campaigns", "adGroups"
+    return RESOURCE_PATH_TO_ENTITY[resourceType] || null;
+  }
+  return null;
+}
+
+/**
+ * Infer entity type from create operation structure
+ * @param {Object} resource - The resource being created
+ * @returns {string|null} - Entity type or null
+ */
+function inferEntityFromCreateResource(resource) {
+  if (!resource || typeof resource !== 'object') return null;
+
+  const keys = Object.keys(resource);
+
+  // ad_group_criterion: has ad_group key and keyword/placement/negative
+  if (keys.includes('ad_group') && (keys.includes('keyword') || keys.includes('negative') || keys.includes('placement'))) {
+    return 'ad_group_criterion';
+  }
+
+  // campaign_criterion: has campaign key and keyword/negative (but not just campaign reference)
+  if (keys.includes('campaign') && (keys.includes('keyword') || keys.includes('negative')) && !keys.includes('advertising_channel_type')) {
+    return 'campaign_criterion';
+  }
+
+  // shared_criterion: has shared_set key
+  if (keys.includes('shared_set')) {
+    return 'shared_criterion';
+  }
+
+  // label: has name and text_label
+  if (keys.includes('name') && keys.includes('text_label')) {
+    return 'label';
+  }
+
+  // ad_group: has campaign key and name but no keyword (and isn't a criterion)
+  if (keys.includes('campaign') && keys.includes('name') && !keys.includes('keyword') && !keys.includes('negative')) {
+    return 'ad_group';
+  }
+
+  // campaign: has advertising_channel_type
+  if (keys.includes('advertising_channel_type')) {
+    return 'campaign';
+  }
+
+  // campaign_budget: has amount_micros
+  if (keys.includes('amount_micros') && !keys.includes('cpc_bid_micros')) {
+    return 'campaign_budget';
+  }
+
+  // asset: has type field (image_asset, text_asset, etc.)
+  if (keys.some(k => k.endsWith('_asset'))) {
+    return 'asset';
+  }
+
+  // conversion_action: has type and category
+  if (keys.includes('type') && keys.includes('category')) {
+    return 'conversion_action';
+  }
+
+  return null;
+}
+
+/**
+ * Check if operation is already in Opteo format
+ * @param {Object} operation
+ * @returns {boolean}
+ */
+function isOpteoFormat(operation) {
+  return !!(operation &&
+    typeof operation.entity === 'string' &&
+    operation.resource !== undefined);
+}
+
+/**
+ * Get operation type from standard format operation
+ * @param {Object} operation
+ * @returns {string|null} - 'create', 'update', 'remove', or null
+ */
+function getStandardOperationType(operation) {
+  if (!operation || typeof operation !== 'object') return null;
+  if ('create' in operation) return 'create';
+  if ('update' in operation) return 'update';
+  if ('remove' in operation) return 'remove';
+  return null;
+}
+
+/**
+ * Transform standard format operation to Opteo format
+ * @param {Object} operation - Standard format operation
+ * @param {number} index - Operation index for error messages
+ * @returns {Object} - Opteo format operation
+ * @throws {Error} - If entity cannot be inferred
+ */
+function transformToOpteoFormat(operation, index) {
+  const opType = getStandardOperationType(operation);
+
+  if (!opType) {
+    throw new Error(
+      `Operation ${index}: Invalid format. Expected { create: {...} }, { update: {...} }, { remove: "..." }, ` +
+      `or Opteo format { entity: "...", operation: "...", resource: {...} }`
+    );
+  }
+
+  let entity = null;
+  let resource = null;
+
+  if (opType === 'remove') {
+    // Remove operations have resource_name as string value
+    const resourceName = operation.remove;
+    if (typeof resourceName !== 'string') {
+      throw new Error(`Operation ${index}: 'remove' value must be a resource_name string`);
+    }
+    entity = inferEntityFromResourceName(resourceName);
+    resource = { resource_name: resourceName };
+  } else {
+    // Create/Update operations have resource as object
+    resource = operation[opType];
+    if (!resource || typeof resource !== 'object') {
+      throw new Error(`Operation ${index}: '${opType}' value must be an object`);
+    }
+
+    // Try to infer entity from resource_name first (for updates)
+    if (resource.resource_name) {
+      entity = inferEntityFromResourceName(resource.resource_name);
+    }
+
+    // For creates without resource_name, infer from structure
+    if (!entity && opType === 'create') {
+      entity = inferEntityFromCreateResource(resource);
+    }
+  }
+
+  // Check for explicit entity hint in the operation
+  if (!entity && operation._entity) {
+    entity = operation._entity;
+  }
+
+  if (!entity) {
+    throw new Error(
+      `Operation ${index}: Could not infer entity type. Please use Opteo format: ` +
+      `{ entity: "campaign", operation: "${opType}", resource: {...} } ` +
+      `or add "_entity" field to your operation.`
+    );
+  }
+
+  return {
+    entity,
+    operation: opType,
+    resource
+  };
+}
+
+/**
+ * Transform operations array to Opteo format
+ * Passes through Opteo format operations, transforms standard format
+ * @param {Array} operations - Array of operations (mixed formats allowed)
+ * @returns {{ operations: Array, warnings: Array }} - Transformed operations and any warnings
+ */
+export function normalizeOperations(operations) {
+  const normalizedOps = [];
+  const warnings = [];
+
+  for (let i = 0; i < operations.length; i++) {
+    const op = operations[i];
+
+    if (isOpteoFormat(op)) {
+      // Already in Opteo format - pass through
+      normalizedOps.push(op);
+    } else {
+      // Transform from standard format
+      const transformed = transformToOpteoFormat(op, i);
+      normalizedOps.push(transformed);
+      warnings.push(`Operation ${i}: Transformed from standard format (entity: ${transformed.entity})`);
+    }
+  }
+
+  return { operations: normalizedOps, warnings };
+}
+
+// Export helpers for testing
+export {
+  inferEntityFromResourceName,
+  inferEntityFromCreateResource,
+  isOpteoFormat,
+  getStandardOperationType,
+  RESOURCE_PATH_TO_ENTITY
+};