@cesteral/gads-mcp 1.0.0

package/dist/mcp-server/prompts/definitions/campaign-setup-workflow.prompt.js

@@ -0,0 +1,237 @@
+export const campaignSetupWorkflowPrompt = {
+    name: "gads_campaign_setup_workflow",
+    description: "Step-by-step workflow for creating a complete Google Ads Search campaign (Budget → Campaign → Ad Group → Ads → Keywords)",
+    arguments: [
+        {
+            name: "customerId",
+            description: "Google Ads customer ID (no dashes)",
+            required: true,
+        },
+    ],
+};
+export function getCampaignSetupWorkflowMessage(args) {
+    const customerId = args?.customerId || "{customerId}";
+    return `# Google Ads Campaign Setup Workflow
+
+## Context
+- Customer ID: \`${customerId}\`
+- Platform: Google Ads API v23
+- Campaign Type: Search (most common)
+
+This workflow guides you through creating a full campaign hierarchy. Each step depends on the previous one.
+
+---
+
+## Step 1: Verify the Account
+
+Confirm the account exists and is accessible.
+
+\`\`\`
+Tool: gads_list_accounts
+Input: {}
+\`\`\`
+
+**Check**: Confirm \`${customerId}\` appears in the list.
+
+---
+
+## Step 2: Create a Campaign Budget
+
+⚠️ **GOTCHA**: Google Ads requires a separate CampaignBudget entity. Create it before the campaign.
+
+\`\`\`
+Tool: gads_create_entity
+Input: {
+  "entityType": "campaignBudget",
+  "customerId": "${customerId}",
+  "data": {
+    "name": "My Campaign Budget",
+    "amountMicros": "50000000",
+    "deliveryMethod": "STANDARD"
+  }
+}
+\`\`\`
+
+**Save**: Note the returned resource name (e.g., \`customers/${customerId}/campaignBudgets/{budgetId}\`).
+
+> \`amountMicros\` is the **daily** budget in micros. $50/day = "50000000".
+
+---
+
+## Step 3: Create the Campaign
+
+\`\`\`
+Tool: gads_create_entity
+Input: {
+  "entityType": "campaign",
+  "customerId": "${customerId}",
+  "data": {
+    "name": "My Search Campaign",
+    "advertisingChannelType": "SEARCH",
+    "status": "PAUSED",
+    "campaignBudget": "customers/${customerId}/campaignBudgets/{budgetId}",
+    "startDate": "2025-03-01",
+    "networkSettings": {
+      "targetGoogleSearch": true,
+      "targetSearchNetwork": true,
+      "targetContentNetwork": false,
+      "targetPartnerSearchNetwork": false
+    },
+    "manualCpc": {
+      "enhancedCpcEnabled": false
+    }
+  }
+}
+\`\`\`
+
+**Save**: Note the returned resource name (e.g., \`customers/${customerId}/campaigns/{campaignId}\`).
+
+### Common Gotchas
+- Set \`status: "PAUSED"\` initially — enable after full setup is verified
+- \`campaignBudget\` must be the full resource name from Step 2
+- \`advertisingChannelType\` cannot be changed after creation
+- Choose bidding strategy carefully: \`manualCpc\` for control, \`maximizeConversions\` for automation
+
+---
+
+## Step 4: Create Ad Group(s)
+
+\`\`\`
+Tool: gads_create_entity
+Input: {
+  "entityType": "adGroup",
+  "customerId": "${customerId}",
+  "data": {
+    "name": "My Ad Group",
+    "campaign": "customers/${customerId}/campaigns/{campaignId}",
+    "status": "ENABLED",
+    "type": "SEARCH_STANDARD",
+    "cpcBidMicros": "2500000"
+  }
+}
+\`\`\`
+
+**Save**: Note the returned resource name.
+
+> \`cpcBidMicros\` is the default max CPC bid. $2.50 = "2500000".
+
+---
+
+## Step 5: Add Keywords
+
+\`\`\`
+Tool: gads_create_entity
+Input: {
+  "entityType": "keyword",
+  "customerId": "${customerId}",
+  "data": {
+    "adGroup": "customers/${customerId}/adGroups/{adGroupId}",
+    "status": "ENABLED",
+    "keyword": {
+      "text": "running shoes",
+      "matchType": "PHRASE"
+    },
+    "cpcBidMicros": "3000000"
+  }
+}
+\`\`\`
+
+### Keyword Strategy Tips
+- Start with 10-20 keywords per ad group
+- Use a mix of match types (Broad for reach, Phrase/Exact for precision)
+- Add negative keywords to exclude irrelevant searches
+- Group related keywords together in the same ad group
+
+---
+
+## Step 6: Create Responsive Search Ads
+
+\`\`\`
+Tool: gads_create_entity
+Input: {
+  "entityType": "ad",
+  "customerId": "${customerId}",
+  "data": {
+    "adGroup": "customers/${customerId}/adGroups/{adGroupId}",
+    "status": "ENABLED",
+    "ad": {
+      "responsiveSearchAd": {
+        "headlines": [
+          { "text": "Buy Running Shoes" },
+          { "text": "Free Shipping Available" },
+          { "text": "Shop Top Brands Today" }
+        ],
+        "descriptions": [
+          { "text": "Wide selection of running shoes. Free returns on all orders." },
+          { "text": "Top brands at great prices. Order today and get free shipping." }
+        ],
+        "path1": "shoes",
+        "path2": "running"
+      },
+      "finalUrls": ["https://www.example.com/running-shoes"]
+    }
+  }
+}
+\`\`\`
+
+### Ad Copy Tips
+- Provide 8-15 headlines and 3-4 descriptions for best performance
+- Headlines: max 30 characters each
+- Descriptions: max 90 characters each
+- Include keywords in headlines and descriptions
+- Google auto-tests combinations and optimizes
+
+---
+
+## Step 7: Enable the Campaign
+
+After verifying all components are set up correctly:
+
+\`\`\`
+Tool: gads_update_entity
+Input: {
+  "entityType": "campaign",
+  "customerId": "${customerId}",
+  "entityId": "{campaignId}",
+  "data": {
+    "status": "ENABLED"
+  },
+  "updateMask": "status"
+}
+\`\`\`
+
+---
+
+## Step 8: Verify the Hierarchy
+
+Confirm everything was created correctly:
+
+1. List campaigns: \`gads_list_entities\` with \`{ "entityType": "campaign", "customerId": "${customerId}" }\`
+2. List ad groups: \`gads_list_entities\` with \`{ "entityType": "adGroup", "customerId": "${customerId}", "filters": { "ad_group.campaign": "= 'customers/${customerId}/campaigns/{campaignId}'" } }\`
+3. Check performance after 24h: \`gads_gaql_search\` with campaign performance GAQL query
+
+---
+
+## Success Checklist
+
+- [ ] Account verified and accessible
+- [ ] Campaign budget created with daily amount
+- [ ] Campaign created (initially PAUSED) with budget linked
+- [ ] Ad group(s) created with appropriate CPC bids
+- [ ] Keywords added with proper match types
+- [ ] Responsive Search Ads created with multiple headlines/descriptions
+- [ ] Campaign enabled after verification
+- [ ] Hierarchy verified via list queries
+
+## Related Resources
+- \`entity-hierarchy://gads\` — Entity relationships and API patterns
+- \`entity-schema://{entityType}\` — Full field reference per entity type
+- \`gaql-reference://syntax\` — GAQL query syntax and common patterns
+
+## Bulk Alternative
+For creating multiple entities at once, use:
+- \`gads_bulk_mutate\` — batch create/update/remove in single API call
+- \`gads_bulk_update_status\` — batch enable/pause after verification
+`;
+}
+//# sourceMappingURL=campaign-setup-workflow.prompt.js.map

