@cesteral/gads-mcp 1.0.0

package/dist/mcp-server/prompts/definitions/targeting-discovery-workflow.prompt.js

@@ -0,0 +1,223 @@
+export const targetingDiscoveryWorkflowPrompt = {
+    name: "gads_targeting_discovery_workflow",
+    description: "Step-by-step guide for discovering and analyzing Google Ads targeting segments via GAQL. Covers audience, keyword, geographic, and device targeting, plus performance insights by segment.",
+    arguments: [
+        {
+            name: "customerId",
+            description: "Google Ads customer ID (no dashes)",
+            required: true,
+        },
+        {
+            name: "campaignId",
+            description: "Campaign ID to scope targeting discovery (optional)",
+            required: false,
+        },
+    ],
+};
+export function getTargetingDiscoveryWorkflowMessage(args) {
+    const customerId = args?.customerId || "{customerId}";
+    const campaignId = args?.campaignId || "{campaignId}";
+    return `# Google Ads Targeting Discovery Workflow
+
+## Context
+- Customer ID: \`${customerId}\`
+- Campaign ID: \`${campaignId}\`
+- Platform: Google Ads API v23
+- Tool: \`gads_gaql_search\`, \`gads_get_insights\`
+
+This workflow helps you explore what targeting is already applied, understand segment performance, and identify targeting opportunities.
+
+---
+
+## Step 1: Understand Available Targeting Dimensions
+
+Google Ads targeting operates across several dimensions:
+
+| Dimension | Description | GAQL Resource |
+|-----------|-------------|---------------|
+| Keywords | Search query matching | \`keyword_view\` |
+| Audiences | User interest / demographic segments | \`ad_group_audience_view\` |
+| Geographic | Country, region, city, DMA | \`geographic_view\` |
+| Device | Desktop, mobile, tablet | Segment via \`segments.device\` |
+| Ad Schedule | Day of week, hour of day | Segment via \`segments.hour\`, \`segments.day_of_week\` |
+| Demographics | Age, gender, parental status | \`age_range_view\`, \`gender_view\` |
+
+---
+
+## Step 2: Discover Existing Keyword Targeting
+
+List the keywords active in the campaign:
+
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group.name, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM keyword_view WHERE campaign.id = ${campaignId} AND segments.date DURING LAST_30_DAYS AND ad_group_criterion.status != 'REMOVED' ORDER BY metrics.impressions DESC LIMIT 100"
+}
+\`\`\`
+
+**Analyze**: Identify high-impression / low-conversion keywords for bid adjustments or exclusion.
+
+---
+
+## Step 3: Discover Geographic Performance
+
+Identify which geographic locations are driving performance:
+
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT geographic_view.country_criterion_id, geographic_view.location_type, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.cost_per_conversion FROM geographic_view WHERE campaign.id = ${campaignId} AND segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC LIMIT 50"
+}
+\`\`\`
+
+### Top Cities Query
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT segments.geo_target_city, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE campaign.id = ${campaignId} AND segments.date DURING LAST_30_DAYS ORDER BY metrics.impressions DESC LIMIT 50"
+}
+\`\`\`
+
+**Analyze**: Look for high-cost / low-conversion geographies to exclude or reduce bids.
+
+---
+
+## Step 4: Analyze Device Performance
+
+Understand how performance varies by device type:
+
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT segments.device, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.ctr, metrics.conversions, metrics.cost_per_conversion FROM campaign WHERE campaign.id = ${campaignId} AND segments.date DURING LAST_30_DAYS"
+}
+\`\`\`
+
+Device values: \`DESKTOP\`, \`MOBILE\`, \`TABLET\`, \`CONNECTED_TV\`
+
+**Analyze**: If mobile CPAs are significantly higher, consider adding a mobile bid adjustment.
+
+---
+
+## Step 5: Analyze Demographic Targeting
+
+Review age and gender breakdowns:
+
+### Age Range Performance
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT ad_group_criterion.age_range.type, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM age_range_view WHERE campaign.id = ${campaignId} AND segments.date DURING LAST_30_DAYS ORDER BY metrics.impressions DESC"
+}
+\`\`\`
+
+### Gender Performance
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT ad_group_criterion.gender.type, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM gender_view WHERE campaign.id = ${campaignId} AND segments.date DURING LAST_30_DAYS"
+}
+\`\`\`
+
+---
+
+## Step 6: Discover Audience Segment Performance
+
+Analyze in-market and affinity audience performance:
+
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT ad_group_audience_view.resource_name, user_list.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM ad_group_audience_view WHERE campaign.id = ${campaignId} AND segments.date DURING LAST_30_DAYS ORDER BY metrics.impressions DESC LIMIT 50"
+}
+\`\`\`
+
+---
+
+## Step 7: Use gads_get_insights for Segment Summaries
+
+For a higher-level view of performance by entity and segment:
+
+\`\`\`
+Tool: gads_get_insights
+Input: {
+  "customerId": "${customerId}",
+  "entityType": "campaign",
+  "dateRange": "LAST_30_DAYS"
+}
+\`\`\`
+
+This returns aggregated performance metrics and can surface top/bottom performers quickly.
+
+---
+
+## Step 8: Discover Search Term Opportunities
+
+Find new keyword opportunities from actual search queries:
+
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT search_term_view.search_term, search_term_view.status, metrics.impressions, metrics.clicks, metrics.conversions, metrics.cost_micros FROM search_term_view WHERE campaign.id = ${campaignId} AND segments.date DURING LAST_30_DAYS AND metrics.impressions > 10 ORDER BY metrics.conversions DESC LIMIT 100"
+}
+\`\`\`
+
+**Analyze**:
+- High-conversion search terms → add as exact/phrase match keywords
+- Irrelevant terms → add as negative keywords
+- High-spend / zero-conversion terms → investigate match type issues
+
+---
+
+## Step 9: Ad Schedule Performance
+
+Identify the best hours and days to run ads:
+
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT segments.day_of_week, segments.hour, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE campaign.id = ${campaignId} AND segments.date DURING LAST_30_DAYS ORDER BY metrics.conversions DESC"
+}
+\`\`\`
+
+Day values: \`MONDAY\`, \`TUESDAY\`, \`WEDNESDAY\`, \`THURSDAY\`, \`FRIDAY\`, \`SATURDAY\`, \`SUNDAY\`
+
+---
+
+## Tips
+
+- **Combine dimensions carefully**: Some segments cannot be combined in a single GAQL query. If you get an error, split into separate queries.
+- **Micros conversion**: All cost values are in micros. Divide by 1,000,000 for actual currency.
+- **Zero impressions**: Entities with 0 impressions in the date range may simply be new, paused, or have limited targeting.
+- **Statistical significance**: Don't make targeting decisions on fewer than 100 impressions — results may be noise.
+- **Act on insights**: Use \`gads_update_entity\` with \`updateMask\` to apply bid adjustments, or \`gads_create_entity\` to add new keywords/audiences discovered here.
+
+---
+
+## Success Checklist
+
+- [ ] Keyword targeting reviewed — high-waste keywords identified
+- [ ] Geographic performance analyzed — low-performing locations noted
+- [ ] Device breakdown reviewed — mobile/desktop bid adjustments considered
+- [ ] Demographic performance reviewed — age/gender outliers identified
+- [ ] Audience segments analyzed — underperforming segments flagged
+- [ ] Search terms explored — new keyword opportunities discovered
+- [ ] Ad schedule analyzed — peak hours/days identified
+- [ ] Action plan created based on segment insights
+
+## Related Resources
+- \`gaql-reference://syntax\` — Full GAQL syntax and field reference
+- \`entity-hierarchy://gads\` — Entity relationships and targeting structure
+- \`entity-schema://keyword\` — Keyword entity field reference
+`;
+}
+//# sourceMappingURL=targeting-discovery-workflow.prompt.js.map

