@cesteral/gads-mcp 1.0.0

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

@@ -0,0 +1,221 @@
+export const entityDuplicationWorkflowPrompt = {
+    name: "gads_entity_duplication_workflow",
+    description: "Step-by-step guide for duplicating Google Ads entities (campaigns, adGroups, ads, keywords) using the get-then-create pattern. Covers field stripping, naming conventions, and budget handling.",
+    arguments: [
+        {
+            name: "customerId",
+            description: "Google Ads customer ID (no dashes)",
+            required: true,
+        },
+        {
+            name: "entityType",
+            description: "Entity type to duplicate: campaign, adGroup, ad, or keyword",
+            required: true,
+        },
+        {
+            name: "sourceEntityId",
+            description: "ID of the source entity to copy from",
+            required: true,
+        },
+    ],
+};
+export function getEntityDuplicationWorkflowMessage(args) {
+    const customerId = args?.customerId || "{customerId}";
+    const entityType = args?.entityType || "{entityType}";
+    const sourceEntityId = args?.sourceEntityId || "{sourceEntityId}";
+    return `# Google Ads Entity Duplication Workflow
+
+## Context
+- Customer ID: \`${customerId}\`
+- Entity Type: \`${entityType}\`
+- Source Entity ID: \`${sourceEntityId}\`
+- Platform: Google Ads API v23
+
+Google Ads has no native "duplicate" endpoint. Duplication is done by reading the source entity and creating a new one with adjusted fields.
+
+---
+
+## Step 1: Fetch the Source Entity
+
+Retrieve the full source entity using GAQL to get all relevant fields:
+
+\`\`\`
+Tool: gads_get_entity
+Input: {
+  "entityType": "${entityType}",
+  "customerId": "${customerId}",
+  "entityId": "${sourceEntityId}"
+}
+\`\`\`
+
+**Save the full response** — you will use it as the template for the new entity.
+
+---
+
+## Step 2: Strip Immutable and ID Fields
+
+Before creating the copy, remove the following fields from the response:
+- \`id\` — auto-assigned by the API
+- \`resource_name\` — auto-assigned by the API
+- \`status\` — set explicitly to \`PAUSED\` for safety
+
+### Fields to strip by entity type
+
+| Entity Type | Fields to Remove |
+|-------------|-----------------|
+| campaign | \`id\`, \`resource_name\`, \`campaign_budget\` (recreate separately) |
+| adGroup | \`id\`, \`resource_name\` |
+| ad | \`id\`, \`resource_name\`, \`ad.id\` |
+| keyword | \`id\`, \`resource_name\` |
+
+---
+
+## Step 3: Adjust Name and Settings
+
+Update the \`name\` to distinguish the copy from the original. Common conventions:
+- Append " — Copy" (e.g., \`"Q1 Search Campaign — Copy"\`)
+- Append a date or variant label (e.g., \`"Q1 Search Campaign — Q2"\`)
+
+Set \`status\` to \`"PAUSED"\` initially — enable after verifying the copy is correct.
+
+---
+
+## Step 4: Handle Campaign Budget (Campaign Duplication Only)
+
+⚠️ **GOTCHA**: Campaigns cannot share a \`campaignBudget\` resource directly — each campaign needs its own budget resource or should link to an existing shared budget.
+
+If duplicating a **campaign**, first create a new budget:
+
+\`\`\`
+Tool: gads_create_entity
+Input: {
+  "entityType": "campaignBudget",
+  "customerId": "${customerId}",
+  "data": {
+    "name": "Q2 Search Campaign Budget — Copy",
+    "amountMicros": "{original amountMicros}",
+    "deliveryMethod": "STANDARD"
+  }
+}
+\`\`\`
+
+Save the returned resource name — you will reference it in the campaign creation step.
+
+---
+
+## Step 5: Create the Duplicate
+
+Create the new entity with the cleaned payload:
+
+### Duplicate a Campaign
+\`\`\`
+Tool: gads_create_entity
+Input: {
+  "entityType": "campaign",
+  "customerId": "${customerId}",
+  "data": {
+    "name": "{original name} — Copy",
+    "advertisingChannelType": "{original advertisingChannelType}",
+    "status": "PAUSED",
+    "campaignBudget": "customers/${customerId}/campaignBudgets/{newBudgetId}",
+    "startDate": "{desired start date}",
+    "networkSettings": "{original networkSettings}",
+    "biddingStrategyType": "{original biddingStrategyType}"
+  }
+}
+\`\`\`
+
+### Duplicate an Ad Group
+\`\`\`
+Tool: gads_create_entity
+Input: {
+  "entityType": "adGroup",
+  "customerId": "${customerId}",
+  "data": {
+    "name": "{original name} — Copy",
+    "campaign": "customers/${customerId}/campaigns/{targetCampaignId}",
+    "status": "PAUSED",
+    "type": "{original type}",
+    "cpcBidMicros": "{original cpcBidMicros}"
+  }
+}
+\`\`\`
+
+### Duplicate an Ad
+\`\`\`
+Tool: gads_create_entity
+Input: {
+  "entityType": "ad",
+  "customerId": "${customerId}",
+  "data": {
+    "adGroup": "customers/${customerId}/adGroups/{targetAdGroupId}",
+    "status": "PAUSED",
+    "ad": {
+      "responsiveSearchAd": {
+        "headlines": "{original headlines}",
+        "descriptions": "{original descriptions}"
+      },
+      "finalUrls": "{original finalUrls}"
+    }
+  }
+}
+\`\`\`
+
+---
+
+## Step 6: Duplicate Child Entities (if needed)
+
+When duplicating a campaign or ad group, you may also want to copy its children:
+
+1. **Campaign → Ad Groups**: List all ad groups under the source campaign, then duplicate each
+2. **Ad Group → Ads**: List all ads under the source ad group, then duplicate each
+3. **Ad Group → Keywords**: List all keywords under the source ad group, then duplicate each
+
+\`\`\`
+Tool: gads_list_entities
+Input: {
+  "entityType": "adGroup",
+  "customerId": "${customerId}",
+  "filters": {
+    "ad_group.campaign": "= 'customers/${customerId}/campaigns/${sourceEntityId}'"
+  }
+}
+\`\`\`
+
+---
+
+## Step 7: Verify the Duplicate
+
+Confirm the new entity was created correctly:
+
+\`\`\`
+Tool: gads_list_entities
+Input: {
+  "entityType": "${entityType}",
+  "customerId": "${customerId}"
+}
+\`\`\`
+
+Review the new entity's name, status, and settings. Enable it when satisfied.
+
+---
+
+## Success Checklist
+
+- [ ] Source entity fetched and saved
+- [ ] ID/resource_name fields stripped from template
+- [ ] Name updated to distinguish copy from original
+- [ ] Status set to PAUSED for initial creation
+- [ ] For campaigns: new budget created separately and linked
+- [ ] New entity created via \`gads_create_entity\`
+- [ ] Child entities duplicated if needed (ad groups, ads, keywords)
+- [ ] Duplicate verified via \`gads_list_entities\`
+- [ ] Duplicate enabled when ready
+
+## Related Resources
+- \`entity-schema://${entityType}\` — Full field reference for this entity type
+- \`entity-hierarchy://gads\` — Entity parent-child relationships
+- \`entity-examples://${entityType}\` — Example create payloads
+`;
+}
+//# sourceMappingURL=entity-duplication-workflow.prompt.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity-duplication-workflow.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/entity-duplication-workflow.prompt.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,+BAA+B,GAAW;IACrD,IAAI,EAAE,kCAAkC;IACxC,WAAW,EACT,iMAAiM;IACnM,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,oCAAoC;YACjD,QAAQ,EAAE,IAAI;SACf;QACD;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,6DAA6D;YAC1E,QAAQ,EAAE,IAAI;SACf;QACD;YACE,IAAI,EAAE,gBAAgB;YACtB,WAAW,EAAE,sCAAsC;YACnD,QAAQ,EAAE,IAAI;SACf;KACF;CACF,CAAC;AAEF,MAAM,UAAU,mCAAmC,CAAC,IAA6B;IAC/E,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACtD,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACtD,MAAM,cAAc,GAAG,IAAI,EAAE,cAAc,IAAI,kBAAkB,CAAC;IAElE,OAAO;;;mBAGU,UAAU;mBACV,UAAU;wBACL,cAAc;;;;;;;;;;;;;;mBAcnB,UAAU;mBACV,UAAU;iBACZ,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBA8CZ,UAAU;;;;;;;;;;;;;;;;;;;;;;mBAsBV,UAAU;;;;;mCAKM,UAAU;;;;;;;;;;;;;mBAa1B,UAAU;;;6BAGA,UAAU;;;;;;;;;;;;;mBAapB,UAAU;;4BAED,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;mBA2BnB,UAAU;;yCAEY,UAAU,cAAc,cAAc;;;;;;;;;;;;;;mBAc5D,UAAU;mBACV,UAAU;;;;;;;;;;;;;;;;;;;;;sBAqBP,UAAU;;wBAER,UAAU;CACjC,CAAC;AACF,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity-update-workflow.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/entity-update-workflow.prompt.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAEjE,eAAO,MAAM,0BAA0B,EAAE,MAsBxC,CAAC;AAEF,wBAAgB,8BAA8B,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAyLpF"}

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