package/dist/mcp-server/prompts/definitions/campaign-setup-workflow.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign-setup-workflow.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/campaign-setup-workflow.prompt.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,2BAA2B,GAAW;IACjD,IAAI,EAAE,8BAA8B;IACpC,WAAW,EACT,0HAA0H;IAC5H,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,oCAAoC;YACjD,QAAQ,EAAE,IAAI;SACf;KACF;CACF,CAAC;AAEF,MAAM,UAAU,+BAA+B,CAAC,IAA6B;IAC3E,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IAEtD,OAAO;;;mBAGU,UAAU;;;;;;;;;;;;;;;;;uBAiBN,UAAU;;;;;;;;;;;;mBAYd,UAAU;;;;;;;;;+DASkC,UAAU;;;;;;;;;;;;mBAYtD,UAAU;;;;;mCAKM,UAAU;;;;;;;;;;;;;;;+DAekB,UAAU;;;;;;;;;;;;;;;;mBAgBtD,UAAU;;;6BAGA,UAAU;;;;;;;;;;;;;;;;;;;;mBAoBpB,UAAU;;4BAED,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;mBAyBnB,UAAU;;4BAED,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAuCnB,UAAU;;;;;;;;;;;;;;;8FAeiE,UAAU;6FACX,UAAU,sDAAsD,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;CAyBtK,CAAC;AACF,CAAC"}

