@channel47/google-ads-mcp 1.0.2 → 1.0.5

package/package.json

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

package/server/tools/mutate.js

@@ -60,10 +60,14 @@ export async function mutate(params) {
     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;
+        // Extract full field path for debugging (e.g., "operations.create.campaign_bidding_strategy")
+        const fieldPath = err.location?.field_path_elements?.map(e => e.field_name).join('.') || null;
         partialFailureErrors.push({
           message: err.message || JSON.stringify(err.error_code),
           error_code: err.error_code,
-          operation_index: opIndex
+          operation_index: opIndex,
+          field_path: fieldPath,
+          trigger: err.trigger?.string_value || null
         });
       }
 
@@ -91,10 +95,13 @@ export async function mutate(params) {
       || [];
 
     for (const error of errorDetails) {
+      const fieldPath = error.location?.field_path_elements?.map(e => e.field_name).join('.') || null;
       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
+        operation_index: error.location?.field_path_elements?.[0]?.index ?? -1,
+        field_path: fieldPath,
+        trigger: error.trigger?.string_value || null
       });
     }
   }

package/server/utils/image-asset.js

@@ -0,0 +1,246 @@
+/**
+ * Image asset processing utility
+ * Handles file path resolution, validation, and base64 encoding for ImageAsset uploads
+ */
+
+import { readFileSync, statSync, accessSync, constants } from 'fs';
+import { resolve, extname, isAbsolute } from 'path';
+
+// Google Ads API limits
+const MAX_FILE_SIZE_BYTES = 5 * 1024 * 1024; // 5MB
+
+// Supported image formats with their Google Ads MIME type enum values
+const SUPPORTED_FORMATS = {
+  '.jpg': 'IMAGE_JPEG',
+  '.jpeg': 'IMAGE_JPEG',
+  '.png': 'IMAGE_PNG'
+};
+
+// Magic bytes for image format validation
+const MAGIC_BYTES = {
+  jpeg: [0xFF, 0xD8, 0xFF],
+  png: [0x89, 0x50, 0x4E, 0x47]
+};
+
+/**
+ * Validate file path for security concerns
+ * @param {string} filePath - Path to validate
+ * @returns {{ valid: boolean, error?: string, resolvedPath?: string }}
+ */
+export function validateFilePath(filePath) {
+  if (!filePath || typeof filePath !== 'string') {
+    return { valid: false, error: 'File path must be a non-empty string' };
+  }
+
+  // Require absolute paths to prevent ambiguity
+  if (!isAbsolute(filePath)) {
+    return {
+      valid: false,
+      error: `File path must be absolute. Received: "${filePath}"`
+    };
+  }
+
+  // Resolve to canonical path (handles .. and symlinks)
+  const resolvedPath = resolve(filePath);
+
+  // Check for path traversal attempts (.. in original that resolves differently)
+  if (resolvedPath !== filePath && filePath.includes('..')) {
+    return {
+      valid: false,
+      error: 'Path traversal detected. Use canonical absolute paths.'
+    };
+  }
+
+  return { valid: true, resolvedPath };
+}
+
+/**
+ * Validate image file exists, is readable, and meets size requirements
+ * @param {string} filePath - Absolute path to image file
+ * @returns {{ valid: boolean, error?: string, size?: number }}
+ */
+export function validateFileAccess(filePath) {
+  try {
+    // Check file exists and is readable
+    accessSync(filePath, constants.R_OK);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { valid: false, error: `File not found: "${filePath}"` };
+    }
+    if (err.code === 'EACCES') {
+      return { valid: false, error: `Permission denied: "${filePath}"` };
+    }
+    return { valid: false, error: `Cannot access file: ${err.message}` };
+  }
+
+  // Check file size
+  try {
+    const stats = statSync(filePath);
+
+    if (!stats.isFile()) {
+      return { valid: false, error: `Not a file: "${filePath}"` };
+    }
+
+    if (stats.size === 0) {
+      return { valid: false, error: `File is empty: "${filePath}"` };
+    }
+
+    if (stats.size > MAX_FILE_SIZE_BYTES) {
+      const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
+      return {
+        valid: false,
+        error: `File size ${sizeMB}MB exceeds Google Ads limit of 5MB`
+      };
+    }
+
+    return { valid: true, size: stats.size };
+  } catch (err) {
+    return { valid: false, error: `Cannot read file stats: ${err.message}` };
+  }
+}
+
+/**
+ * Detect MIME type from file extension and validate with magic bytes
+ * @param {string} filePath - Path to image file
+ * @param {Buffer} fileBuffer - File contents (first few bytes needed)
+ * @returns {{ valid: boolean, mimeType?: string, error?: string }}
+ */
+export function detectAndValidateFormat(filePath, fileBuffer) {
+  const ext = extname(filePath).toLowerCase();
+
+  // Check extension is supported
+  if (!SUPPORTED_FORMATS[ext]) {
+    return {
+      valid: false,
+      error: `Unsupported image format: "${ext}". Supported: JPEG, PNG`
+    };
+  }
+
+  // Validate magic bytes match extension
+  const isJpeg = MAGIC_BYTES.jpeg.every((b, i) => fileBuffer[i] === b);
+  const isPng = MAGIC_BYTES.png.every((b, i) => fileBuffer[i] === b);
+
+  if ((ext === '.jpg' || ext === '.jpeg') && !isJpeg) {
+    return {
+      valid: false,
+      error: `File "${filePath}" has .jpg extension but is not a valid JPEG`
+    };
+  }
+
+  if (ext === '.png' && !isPng) {
+    return {
+      valid: false,
+      error: `File "${filePath}" has .png extension but is not a valid PNG`
+    };
+  }
+
+  // Determine actual format from magic bytes
+  let mimeType;
+  if (isJpeg) {
+    mimeType = 'IMAGE_JPEG';
+  } else if (isPng) {
+    mimeType = 'IMAGE_PNG';
+  } else {
+    return {
+      valid: false,
+      error: `Could not detect image format for "${filePath}"`
+    };
+  }
+
+  return { valid: true, mimeType };
+}
+
+/**
+ * Process an image file path into base64-encoded image_asset data
+ * @param {string} filePath - Absolute path to image file
+ * @returns {{ success: boolean, data?: Object, error?: string }}
+ */
+export function processImageFile(filePath) {
+  // Step 1: Validate path security
+  const pathValidation = validateFilePath(filePath);
+  if (!pathValidation.valid) {
+    return { success: false, error: pathValidation.error };
+  }
+
+  // Step 2: Validate file access and size
+  const accessValidation = validateFileAccess(pathValidation.resolvedPath);
+  if (!accessValidation.valid) {
+    return { success: false, error: accessValidation.error };
+  }
+
+  // Step 3: Read file
+  let fileBuffer;
+  try {
+    fileBuffer = readFileSync(pathValidation.resolvedPath);
+  } catch (err) {
+    return { success: false, error: `Failed to read file: ${err.message}` };
+  }
+
+  // Step 4: Validate format
+  const formatValidation = detectAndValidateFormat(
+    pathValidation.resolvedPath,
+    fileBuffer
+  );
+  if (!formatValidation.valid) {
+    return { success: false, error: formatValidation.error };
+  }
+
+  // Step 5: Encode to base64
+  // CRITICAL: Opteo library requires base64 string, NOT Buffer
+  const base64Data = fileBuffer.toString('base64');
+
+  return {
+    success: true,
+    data: {
+      data: base64Data,
+      file_size: accessValidation.size,
+      mime_type: formatValidation.mimeType
+    }
+  };
+}
+
+/**
+ * Transform a resource object by processing image_file_path if present
+ * @param {Object} resource - Resource object that may contain image_file_path
+ * @returns {{ resource: Object, processed: boolean, error?: string }}
+ */
+export function transformImageAssetResource(resource) {
+  if (!resource || typeof resource !== 'object') {
+    return { resource, processed: false };
+  }
+
+  // Check if this is an asset with image_file_path
+  if (!resource.image_file_path) {
+    return { resource, processed: false };
+  }
+
+  // Validate this is an IMAGE type asset (or infer it)
+  if (resource.type && resource.type !== 'IMAGE') {
+    return {
+      resource,
+      processed: false,
+      error: `image_file_path is only valid for IMAGE assets, got type: ${resource.type}`
+    };
+  }
+
+  // Process the image file
+  const result = processImageFile(resource.image_file_path);
+  if (!result.success) {
+    return { resource, processed: false, error: result.error };
+  }
+
+  // Build the transformed resource (remove image_file_path, add image_asset)
+  const { image_file_path, ...restResource } = resource;
+
+  return {
+    resource: {
+      ...restResource,
+      type: 'IMAGE',  // Ensure type is set
+      image_asset: result.data
+    },
+    processed: true
+  };
+}
+
+// Export constants for testing
+export { MAX_FILE_SIZE_BYTES, SUPPORTED_FORMATS, MAGIC_BYTES };