@@ -0,0 +1,207 @@
+export const entityUpdateWorkflowPrompt = {
+    name: "gads_entity_update_workflow",
+    description: "Step-by-step guide for safely updating Google Ads entities. Covers the read-then-update pattern with explicit updateMask for campaigns, adGroups, ads, keywords, campaignBudgets, and assets.",
+    arguments: [
+        {
+            name: "customerId",
+            description: "Google Ads customer ID (no dashes)",
+            required: true,
+        },
+        {
+            name: "entityType",
+            description: "Entity type to update: campaign, adGroup, ad, keyword, campaignBudget, or asset",
+            required: true,
+        },
+        {
+            name: "entityId",
+            description: "Google Ads entity ID to update",
+            required: true,
+        },
+    ],
+};
+export function getEntityUpdateWorkflowMessage(args) {
+    const customerId = args?.customerId || "{customerId}";
+    const entityType = args?.entityType || "{entityType}";
+    const entityId = args?.entityId || "{entityId}";
+    return `# Google Ads Entity Update Workflow
+
+## Context
+- Customer ID: \`${customerId}\`
+- Entity Type: \`${entityType}\`
+- Entity ID: \`${entityId}\`
+- Platform: Google Ads API v23
+
+---
+
+## ⚠️ Critical: Always Use updateMask
+
+Google Ads uses **partial updates via updateMask**. The \`updateMask\` field is a comma-separated list of field paths to update. Only the listed fields are modified — all other fields are left untouched.
+
+**Without updateMask**: The API may reject the request or update unexpected fields.
+**With updateMask**: Only the specified fields are written; all others remain as-is.
+
+---
+
+## Step 1: Read Current State
+
+Fetch the entity before modifying it to understand its current configuration.
+
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT ${entityType}.id, ${entityType}.name, ${entityType}.status, ${entityType}.resource_name FROM ${entityType} WHERE ${entityType}.id = ${entityId}"
+}
+\`\`\`
+
+**Save the response** — particularly the \`resource_name\`, which is required for the update call.
+
+> Resource name format: \`customers/${customerId}/${entityType}s/${entityId}\`
+
+---
+
+## Step 2: Build Your Update Payload
+
+Only include the fields you want to change. The \`updateMask\` must list every field path you are setting in \`data\`.
+
+### Campaign — Pause a Campaign
+\`\`\`
+Tool: gads_update_entity
+Input: {
+  "entityType": "campaign",
+  "customerId": "${customerId}",
+  "entityId": "${entityId}",
+  "data": {
+    "status": "PAUSED"
+  },
+  "updateMask": "status"
+}
+\`\`\`
+
+### Campaign — Update Name and End Date
+\`\`\`
+Tool: gads_update_entity
+Input: {
+  "entityType": "campaign",
+  "customerId": "${customerId}",
+  "entityId": "${entityId}",
+  "data": {
+    "name": "Q2 Search Campaign — Revised",
+    "endDate": "2025-06-30"
+  },
+  "updateMask": "name,end_date"
+}
+\`\`\`
+
+### Ad Group — Update Default CPC Bid
+\`\`\`
+Tool: gads_update_entity
+Input: {
+  "entityType": "adGroup",
+  "customerId": "${customerId}",
+  "entityId": "${entityId}",
+  "data": {
+    "cpcBidMicros": "3500000"
+  },
+  "updateMask": "cpc_bid_micros"
+}
+\`\`\`
+
+### Campaign Budget — Increase Daily Budget
+\`\`\`
+Tool: gads_update_entity
+Input: {
+  "entityType": "campaignBudget",
+  "customerId": "${customerId}",
+  "entityId": "${entityId}",
+  "data": {
+    "amountMicros": "75000000"
+  },
+  "updateMask": "amount_micros"
+}
+\`\`\`
+
+### Keyword — Update Bid and Status
+\`\`\`
+Tool: gads_update_entity
+Input: {
+  "entityType": "keyword",
+  "customerId": "${customerId}",
+  "entityId": "${entityId}",
+  "data": {
+    "status": "ENABLED",
+    "cpcBidMicros": "4000000"
+  },
+  "updateMask": "status,cpc_bid_micros"
+}
+\`\`\`
+
+---
+
+## Step 3: Execute the Update
+
+Call \`gads_update_entity\` with your payload and updateMask. Review the response for field-level errors.
+
+---
+
+## Step 4: Verify the Change
+
+Confirm the update was applied:
+
+\`\`\`
+Tool: gads_get_entity
+Input: {
+  "entityType": "${entityType}",
+  "customerId": "${customerId}",
+  "entityId": "${entityId}"
+}
+\`\`\`
+
+Compare the returned values with what you set in Step 2.
+
+---
+
+## Gotchas
+
+- **updateMask field naming**: Use snake_case for updateMask paths (e.g., \`cpc_bid_micros\`, not \`cpcBidMicros\`). The \`data\` payload uses camelCase.
+- **Resource name vs ID**: The API identifies entities by \`resource_name\` internally. Always verify the entity exists before updating.
+- **Budget is shared**: \`campaignBudget.amountMicros\` is the daily budget, shared across all campaigns linked to it. Changing it affects all linked campaigns.
+- **advertisingChannelType**: Cannot be changed after campaign creation.
+- **Ad updates**: Most ad fields are immutable after creation. To change ad copy, create a new ad and pause/remove the old one.
+- **Bulk status changes**: For pausing/enabling multiple entities, prefer \`gads_bulk_update_status\` over individual update calls.
+- **Bid adjustments**: For batch bid changes across multiple ad groups, use \`gads_adjust_bids\` — it handles read-modify-write safely.
+
+---
+
+## Common updateMask Field Paths
+
+| Entity | Field | updateMask Path |
+|--------|-------|-----------------|
+| campaign | status | \`status\` |
+| campaign | name | \`name\` |
+| campaign | end date | \`end_date\` |
+| campaign | budget | \`campaign_budget\` |
+| adGroup | status | \`status\` |
+| adGroup | CPC bid | \`cpc_bid_micros\` |
+| adGroup | name | \`name\` |
+| campaignBudget | daily amount | \`amount_micros\` |
+| keyword | status | \`status\` |
+| keyword | CPC bid | \`cpc_bid_micros\` |
+
+---
+
+## Success Checklist
+
+- [ ] Current entity state read via \`gads_gaql_search\` or \`gads_get_entity\`
+- [ ] Update payload built with only the fields being changed
+- [ ] \`updateMask\` set to comma-separated snake_case field paths
+- [ ] \`gads_update_entity\` called and returned success
+- [ ] Change verified by re-fetching the entity
+
+## Related Resources
+- \`entity-schema://${entityType}\` — Full field reference for this entity type
+- \`entity-hierarchy://gads\` — Entity relationships and resource name patterns
+- \`gaql-reference://syntax\` — GAQL query syntax for reading current state
+`;
+}
+//# sourceMappingURL=entity-update-workflow.prompt.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity-update-workflow.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/entity-update-workflow.prompt.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,0BAA0B,GAAW;IAChD,IAAI,EAAE,6BAA6B;IACnC,WAAW,EACT,+LAA+L;IACjM,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,oCAAoC;YACjD,QAAQ,EAAE,IAAI;SACf;QACD;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EACT,iFAAiF;YACnF,QAAQ,EAAE,IAAI;SACf;QACD;YACE,IAAI,EAAE,UAAU;YAChB,WAAW,EAAE,gCAAgC;YAC7C,QAAQ,EAAE,IAAI;SACf;KACF;CACF,CAAC;AAEF,MAAM,UAAU,8BAA8B,CAAC,IAA6B;IAC1E,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACtD,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,YAAY,CAAC;IAEhD,OAAO;;;mBAGU,UAAU;mBACV,UAAU;iBACZ,QAAQ;;;;;;;;;;;;;;;;;;;;;mBAqBN,UAAU;qBACR,UAAU,QAAQ,UAAU,UAAU,UAAU,YAAY,UAAU,uBAAuB,UAAU,UAAU,UAAU,SAAS,QAAQ;;;;;;sCAM3H,UAAU,IAAI,UAAU,KAAK,QAAQ;;;;;;;;;;;;;mBAaxD,UAAU;iBACZ,QAAQ;;;;;;;;;;;;;mBAaN,UAAU;iBACZ,QAAQ;;;;;;;;;;;;;;mBAcN,UAAU;iBACZ,QAAQ;;;;;;;;;;;;;mBAaN,UAAU;iBACZ,QAAQ;;;;;;;;;;;;;mBAaN,UAAU;iBACZ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;mBAwBN,UAAU;mBACV,UAAU;iBACZ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA8CH,UAAU;;;CAG/B,CAAC;AACF,CAAC"}