package/dist/mcp-server/prompts/definitions/creative-setup-workflow.prompt.d.ts

@@ -0,0 +1,4 @@
+import type { Prompt } from "@modelcontextprotocol/sdk/types.js";
+export declare const gadsCreativeSetupWorkflowPrompt: Prompt;
+export declare function getGadsCreativeSetupWorkflowMessage(args?: Record<string, string>): string;
+//# sourceMappingURL=creative-setup-workflow.prompt.d.ts.map

package/dist/mcp-server/prompts/definitions/creative-setup-workflow.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creative-setup-workflow.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/creative-setup-workflow.prompt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAEjE,eAAO,MAAM,+BAA+B,EAAE,MAW7C,CAAC;AAEF,wBAAgB,mCAAmC,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CA8IzF"}

package/dist/mcp-server/prompts/definitions/creative-setup-workflow.prompt.js

@@ -0,0 +1,154 @@
+export const gadsCreativeSetupWorkflowPrompt = {
+    name: "creative_setup_workflow",
+    description: "Step-by-step guide for creating Google Ads responsive display ads and video creatives",
+    arguments: [
+        {
+            name: "customerId",
+            description: "Google Ads Customer ID (e.g., 1234567890)",
+            required: true,
+        },
+    ],
+};
+export function getGadsCreativeSetupWorkflowMessage(args) {
+    const customerId = args?.customerId || "{customerId}";
+    return `# Google Ads Creative Setup Workflow
+
+## Prerequisites
+- Customer ID: \`${customerId}\`
+- Google Ads account with active campaigns
+
+## Overview
+Google Ads uses **Responsive Display Ads (RDA)** and **Responsive Search Ads (RSA)** for automated asset optimization.
+
+---
+
+## Step 1: Understand Ad Types
+
+**Responsive Display Ads**: Provide headlines, descriptions, images, logos → Google optimizes combinations.
+**Responsive Search Ads**: Provide 3-15 headlines, 2-4 descriptions → Google optimizes combinations.
+**Video Ads**: YouTube video URL + companion banner.
+
+## Step 2: Create a Responsive Display Ad
+
+\`\`\`json
+gads_create_entity({
+  "entityType": "ad",
+  "customerId": "${customerId}",
+  "data": {
+    "type": "RESPONSIVE_DISPLAY_AD",
+    "responsiveDisplayAd": {
+      "headlines": [
+        { "text": "Your Headline 1" },
+        { "text": "Your Headline 2" }
+      ],
+      "longHeadline": { "text": "Your Long Headline" },
+      "descriptions": [
+        { "text": "Your description here" }
+      ],
+      "businessName": "Your Business Name",
+      "marketingImages": [
+        {
+          "asset": "customers/${customerId}/assets/{image_asset_id}",
+          "fieldType": "MARKETING_IMAGE"
+        }
+      ],
+      "logoImages": [
+        {
+          "asset": "customers/${customerId}/assets/{logo_asset_id}",
+          "fieldType": "LOGO_IMAGE"
+        }
+      ]
+    },
+    "finalUrls": ["https://yoursite.com"]
+  }
+})
+\`\`\`
+
+⚠️ **GOTCHA**: Google Ads requires image assets to be uploaded first as Asset entities (type: IMAGE). Use \`gads_create_entity\` with entityType "asset" to upload via URL.
+
+## Step 3: Upload Image as Asset
+
+\`\`\`json
+gads_create_entity({
+  "entityType": "asset",
+  "customerId": "${customerId}",
+  "data": {
+    "type": "IMAGE",
+    "imageAsset": {
+      "data": "{base64_encoded_image_or_url}"
+    },
+    "name": "Banner 1200x628"
+  }
+})
+\`\`\`
+
+⚠️ **GOTCHA**: Google Ads API requires images as base64-encoded data or via asset resource name. For URL-based uploads, use the Asset API with imageAsset.data as base64.
+
+## Step 4: Create Responsive Search Ad
+
+\`\`\`json
+gads_create_entity({
+  "entityType": "ad",
+  "customerId": "${customerId}",
+  "data": {
+    "type": "RESPONSIVE_SEARCH_AD",
+    "responsiveSearchAd": {
+      "headlines": [
+        { "text": "Headline 1", "pinned_field": "HEADLINE_1" },
+        { "text": "Headline 2" },
+        { "text": "Headline 3" }
+      ],
+      "descriptions": [
+        { "text": "Description line 1 here" },
+        { "text": "Description line 2 here" }
+      ]
+    },
+    "finalUrls": ["https://yoursite.com"]
+  }
+})
+\`\`\`
+
+## Step 5: Preview Ad
+
+\`\`\`json
+gads_get_ad_preview({
+  "customerId": "${customerId}",
+  "adId": "{adId_from_step_2_or_4}"
+})
+\`\`\`
+
+## Step 6: Create Ad Group Ad
+
+To link the ad to an ad group:
+\`\`\`json
+gads_create_entity({
+  "entityType": "adGroupAd",
+  "customerId": "${customerId}",
+  "data": {
+    "adGroup": "customers/${customerId}/adGroups/{adGroupId}",
+    "ad": { "resourceName": "customers/${customerId}/ads/{adId}" },
+    "status": "PAUSED"
+  }
+})
+\`\`\`
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Image too small" | Below min dimensions | Use 600x314px min (1.91:1), 300x300px min (square) |
+| "Headline too long" | Over 30 characters | Shorten to 30 chars max |
+| "Description too long" | Over 90 characters | Shorten to 90 chars max |
+| "Invalid landing page" | URL not approved | Verify URL loads correctly |
+| "Policy violation" | Ad content issue | Review Google Ads policies |
+
+## Success Criteria
+- [ ] Assets uploaded (image_asset_id obtained)
+- [ ] Ad created (adId obtained)
+- [ ] Ad linked to ad group (adGroupAd created)
+- [ ] Preview reviewed
+- [ ] Status changed to ENABLED when ready
+
+`;
+}
+//# sourceMappingURL=creative-setup-workflow.prompt.js.map