package/dist/mcp-server/prompts/definitions/targeting-discovery-workflow.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targeting-discovery-workflow.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/targeting-discovery-workflow.prompt.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,gCAAgC,GAAW;IACtD,IAAI,EAAE,mCAAmC;IACzC,WAAW,EACT,4LAA4L;IAC9L,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,oCAAoC;YACjD,QAAQ,EAAE,IAAI;SACf;QACD;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,qDAAqD;YAClE,QAAQ,EAAE,KAAK;SAChB;KACF;CACF,CAAC;AAEF,MAAM,UAAU,oCAAoC,CAAC,IAA6B;IAChF,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACtD,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IAEtD,OAAO;;;mBAGU,UAAU;mBACV,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBA8BV,UAAU;0QAC6O,UAAU;;;;;;;;;;;;;;;mBAejQ,UAAU;8OACiN,UAAU;;;;;;;;mBAQrO,UAAU;+JACkI,UAAU;;;;;;;;;;;;;;;mBAetJ,UAAU;gMACmK,UAAU;;;;;;;;;;;;;;;;;;mBAkBvL,UAAU;8KACiJ,UAAU;;;;;;;;mBAQrK,UAAU;wKAC2I,UAAU;;;;;;;;;;;;;mBAa/J,UAAU;yMAC4K,UAAU;;;;;;;;;;;;;mBAahM,UAAU;;;;;;;;;;;;;;;;;mBAiBV,UAAU;oMACuK,UAAU;;;;;;;;;;;;;;;;;;mBAkB3L,UAAU;0KAC6I,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCnL,CAAC;AACF,CAAC"}