package/dist/mcp-server/prompts/definitions/gaql-reporting-workflow.prompt.d.ts

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

package/dist/mcp-server/prompts/definitions/gaql-reporting-workflow.prompt.d.ts.map

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

package/dist/mcp-server/prompts/definitions/gaql-reporting-workflow.prompt.js

@@ -0,0 +1,182 @@
+export const gaqlReportingWorkflowPrompt = {
+    name: "gaql_reporting_workflow",
+    description: "Step-by-step workflow for querying Google Ads performance data via GAQL, including common query patterns, field selection, and filtering",
+    arguments: [
+        {
+            name: "customerId",
+            description: "Google Ads Customer ID (without hyphens, e.g. 1234567890)",
+            required: true,
+        },
+    ],
+};
+export function getGaqlReportingWorkflowMessage(args) {
+    const customerId = args?.customerId || "{customerId}";
+    return `# GAQL Reporting Workflow
+
+## Context
+- Customer ID: \`${customerId}\`
+- Query Language: GAQL (Google Ads Query Language)
+- Tool: \`gads_gaql_search\`
+
+GAQL queries are synchronous — results are returned directly in the response. Use the \`gads_gaql_search\` tool to execute any GAQL query.
+
+---
+
+## Step 1: Choose Your Report Goal
+
+Before writing a query, decide what question you're answering:
+
+| Goal | Resource | Key Fields |
+|------|----------|------------|
+| Campaign overview | \`campaign\` | \`campaign.name\`, \`campaign.status\`, \`metrics.impressions\`, \`metrics.clicks\`, \`metrics.cost_micros\` |
+| Ad group performance | \`ad_group\` | \`ad_group.name\`, \`ad_group.status\`, \`metrics.impressions\`, \`metrics.ctr\`, \`metrics.average_cpc\` |
+| Keyword analysis | \`keyword_view\` | \`ad_group_criterion.keyword.text\`, \`ad_group_criterion.keyword.match_type\`, \`metrics.impressions\`, \`metrics.conversions\` |
+| Search terms | \`search_term_view\` | \`search_term_view.search_term\`, \`metrics.impressions\`, \`metrics.clicks\`, \`metrics.conversions\` |
+| Device breakdown | \`campaign\` | \`segments.device\`, \`metrics.impressions\`, \`metrics.clicks\`, \`metrics.cost_micros\` |
+| Daily trend | \`campaign\` | \`segments.date\`, \`metrics.impressions\`, \`metrics.cost_micros\` |
+| Conversion tracking | \`campaign\` | \`metrics.conversions\`, \`metrics.conversions_value\`, \`metrics.cost_per_conversion\` |
+| Budget utilization | \`campaign_budget\` | \`campaign_budget.amount_micros\`, \`campaign_budget.total_amount_micros\`, \`metrics.cost_micros\` |
+
+---
+
+## Step 2: Write the GAQL Query
+
+### Query Structure
+\`\`\`sql
+SELECT
+  resource.field1,
+  resource.field2,
+  metrics.metric1,
+  segments.segment1
+FROM resource
+WHERE condition1
+  AND condition2
+ORDER BY metrics.metric1 DESC
+LIMIT 100
+\`\`\`
+
+### Important GAQL Rules
+- **No \`*\` wildcard** — you must list each field explicitly
+- **Segments create row breakdowns** — adding \`segments.date\` gives one row per day per entity
+- **Metrics are auto-aggregated** — \`metrics.cost_micros\` sums over the date range by default
+- **cost_micros** — all monetary values are in micros (divide by 1,000,000 for actual currency)
+- **Date filtering** — use \`segments.date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'\`
+
+---
+
+## Step 3: Run the Query
+
+\`\`\`
+Tool: gads_gaql_search
+Input: {
+  "customerId": "${customerId}",
+  "query": "SELECT campaign.name, campaign.status, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.ctr FROM campaign WHERE campaign.status = 'ENABLED' AND segments.date DURING LAST_7_DAYS ORDER BY metrics.impressions DESC"
+}
+\`\`\`
+
+---
+
+## Step 4: Interpret Results
+
+- \`metrics.cost_micros\` ÷ 1,000,000 = actual cost in account currency
+- \`metrics.ctr\` is already a fraction (0.05 = 5%)
+- \`metrics.average_cpc\` is in micros
+- Empty results may mean the date range has no data or filters are too restrictive
+
+---
+
+## Common Query Patterns
+
+### Campaign Performance Summary
+\`\`\`sql
+SELECT
+  campaign.name,
+  campaign.status,
+  metrics.impressions,
+  metrics.clicks,
+  metrics.ctr,
+  metrics.cost_micros,
+  metrics.conversions,
+  metrics.cost_per_conversion
+FROM campaign
+WHERE campaign.status = 'ENABLED'
+  AND segments.date DURING LAST_30_DAYS
+ORDER BY metrics.cost_micros DESC
+\`\`\`
+
+### Daily Spend Trend (for pacing)
+\`\`\`sql
+SELECT
+  segments.date,
+  campaign.name,
+  metrics.cost_micros,
+  metrics.impressions
+FROM campaign
+WHERE campaign.id = {campaignId}
+  AND segments.date DURING LAST_14_DAYS
+ORDER BY segments.date DESC
+\`\`\`
+Compare daily \`cost_micros / 1e6\` against \`campaign_budget.amount_micros / 1e6\`.
+
+### Top Keywords by Conversions
+\`\`\`sql
+SELECT
+  ad_group_criterion.keyword.text,
+  ad_group_criterion.keyword.match_type,
+  metrics.impressions,
+  metrics.clicks,
+  metrics.conversions,
+  metrics.cost_per_conversion
+FROM keyword_view
+WHERE campaign.id = {campaignId}
+  AND segments.date DURING LAST_30_DAYS
+  AND metrics.impressions > 0
+ORDER BY metrics.conversions DESC
+LIMIT 50
+\`\`\`
+
+### Search Terms Report
+\`\`\`sql
+SELECT
+  search_term_view.search_term,
+  campaign.name,
+  metrics.impressions,
+  metrics.clicks,
+  metrics.conversions,
+  metrics.cost_micros
+FROM search_term_view
+WHERE campaign.id = {campaignId}
+  AND segments.date DURING LAST_30_DAYS
+ORDER BY metrics.impressions DESC
+LIMIT 100
+\`\`\`
+
+---
+
+## Date Range Shortcuts
+
+| GAQL Keyword | Meaning |
+|-------------|---------|
+| \`TODAY\` | Current day |
+| \`YESTERDAY\` | Previous day |
+| \`LAST_7_DAYS\` | Past 7 days (not including today) |
+| \`LAST_14_DAYS\` | Past 14 days |
+| \`LAST_30_DAYS\` | Past 30 days |
+| \`THIS_MONTH\` | Current month to date |
+| \`LAST_MONTH\` | Previous full month |
+| \`LAST_BUSINESS_WEEK\` | Mon–Fri of previous week |
+
+For custom ranges: \`segments.date BETWEEN '2025-01-01' AND '2025-01-31'\`
+
+---
+
+## Tips
+
+- Start simple — add fields incrementally to avoid field compatibility errors
+- Some segments can't be combined with certain resources — GAQL will return a clear error
+- Use \`gads_list_entities\` to discover entity IDs before querying with GAQL
+- For large accounts, always add \`LIMIT\` to avoid timeouts
+- Combine with write tools: analyze GAQL results, then use \`gads_update_entity\` to act on insights
+`;
+}
+//# sourceMappingURL=gaql-reporting-workflow.prompt.js.map

package/dist/mcp-server/prompts/definitions/gaql-reporting-workflow.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaql-reporting-workflow.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/gaql-reporting-workflow.prompt.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,2BAA2B,GAAW;IACjD,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EACT,0IAA0I;IAC5I,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,2DAA2D;YACxE,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAuDV,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4G5B,CAAC;AACF,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"targeting-discovery-workflow.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/targeting-discovery-workflow.prompt.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAEjE,eAAO,MAAM,gCAAgC,EAAE,MAgB9C,CAAC;AAEF,wBAAgB,oCAAoC,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CA8M1F"}