package/dist/mcp-server/prompts/definitions/creative-setup-workflow.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"creative-setup-workflow.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/creative-setup-workflow.prompt.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,+BAA+B,GAAW;IACrD,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EACT,uFAAuF;IACzF,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,2CAA2C;YACxD,QAAQ,EAAE,IAAI;SACf;KACF;CACF,CAAC;AAEF,MAAM,UAAU,mCAAmC,CAAC,IAA6B;IAC/E,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IAEtD,OAAO;;;mBAGU,UAAU;;;;;;;;;;;;;;;;;;;mBAmBV,UAAU;;;;;;;;;;;;;;;gCAeG,UAAU;;;;;;gCAMV,UAAU;;;;;;;;;;;;;;;;;mBAiBvB,UAAU;;;;;;;;;;;;;;;;;;mBAkBV,UAAU;;;;;;;;;;;;;;;;;;;;;;;mBAuBV,UAAU;;;;;;;;;;;mBAWV,UAAU;;4BAED,UAAU;yCACG,UAAU;;;;;;;;;;;;;;;;;;;;;;;CAuBlD,CAAC;AACF,CAAC"}

package/dist/mcp-server/prompts/definitions/cross-platform-campaign-setup.prompt.d.ts

@@ -0,0 +1,4 @@
+import type { Prompt } from "@modelcontextprotocol/sdk/types.js";
+export declare const crossPlatformCampaignSetupPrompt: Prompt;
+export declare function getCrossPlatformCampaignSetupMessage(args?: Record<string, string>): string;
+//# sourceMappingURL=cross-platform-campaign-setup.prompt.d.ts.map

package/dist/mcp-server/prompts/definitions/cross-platform-campaign-setup.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-platform-campaign-setup.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/cross-platform-campaign-setup.prompt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAQjE,eAAO,MAAM,gCAAgC,EAAE,MAiB9C,CAAC;AAEF,wBAAgB,oCAAoC,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CA0R1F"}