package/dist/mcp-server/prompts/definitions/tool-schema-exploration.prompt.d.ts

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

package/dist/mcp-server/prompts/definitions/tool-schema-exploration.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema-exploration.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/tool-schema-exploration.prompt.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAEjE,eAAO,MAAM,2BAA2B,EAAE,MAYzC,CAAC;AAEF,wBAAgB,+BAA+B,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAiHrF"}

package/dist/mcp-server/prompts/definitions/tool-schema-exploration.prompt.js

@@ -0,0 +1,125 @@
+export const toolSchemaExplorationPrompt = {
+    name: "gads_tool_schema_exploration",
+    description: "Step-by-step workflow for exploring available Google Ads MCP tools, prompts, and resources with minimal context usage",
+    arguments: [
+        {
+            name: "objective",
+            description: "Exploration objective (e.g., entity management, GAQL reporting, troubleshooting)",
+            required: false,
+        },
+    ],
+};
+export function getToolSchemaExplorationMessage(args) {
+    const objective = args?.objective || "general capability discovery";
+    return `# Google Ads Tool and Schema Exploration
+
+## Context
+- Server: gads-mcp (Google Ads)
+- Objective: ${objective}
+
+Use this workflow to discover Google Ads MCP capabilities while minimizing token usage.
+
+---
+
+## Step 1: List Capabilities
+
+Run these three calls to see what's available:
+1. \`tools/list\` — See all available tools
+2. \`prompts/list\` — See workflow prompts
+3. \`resources/list\` — See on-demand documentation resources
+
+Do **not** fetch large resources before narrowing your scope.
+
+---
+
+## Step 2: Identify Your Task Path
+
+Pick one immediate action:
+
+| Task | Start Here |
+|------|-----------|
+| Create a campaign structure | Prompt: \`gads_campaign_setup_workflow\` |
+| Debug an entity issue | Prompt: \`gads_troubleshoot_entity\` |
+| Understand entity fields | Resource: \`entity-schema://{entityType}\` |
+| See CRUD examples | Resource: \`entity-examples://{entityType}\` |
+| Learn entity relationships | Resource: \`entity-hierarchy://gads\` |
+| Write GAQL queries | Resource: \`gaql-reference://syntax\` |
+
+---
+
+## Step 3: Fetch Targeted Resources
+
+Prefer specific resources over aggregate ones:
+
+| Need | Fetch |
+|------|-------|
+| Campaign fields | \`entity-schema://campaign\` (not \`://all\`) |
+| Ad group examples | \`entity-examples://adGroup\` (not \`://all\`) |
+| Keyword examples | \`entity-examples://keyword\` |
+| GAQL syntax | \`gaql-reference://syntax\` |
+| Available metrics & date ranges | \`insights-reference://gads\` |
+
+Only use \`://all\` resources when you need a cross-entity view.
+
+---
+
+## Step 4: Execute a Minimal Tool Call
+
+Start with the simplest useful call:
+
+| Action | Tool | Minimal Input |
+|--------|------|---------------|
+| Check an entity | \`gads_get_entity\` | \`entityType\` + \`customerId\` + \`entityId\` |
+| List entities | \`gads_list_entities\` | \`entityType\` + \`customerId\` |
+| Run a GAQL query | \`gads_gaql_search\` | \`customerId\` + \`query\` |
+| List accounts | \`gads_list_accounts\` | _(no arguments needed)_ |
+
+Inspect the output, then iterate with more specific calls.
+
+---
+
+## Available Tools Summary (15 tools)
+
+### Read Tools
+| Tool | Purpose | Notes |
+|------|---------|-------|
+| \`gads_gaql_search\` | Execute GAQL queries for ad-hoc reporting | Most flexible read tool |
+| \`gads_list_accounts\` | List accessible customer accounts | No arguments needed |
+| \`gads_get_entity\` | Get a single entity by type/ID | Returns full entity |
+| \`gads_list_entities\` | List entities with optional GAQL filters | Supports pagination |
+| \`gads_get_insights\` | Performance insights with preset params | Convenience wrapper |
+
+### Write Tools
+| Tool | Purpose | Notes |
+|------|---------|-------|
+| \`gads_create_entity\` | Create a new entity | Returns resource name |
+| \`gads_update_entity\` | Update an entity | Requires \`updateMask\` |
+| \`gads_remove_entity\` | Remove an entity | Sets status to REMOVED (permanent) |
+| \`gads_bulk_mutate\` | Batch create/update/remove | Up to 5000 operations |
+| \`gads_bulk_create_entities\` | Batch create entities | Max 50, partial failure |
+| \`gads_bulk_update_status\` | Batch enable/pause/remove | Convenience wrapper |
+| \`gads_adjust_bids\` | Batch adjust ad group bids | Safe read-modify-write |
+| \`gads_validate_entity\` | Dry-run validate entity payload | Returns validation errors |
+| \`gads_get_ad_preview\` | Get ad preview HTML/URL | Returns preview for an ad |
+| \`gads_get_pacing_status\` | Real-time pacing calc for a campaign | Reads spend + budget |
+
+### Supported Entity Types (6)
+\`campaign\`, \`adGroup\`, \`ad\`, \`keyword\`, \`campaignBudget\`, \`asset\`
+
+---
+
+## Context-Minimization Rules
+
+- Summarize fetched resources in your own words instead of pasting full content
+- Reuse facts from previous tool calls instead of re-fetching
+- Start with one tool call, inspect results, then decide next steps
+- Avoid requesting \`://all\` resources unless you need a complete overview
+
+## Suggested Next Steps
+- For campaign setup: invoke \`gads_campaign_setup_workflow\` prompt
+- For debugging: invoke \`gads_troubleshoot_entity\` prompt
+- For ad-hoc reporting: use \`gads_gaql_search\` directly
+- For bulk operations: use \`gads_bulk_mutate\` or \`gads_bulk_update_status\`
+`;
+}
+//# sourceMappingURL=tool-schema-exploration.prompt.js.map