package/server/utils/operation-transform.js

@@ -3,6 +3,17 @@
  * Converts standard Google Ads API format to Opteo library format
  */
 
+import { transformImageAssetResource } from './image-asset.js';
+
+/**
+ * Entities that legitimately use resource_name in CREATE operations.
+ * These use temporary resource IDs (-1, -2, etc.) for atomic multi-resource creation.
+ * 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
+]);
+
 /**
  * Resource name URL path segments to entity type mapping
  * Based on Google Ads API resource name patterns
@@ -156,12 +167,13 @@ function transformToOpteoFormat(operation, index) {
 
   if (opType === 'remove') {
     // Remove operations have resource_name as string value
+    // The Opteo library expects resource to be the string directly for remove ops
     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 };
+    resource = resourceName;  // String, not object - Opteo expects { remove: "resource_name" }
   } else {
     // Create/Update operations have resource as object
     resource = operation[opType];
@@ -193,6 +205,27 @@ function transformToOpteoFormat(operation, index) {
     );
   }
 
+  // Strip resource_name from CREATE operations (API generates it automatically)
+  // Exception: entities that use temp IDs for atomic multi-resource creation
+  // See: https://developers.google.com/google-ads/api/docs/campaigns/create-campaigns
+  if (opType === 'create' && resource.resource_name) {
+    if (!ENTITIES_REQUIRING_RESOURCE_NAME_IN_CREATE.has(entity)) {
+      const { resource_name, ...resourceWithoutName } = resource;
+      resource = resourceWithoutName;
+    }
+  }
+
+  // Process image file paths in asset resources
+  if (opType === 'create' && entity === 'asset') {
+    const imageResult = transformImageAssetResource(resource);
+    if (imageResult.error) {
+      throw new Error(`Operation ${index}: ${imageResult.error}`);
+    }
+    if (imageResult.processed) {
+      resource = imageResult.resource;
+    }
+  }
+
   return {
     entity,
     operation: opType,
@@ -214,8 +247,32 @@ export function normalizeOperations(operations) {
     const op = operations[i];
 
     if (isOpteoFormat(op)) {
-      // Already in Opteo format - pass through
-      normalizedOps.push(op);
+      // Already in Opteo format - pass through, but normalize special cases
+
+      // Handle image_file_path in Opteo format asset operations
+      if (op.entity === 'asset' && op.operation === 'create' && op.resource?.image_file_path) {
+        const imageResult = transformImageAssetResource(op.resource);
+        if (imageResult.error) {
+          throw new Error(`Operation ${i}: ${imageResult.error}`);
+        }
+        if (imageResult.processed) {
+          normalizedOps.push({
+            ...op,
+            resource: imageResult.resource
+          });
+          continue;
+        }
+      }
+
+      // 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);
+      }
     } else {
       // Transform from standard format
       const transformed = transformToOpteoFormat(op, i);