package/dist/mcp-server/prompts/definitions/tool-schema-exploration.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema-exploration.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/tool-schema-exploration.prompt.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,2BAA2B,GAAW;IACjD,IAAI,EAAE,8BAA8B;IACpC,WAAW,EACT,uHAAuH;IACzH,SAAS,EAAE;QACT;YACE,IAAI,EAAE,WAAW;YACjB,WAAW,EACT,kFAAkF;YACpF,QAAQ,EAAE,KAAK;SAChB;KACF;CACF,CAAC;AAEF,MAAM,UAAU,+BAA+B,CAAC,IAA6B;IAC3E,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,IAAI,8BAA8B,CAAC;IAEpE,OAAO;;;;eAIM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyGvB,CAAC;AACF,CAAC"}

package/dist/mcp-server/prompts/definitions/troubleshoot-entity.prompt.d.ts

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

package/dist/mcp-server/prompts/definitions/troubleshoot-entity.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"troubleshoot-entity.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/troubleshoot-entity.prompt.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAEjE,eAAO,MAAM,wBAAwB,EAAE,MAiBtC,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAgKlF"}

package/dist/mcp-server/prompts/definitions/troubleshoot-entity.prompt.js

@@ -0,0 +1,177 @@
+export const troubleshootEntityPrompt = {
+    name: "gads_troubleshoot_entity",
+    description: "Step-by-step diagnostic workflow for troubleshooting Google Ads entity errors and common issues",
+    arguments: [
+        {
+            name: "entityType",
+            description: "Entity type to troubleshoot (campaign, adGroup, ad, keyword, campaignBudget, asset)",
+            required: false,
+        },
+        {
+            name: "errorMessage",
+            description: "The error message or symptom you are investigating",
+            required: false,
+        },
+    ],
+};
+export function getTroubleshootEntityMessage(args) {
+    const entityType = args?.entityType || "{entityType}";
+    const errorMessage = args?.errorMessage || "(not specified)";
+    return `# Google Ads Entity Troubleshooting
+
+## Context
+- Entity Type: \`${entityType}\`
+- Reported Error: ${errorMessage}
+- Platform: Google Ads API v23
+
+---
+
+## Step 1: Verify the Entity Exists
+
+\`\`\`
+Tool: gads_get_entity
+Input: { "entityType": "${entityType}", "customerId": "{customerId}", "entityId": "{entityId}" }
+\`\`\`
+
+**Check**: Does the entity exist? What is its current status?
+
+If the entity is not found, check:
+- Is the \`customerId\` correct (no dashes, 10 digits)?
+- For composite IDs (\`ad\`, \`keyword\`): is the format \`{adGroupId}~{criterionId}\`?
+- Was the entity already removed?
+
+---
+
+## Step 2: Check Parent References
+
+Google Ads entities form a strict hierarchy. Verify each parent exists:
+
+| Entity | Parent | How to Check |
+|--------|--------|-------------|
+| \`campaign\` | \`campaignBudget\` | Budget resource name must exist |
+| \`adGroup\` | \`campaign\` | Campaign resource name must exist |
+| \`ad\` | \`adGroup\` | Ad group resource name must exist |
+| \`keyword\` | \`adGroup\` | Ad group resource name must exist |
+| \`asset\` | _(standalone)_ | No parent required |
+
+Use GAQL to verify:
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "{customerId}",
+  "query": "SELECT campaign.id, campaign.status FROM campaign WHERE campaign.id = {campaignId}"
+}
+\`\`\`
+
+---
+
+## Step 3: Inspect Status Chain
+
+An entity can only serve if its **entire hierarchy** is ENABLED:
+
+\`\`\`
+campaignBudget (has sufficient amount)
+  └── campaign (ENABLED)
+       └── adGroup (ENABLED)
+            ├── ad (ENABLED, approved)
+            └── keyword (ENABLED, approved)
+\`\`\`
+
+Use GAQL to check the full chain:
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "{customerId}",
+  "query": "SELECT campaign.status, ad_group.status, ad_group_ad.status, ad_group_ad.ad.type FROM ad_group_ad WHERE campaign.id = {campaignId} LIMIT 10"
+}
+\`\`\`
+
+---
+
+## Step 4: Check Field Values and Constraints
+
+### Common Field Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| \`MUTATE_ERROR_CAMPAIGN_BUDGET_NOT_FOUND\` | Budget resource name doesn't exist | Create the budget first, then reference it |
+| \`FIELD_MASK_ERROR_FIELD_NOT_FOUND\` | Invalid field in \`updateMask\` | Check \`entity-schema://${entityType}\` for valid fields |
+| \`FIELD_ERROR_IMMUTABLE_FIELD\` | Trying to change an immutable field | \`advertisingChannelType\`, \`type\` cannot be changed after creation |
+| \`VALUE_ERROR_MICROS_TOO_SMALL\` | Bid or budget is below minimum | Minimum CPC is usually $0.01 (10000 micros) |
+| \`AD_ERROR_INVALID_HEADLINE\` | Headline too long or contains invalid chars | Max 30 chars, no exclamation marks in headlines |
+| \`KEYWORD_ERROR_DUPLICATE_KEYWORD\` | Same keyword+match type already exists | Check existing keywords with \`gads_list_entities\` |
+| \`RESOURCE_NOT_FOUND\` | Entity was removed or never existed | Check \`entityId\` and \`customerId\` |
+
+---
+
+## Step 5: Validate Resource Names
+
+Google Ads uses full resource name paths. Common format errors:
+
+| Format | Example | Notes |
+|--------|---------|-------|
+| Campaign | \`customers/1234567890/campaigns/111222333\` | 10-digit customer ID, no dashes |
+| Ad Group | \`customers/1234567890/adGroups/444555666\` | camelCase \`adGroups\` |
+| Budget | \`customers/1234567890/campaignBudgets/777888999\` | camelCase \`campaignBudgets\` |
+| Ad (composite) | \`{adGroupId}~{adId}\` | Tilde separator for get/update |
+| Keyword (composite) | \`{adGroupId}~{criterionId}\` | Tilde separator for get/update |
+
+---
+
+## Step 6: Common Error Resolution Patterns
+
+### "Budget not found" when creating campaign
+1. Create budget: \`gads_create_entity\` with \`entityType: "campaignBudget"\`
+2. Note the returned resource name
+3. Use that resource name in the campaign's \`campaignBudget\` field
+
+### "Entity cannot be modified" (REMOVED status)
+- Removed entities cannot be updated — create a new one instead
+- REMOVED is permanent in Google Ads
+
+### "Field mask required"
+- \`gads_update_entity\` requires \`updateMask\` — a comma-separated list of fields being changed
+- Example: \`"updateMask": "status,name"\`
+
+### "Invalid customer ID"
+- Customer ID must be 10 digits with no dashes
+- Use \`gads_list_accounts\` to find correct IDs
+- If using a manager account, set \`loginCustomerId\` in headers
+
+### GAQL query errors
+- Use \`gaql-reference://syntax\` resource for syntax reference
+- Common issue: single quotes around string values are required
+- Date format: \`'YYYY-MM-DD'\`
+
+---
+
+## Quick Diagnostic GAQL Queries
+
+### Check campaign status and budget
+\`\`\`sql
+SELECT campaign.name, campaign.status, campaign_budget.amount_micros
+FROM campaign WHERE campaign.id = {campaignId}
+\`\`\`
+
+### Find disapproved ads
+\`\`\`sql
+SELECT ad_group_ad.ad.id, ad_group_ad.policy_summary.approval_status
+FROM ad_group_ad WHERE ad_group_ad.policy_summary.approval_status != 'APPROVED'
+\`\`\`
+
+### Check keyword quality scores
+\`\`\`sql
+SELECT ad_group_criterion.keyword.text, ad_group_criterion.quality_info.quality_score
+FROM keyword_view WHERE campaign.id = {campaignId}
+\`\`\`
+
+---
+
+## Related Resources
+- \`entity-schema://${entityType}\` — Full field reference
+- \`entity-examples://${entityType}\` — Example payloads
+- \`entity-hierarchy://gads\` — Entity relationships
+- \`gaql-reference://syntax\` — GAQL query syntax
+`;
+}
+//# sourceMappingURL=troubleshoot-entity.prompt.js.map

package/dist/mcp-server/prompts/definitions/troubleshoot-entity.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"troubleshoot-entity.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/troubleshoot-entity.prompt.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,wBAAwB,GAAW;IAC9C,IAAI,EAAE,0BAA0B;IAChC,WAAW,EACT,iGAAiG;IACnG,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EACT,qFAAqF;YACvF,QAAQ,EAAE,KAAK;SAChB;QACD;YACE,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,oDAAoD;YACjE,QAAQ,EAAE,KAAK;SAChB;KACF;CACF,CAAC;AAEF,MAAM,UAAU,4BAA4B,CAAC,IAA6B;IACxE,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACtD,MAAM,YAAY,GAAG,IAAI,EAAE,YAAY,IAAI,iBAAiB,CAAC;IAE7D,OAAO;;;mBAGU,UAAU;oBACT,YAAY;;;;;;;;;0BASN,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qGAiEiE,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAyEzF,UAAU;wBACR,UAAU;;;CAGjC,CAAC;AACF,CAAC"}

package/dist/mcp-server/prompts/index.d.ts

@@ -0,0 +1,9 @@
+import type { Prompt } from "@modelcontextprotocol/sdk/types.js";
+export interface PromptDefinition {
+    prompt: Prompt;
+    generateMessage: (args?: Record<string, string>) => string;
+}
+export declare const promptRegistry: Map<string, PromptDefinition>;
+export declare function getAllPrompts(): Prompt[];
+export declare function getPromptDefinition(name: string): PromptDefinition | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/prompts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/prompts/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AA8CjE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC;CAC5D;AAED,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CA8EvD,CAAC;AAEH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE9E"}

package/dist/mcp-server/prompts/index.js

@@ -0,0 +1,97 @@
+import { campaignSetupWorkflowPrompt, getCampaignSetupWorkflowMessage, } from "./definitions/campaign-setup-workflow.prompt.js";
+import { toolSchemaExplorationPrompt, getToolSchemaExplorationMessage, } from "./definitions/tool-schema-exploration.prompt.js";
+import { troubleshootEntityPrompt, getTroubleshootEntityMessage, } from "./definitions/troubleshoot-entity.prompt.js";
+import { gaqlReportingWorkflowPrompt, getGaqlReportingWorkflowMessage, } from "./definitions/gaql-reporting-workflow.prompt.js";
+import { crossPlatformPerformancePrompt, getCrossPlatformPerformanceMessage, } from "./definitions/cross-platform-performance.prompt.js";
+import { bulkOperationsWorkflowPrompt, getBulkOperationsWorkflowMessage, } from "./definitions/bulk-operations-workflow.prompt.js";
+import { crossPlatformCampaignSetupPrompt, getCrossPlatformCampaignSetupMessage, } from "./definitions/cross-platform-campaign-setup.prompt.js";
+import { entityUpdateWorkflowPrompt, getEntityUpdateWorkflowMessage, } from "./definitions/entity-update-workflow.prompt.js";
+import { entityDuplicationWorkflowPrompt, getEntityDuplicationWorkflowMessage, } from "./definitions/entity-duplication-workflow.prompt.js";
+import { targetingDiscoveryWorkflowPrompt, getTargetingDiscoveryWorkflowMessage, } from "./definitions/targeting-discovery-workflow.prompt.js";
+import { gadsCreativeSetupWorkflowPrompt, getGadsCreativeSetupWorkflowMessage, } from "./definitions/creative-setup-workflow.prompt.js";
+export const promptRegistry = new Map([
+    [
+        campaignSetupWorkflowPrompt.name,
+        {
+            prompt: campaignSetupWorkflowPrompt,
+            generateMessage: getCampaignSetupWorkflowMessage,
+        },
+    ],
+    [
+        toolSchemaExplorationPrompt.name,
+        {
+            prompt: toolSchemaExplorationPrompt,
+            generateMessage: getToolSchemaExplorationMessage,
+        },
+    ],
+    [
+        troubleshootEntityPrompt.name,
+        {
+            prompt: troubleshootEntityPrompt,
+            generateMessage: getTroubleshootEntityMessage,
+        },
+    ],
+    [
+        gaqlReportingWorkflowPrompt.name,
+        {
+            prompt: gaqlReportingWorkflowPrompt,
+            generateMessage: getGaqlReportingWorkflowMessage,
+        },
+    ],
+    [
+        crossPlatformPerformancePrompt.name,
+        {
+            prompt: crossPlatformPerformancePrompt,
+            generateMessage: getCrossPlatformPerformanceMessage,
+        },
+    ],
+    [
+        bulkOperationsWorkflowPrompt.name,
+        {
+            prompt: bulkOperationsWorkflowPrompt,
+            generateMessage: getBulkOperationsWorkflowMessage,
+        },
+    ],
+    [
+        crossPlatformCampaignSetupPrompt.name,
+        {
+            prompt: crossPlatformCampaignSetupPrompt,
+            generateMessage: getCrossPlatformCampaignSetupMessage,
+        },
+    ],
+    [
+        entityUpdateWorkflowPrompt.name,
+        {
+            prompt: entityUpdateWorkflowPrompt,
+            generateMessage: getEntityUpdateWorkflowMessage,
+        },
+    ],
+    [
+        entityDuplicationWorkflowPrompt.name,
+        {
+            prompt: entityDuplicationWorkflowPrompt,
+            generateMessage: getEntityDuplicationWorkflowMessage,
+        },
+    ],
+    [
+        targetingDiscoveryWorkflowPrompt.name,
+        {
+            prompt: targetingDiscoveryWorkflowPrompt,
+            generateMessage: getTargetingDiscoveryWorkflowMessage,
+        },
+    ],
+    [
+        gadsCreativeSetupWorkflowPrompt.name,
+        {
+            prompt: gadsCreativeSetupWorkflowPrompt,
+            generateMessage: getGadsCreativeSetupWorkflowMessage,
+        },
+    ],
+]);
+export function getAllPrompts() {
+    return Array.from(promptRegistry.values()).map((def) => def.prompt);
+}
+export function getPromptDefinition(name) {
+    return promptRegistry.get(name);
+}
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/prompts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp-server/prompts/index.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,iDAAiD,CAAC;AACzD,OAAO,EACL,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,iDAAiD,CAAC;AACzD,OAAO,EACL,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EACL,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,iDAAiD,CAAC;AACzD,OAAO,EACL,8BAA8B,EAC9B,kCAAkC,GACnC,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EACL,4BAA4B,EAC5B,gCAAgC,GACjC,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EACL,gCAAgC,EAChC,oCAAoC,GACrC,MAAM,uDAAuD,CAAC;AAC/D,OAAO,EACL,0BAA0B,EAC1B,8BAA8B,GAC/B,MAAM,gDAAgD,CAAC;AACxD,OAAO,EACL,+BAA+B,EAC/B,mCAAmC,GACpC,MAAM,qDAAqD,CAAC;AAC7D,OAAO,EACL,gCAAgC,EAChC,oCAAoC,GACrC,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EACL,+BAA+B,EAC/B,mCAAmC,GACpC,MAAM,iDAAiD,CAAC;AAOzD,MAAM,CAAC,MAAM,cAAc,GAAkC,IAAI,GAAG,CAAC;IACnE;QACE,2BAA2B,CAAC,IAAI;QAChC;YACE,MAAM,EAAE,2BAA2B;YACnC,eAAe,EAAE,+BAA+B;SACjD;KACF;IACD;QACE,2BAA2B,CAAC,IAAI;QAChC;YACE,MAAM,EAAE,2BAA2B;YACnC,eAAe,EAAE,+BAA+B;SACjD;KACF;IACD;QACE,wBAAwB,CAAC,IAAI;QAC7B;YACE,MAAM,EAAE,wBAAwB;YAChC,eAAe,EAAE,4BAA4B;SAC9C;KACF;IACD;QACE,2BAA2B,CAAC,IAAI;QAChC;YACE,MAAM,EAAE,2BAA2B;YACnC,eAAe,EAAE,+BAA+B;SACjD;KACF;IACD;QACE,8BAA8B,CAAC,IAAI;QACnC;YACE,MAAM,EAAE,8BAA8B;YACtC,eAAe,EAAE,kCAAkC;SACpD;KACF;IACD;QACE,4BAA4B,CAAC,IAAI;QACjC;YACE,MAAM,EAAE,4BAA4B;YACpC,eAAe,EAAE,gCAAgC;SAClD;KACF;IACD;QACE,gCAAgC,CAAC,IAAI;QACrC;YACE,MAAM,EAAE,gCAAgC;YACxC,eAAe,EAAE,oCAAoC;SACtD;KACF;IACD;QACE,0BAA0B,CAAC,IAAI;QAC/B;YACE,MAAM,EAAE,0BAA0B;YAClC,eAAe,EAAE,8BAA8B;SAChD;KACF;IACD;QACE,+BAA+B,CAAC,IAAI;QACpC;YACE,MAAM,EAAE,+BAA+B;YACvC,eAAe,EAAE,mCAAmC;SACrD;KACF;IACD;QACE,gCAAgC,CAAC,IAAI;QACrC;YACE,MAAM,EAAE,gCAAgC;YACxC,eAAe,EAAE,oCAAoC;SACtD;KACF;IACD;QACE,+BAA+B,CAAC,IAAI;QACpC;YACE,MAAM,EAAE,+BAA+B;YACvC,eAAe,EAAE,mCAAmC;SACrD;KACF;CACF,CAAC,CAAC;AAEH,MAAM,UAAU,aAAa;IAC3B,OAAO,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}