@cesteral/gads-mcp 1.0.0

package/dist/mcp-server/resources/definitions/entity-hierarchy.resource.js

@@ -0,0 +1,124 @@
+let cachedContent;
+function formatEntityHierarchyMarkdown() {
+    return `# Google Ads Entity Hierarchy
+
+## Relationship Diagram
+
+\`\`\`
+Customer (Google Ads Account)
+  ├── Campaign Budget (shared or dedicated)
+  ├── Campaign
+  │     ├── Ad Group
+  │     │     ├── Ad (AdGroupAd)
+  │     │     ├── Keyword (AdGroupCriterion)
+  │     │     └── (Targeting criteria)
+  │     └── Campaign-level targeting (locations, languages)
+  └── Asset (reusable text/image/video/sitelink/callout)
+        ├── CampaignAsset (links asset to campaign)
+        └── AdGroupAsset (links asset to ad group)
+\`\`\`
+
+## Entity Types (6 in Phase 1)
+
+| Entity Type | GAQL Resource | Mutate Endpoint | Parent |
+|-------------|--------------|-----------------|--------|
+| **campaign** | \`campaign\` | \`campaigns:mutate\` | customerId |
+| **adGroup** | \`ad_group\` | \`adGroups:mutate\` | customerId + campaign |
+| **ad** | \`ad_group_ad\` | \`adGroupAds:mutate\` | customerId + adGroup |
+| **keyword** | \`ad_group_criterion\` | \`adGroupCriteria:mutate\` | customerId + adGroup |
+| **campaignBudget** | \`campaign_budget\` | \`campaignBudgets:mutate\` | customerId |
+| **asset** | \`asset\` | \`assets:mutate\` | customerId |
+
+## API Patterns
+
+### Reading: GAQL Queries
+All reads use GAQL via \`POST /customers/{customerId}/googleAds:search\`:
+\`\`\`json
+{
+  "query": "SELECT campaign.id, campaign.name FROM campaign WHERE campaign.status = 'ENABLED'"
+}
+\`\`\`
+
+### Writing: :mutate Endpoints
+All writes use \`POST /customers/{customerId}/{resource}:mutate\`:
+\`\`\`json
+{
+  "operations": [
+    { "create": { "name": "My Campaign", ... } },
+    { "update": { "resourceName": "customers/123/campaigns/456", "name": "Updated" }, "updateMask": "name" },
+    { "remove": "customers/123/campaigns/789" }
+  ]
+}
+\`\`\`
+
+### Resource Names
+Every entity has a resource name: \`customers/{customerId}/{entityType}/{entityId}\`
+- Campaign: \`customers/123/campaigns/456\`
+- Ad Group: \`customers/123/adGroups/789\`
+- Campaign Budget: \`customers/123/campaignBudgets/101\`
+- Ad (composite): \`customers/123/adGroupAds/{adGroupId}~{adId}\`
+- Keyword (composite): \`customers/123/adGroupCriteria/{adGroupId}~{criterionId}\`
+- Asset: \`customers/123/assets/202\`
+
+## Creation Order
+
+Full campaign structure (top-down):
+
+1. **List accessible accounts** — \`gads_list_accounts\` to find your customer ID
+2. **Campaign Budget** — create budget first (\`amountMicros\` = daily budget in micros)
+3. **Campaign** — reference budget via \`campaignBudget\` resource name field
+4. **Ad Group(s)** — reference campaign via \`campaign\` resource name field
+5. **Keyword(s)** — reference ad group via \`adGroup\` resource name field
+6. **Ad(s)** — reference ad group via \`adGroup\` resource name field
+7. **Asset(s)** — optional, create then link via CampaignAsset or AdGroupAsset
+
+## Key Differences from Other Platforms
+
+| Feature | Google Ads | DV360 | TTD |
+|---------|-----------|-------|-----|
+| **Budget model** | Separate CampaignBudget entity | Budget in campaign object | Budget in campaign + ad group |
+| **Query language** | GAQL (SQL-like) | REST GET with filters | POST to /query endpoints |
+| **Mutations** | :mutate with operations[] | REST PUT/PATCH | REST POST/PUT |
+| **Update mask** | Required on update | Required on update | Full PUT (no mask) |
+| **Status values** | ENABLED/PAUSED/REMOVED | ACTIVE/PAUSED/DRAFT/ARCHIVED | Available/Paused/Archived |
+| **ID format** | Numeric strings | Numeric strings | Alphanumeric strings |
+| **Currency** | Micros (÷1,000,000) | Standard units | Standard units |
+
+## Deletion / Removal Order
+
+Remove bottom-up to avoid dependency errors:
+
+1. **Keywords** and **Ads** first
+2. **Ad Groups**
+3. **Campaigns**
+4. **Campaign Budgets** (only if not shared)
+5. **Assets** (only if not linked to campaigns/ad groups)
+
+Note: In Google Ads, "remove" sets status to REMOVED. Entities cannot be un-removed.
+
+## Available Tools Summary
+
+| Tool | Purpose | Read/Write |
+|------|---------|:----------:|
+| \`gads_gaql_search\` | Execute arbitrary GAQL queries | Read |
+| \`gads_list_accounts\` | List accessible customer accounts | Read |
+| \`gads_get_entity\` | Get single entity by type/ID | Read |
+| \`gads_list_entities\` | List entities with filters | Read |
+| \`gads_create_entity\` | Create via :mutate API | Write |
+| \`gads_update_entity\` | Update with updateMask | Write |
+| \`gads_remove_entity\` | Remove via :mutate API | Write |
+| \`gads_bulk_mutate\` | Multi-operation mutate | Write |
+| \`gads_bulk_update_status\` | Batch enable/pause/remove | Write |
+`;
+}
+export const entityHierarchyResource = {
+    uri: "entity-hierarchy://gads",
+    name: "Google Ads Entity Hierarchy",
+    description: "Parent-child relationships between Google Ads entities, API patterns, creation/deletion ordering, and platform differences",
+    mimeType: "text/markdown",
+    getContent: () => {
+        cachedContent ??= formatEntityHierarchyMarkdown();
+        return cachedContent;
+    },
+};
+//# sourceMappingURL=entity-hierarchy.resource.js.map

package/dist/mcp-server/resources/definitions/entity-hierarchy.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-hierarchy.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-hierarchy.resource.ts"],"names":[],"mappings":"AAUA,IAAI,aAAiC,CAAC;AAEtC,SAAS,6BAA6B;IACpC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6GR,CAAC;AACF,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAa;IAC/C,GAAG,EAAE,yBAAyB;IAC9B,IAAI,EAAE,6BAA6B;IACnC,WAAW,EACT,4HAA4H;IAC9H,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE;QACf,aAAa,KAAK,6BAA6B,EAAE,CAAC;QAClD,OAAO,aAAa,CAAC;IACvB,CAAC;CACF,CAAC"}

package/dist/mcp-server/resources/definitions/entity-schemas.resource.d.ts

@@ -0,0 +1,4 @@
+import type { Resource } from "../types.js";
+export declare const entitySchemaResources: Resource[];
+export declare const entitySchemaAllResource: Resource;
+//# sourceMappingURL=entity-schemas.resource.d.ts.map

package/dist/mcp-server/resources/definitions/entity-schemas.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-schemas.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-schemas.resource.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAqQ5C,eAAO,MAAM,qBAAqB,EAAE,QAAQ,EAMzC,CAAC;AAEJ,eAAO,MAAM,uBAAuB,EAAE,QASrC,CAAC"}

package/dist/mcp-server/resources/definitions/entity-schemas.resource.js

@@ -0,0 +1,264 @@
+const cachedSchemas = new Map();
+function campaignSchemaMarkdown() {
+    return `# Google Ads Campaign Schema
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`name\` | string | **Yes** | Campaign name (unique within account) |
+| \`advertisingChannelType\` | enum | **Yes** | \`SEARCH\`, \`DISPLAY\`, \`SHOPPING\`, \`VIDEO\`, \`MULTI_CHANNEL\`, \`PERFORMANCE_MAX\`, \`DEMAND_GEN\` |
+| \`status\` | enum | No | \`ENABLED\`, \`PAUSED\`, \`REMOVED\` (default: \`ENABLED\`) |
+| \`campaignBudget\` | string | **Yes** | Resource name of the campaign budget (e.g., \`customers/{id}/campaignBudgets/{budgetId}\`) |
+| \`startDate\` | string | No | Start date in YYYY-MM-DD format |
+| \`endDate\` | string | No | End date in YYYY-MM-DD format |
+| \`biddingStrategyType\` | enum | No | \`MANUAL_CPC\`, \`MAXIMIZE_CONVERSIONS\`, \`MAXIMIZE_CONVERSION_VALUE\`, \`TARGET_CPA\`, \`TARGET_ROAS\`, etc. |
+| \`manualCpc\` | object | Cond. | Manual CPC settings (when biddingStrategyType = MANUAL_CPC) |
+| \`maximizeConversions\` | object | Cond. | Maximize conversions settings |
+| \`targetCpa\` | object | Cond. | Target CPA settings with \`targetCpaMicros\` |
+| \`targetRoas\` | object | Cond. | Target ROAS settings with \`targetRoas\` (float) |
+| \`networkSettings\` | object | No | Network targeting (Search, Display, YouTube, partners) |
+| \`geoTargetTypeSetting\` | object | No | Geo targeting type configuration |
+| \`frequencyCaps\` | object[] | No | Frequency capping rules |
+| \`urlCustomParameters\` | object[] | No | Custom URL parameters |
+
+## Network Settings Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`targetGoogleSearch\` | boolean | Show ads on Google Search |
+| \`targetSearchNetwork\` | boolean | Show ads on search partner sites |
+| \`targetContentNetwork\` | boolean | Show ads on Display Network |
+| \`targetPartnerSearchNetwork\` | boolean | Show ads on partner search network |
+
+## Notes
+- \`campaignBudget\` must reference an existing CampaignBudget resource (create budget first).
+- \`advertisingChannelType\` cannot be changed after creation.
+- Use \`PERFORMANCE_MAX\` for AI-optimized campaigns across all Google surfaces.
+- Bidding strategy fields are mutually exclusive — set only one.
+`;
+}
+function adGroupSchemaMarkdown() {
+    return `# Google Ads Ad Group Schema
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`name\` | string | **Yes** | Ad group name |
+| \`campaign\` | string | **Yes** | Parent campaign resource name |
+| \`status\` | enum | No | \`ENABLED\`, \`PAUSED\`, \`REMOVED\` |
+| \`type\` | enum | No | \`SEARCH_STANDARD\`, \`DISPLAY_STANDARD\`, \`SHOPPING_PRODUCT_ADS\`, \`VIDEO_BUMPER\`, etc. |
+| \`cpcBidMicros\` | string (int64) | No | Default max CPC bid in micros (1,000,000 micros = 1 currency unit) |
+| \`cpmBidMicros\` | string (int64) | No | Default CPM bid in micros |
+| \`targetCpaMicros\` | string (int64) | No | Target CPA bid in micros |
+| \`targetRoas\` | number | No | Target ROAS (e.g., 2.0 = 200% return) |
+| \`adRotationMode\` | enum | No | \`OPTIMIZE\`, \`ROTATE_FOREVER\` |
+| \`urlCustomParameters\` | object[] | No | Custom URL parameters |
+
+## Notes
+- \`campaign\` must be a valid campaign resource name: \`customers/{customerId}/campaigns/{campaignId}\`.
+- \`cpcBidMicros\` is in micros: to set $2.50 bid, use \`"2500000"\`.
+- Ad group type is typically inferred from the parent campaign's channel type.
+- For Display campaigns, targeting options (audiences, placements) are set separately.
+`;
+}
+function adSchemaMarkdown() {
+    return `# Google Ads Ad (AdGroupAd) Schema
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`adGroup\` | string | **Yes** | Parent ad group resource name |
+| \`status\` | enum | No | \`ENABLED\`, \`PAUSED\`, \`REMOVED\` |
+| \`ad\` | object | **Yes** | The ad creative object (see below) |
+
+## Ad Object (varies by type)
+
+### Responsive Search Ad
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`responsiveSearchAd\` | object | **Yes** | RSA creative content |
+| \`responsiveSearchAd.headlines\` | object[] | **Yes** | 3-15 headline options (\`{ text: string }\`) |
+| \`responsiveSearchAd.descriptions\` | object[] | **Yes** | 2-4 description options (\`{ text: string }\`) |
+| \`responsiveSearchAd.path1\` | string | No | Display URL path 1 (max 15 chars) |
+| \`responsiveSearchAd.path2\` | string | No | Display URL path 2 (max 15 chars) |
+| \`finalUrls\` | string[] | **Yes** | Landing page URLs |
+| \`finalMobileUrls\` | string[] | No | Mobile-specific landing pages |
+| \`trackingUrlTemplate\` | string | No | Tracking URL template |
+
+### Responsive Display Ad
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`responsiveDisplayAd\` | object | **Yes** | Display ad content |
+| \`responsiveDisplayAd.headlines\` | object[] | **Yes** | Short headlines |
+| \`responsiveDisplayAd.longHeadline\` | object | **Yes** | Long headline |
+| \`responsiveDisplayAd.descriptions\` | object[] | **Yes** | Description options |
+| \`responsiveDisplayAd.marketingImages\` | object[] | **Yes** | Marketing image assets |
+| \`responsiveDisplayAd.squareMarketingImages\` | object[] | No | Square format images |
+| \`responsiveDisplayAd.businessName\` | string | **Yes** | Business/brand name |
+| \`finalUrls\` | string[] | **Yes** | Landing page URLs |
+
+## Notes
+- Google Ads strongly favors Responsive Search Ads (RSA) over expanded text ads.
+- Provide 8-15 headlines and 3-4 descriptions for best RSA performance.
+- Headlines max 30 chars each; descriptions max 90 chars each.
+- \`finalUrls\` is required for all ad types.
+`;
+}
+function keywordSchemaMarkdown() {
+    return `# Google Ads Keyword (AdGroupCriterion) Schema
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`adGroup\` | string | **Yes** | Parent ad group resource name |
+| \`status\` | enum | No | \`ENABLED\`, \`PAUSED\`, \`REMOVED\` |
+| \`keyword\` | object | **Yes** | Keyword targeting settings |
+| \`keyword.text\` | string | **Yes** | The keyword text |
+| \`keyword.matchType\` | enum | **Yes** | \`BROAD\`, \`PHRASE\`, \`EXACT\` |
+| \`cpcBidMicros\` | string (int64) | No | Keyword-level max CPC bid override (in micros) |
+| \`finalUrls\` | string[] | No | Keyword-level landing page override |
+| \`negative\` | boolean | No | Whether this is a negative keyword |
+
+## Match Types
+
+| Match Type | Behavior | Example for "running shoes" |
+|------------|----------|---------------------------|
+| \`BROAD\` | Shows for related searches | "buy sneakers", "jogging footwear" |
+| \`PHRASE\` | Shows when search includes phrase | "best running shoes", "running shoes sale" |
+| \`EXACT\` | Shows for exact or close variant | "running shoes", "running shoe" |
+
+## Notes
+- Keywords are created as AdGroupCriterion resources.
+- Bid in micros: $1.50 = \`"1500000"\`.
+- Negative keywords exclude searches — set \`negative: true\`.
+- Broad match is recommended with Smart Bidding strategies.
+`;
+}
+function campaignBudgetSchemaMarkdown() {
+    return `# Google Ads Campaign Budget Schema
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`name\` | string | No | Budget name (for reference) |
+| \`amountMicros\` | string (int64) | **Yes** | Daily budget in micros (1,000,000 micros = 1 currency unit) |
+| \`deliveryMethod\` | enum | No | \`STANDARD\` (spread evenly) or \`ACCELERATED\` (spend quickly, limited availability) |
+| \`explicitlyShared\` | boolean | No | Whether budget is shared across campaigns |
+| \`status\` | enum | Read-only | \`ENABLED\`, \`REMOVED\` |
+| \`totalAmountMicros\` | string (int64) | No | Total lifetime budget in micros (optional) |
+
+## Notes
+- Create budget first, then reference it in campaign creation via \`campaignBudget\` field.
+- \`amountMicros\` is the **daily** budget: $50/day = \`"50000000"\`.
+- A budget can be shared across multiple campaigns if \`explicitlyShared: true\`.
+- \`STANDARD\` delivery is recommended — spreads spend evenly throughout the day.
+`;
+}
+function assetSchemaMarkdown() {
+    return `# Google Ads Asset Schema
+
+## Overview
+
+Assets are reusable building blocks (text, images, videos, etc.) that can be linked to
+campaigns and ad groups via CampaignAsset and AdGroupAsset associations.
+
+## Common Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`name\` | string | No | Optional asset name for reference |
+| \`type\` | enum | Read-only | Auto-set based on asset content: \`TEXT\`, \`IMAGE\`, \`YOUTUBE_VIDEO\`, \`CALLOUT\`, \`SITELINK\`, \`CALL\`, \`STRUCTURED_SNIPPET\`, etc. |
+| \`resourceName\` | string | Read-only | \`customers/{customerId}/assets/{assetId}\` |
+
+## Asset Type-Specific Fields
+
+### Text Asset
+| Field | Type | Description |
+|-------|------|-------------|
+| \`textAsset.text\` | string | The text content |
+
+### Image Asset
+| Field | Type | Description |
+|-------|------|-------------|
+| \`imageAsset.data\` | bytes (base64) | Raw image data |
+| \`imageAsset.fileSize\` | int64 | File size in bytes |
+| \`imageAsset.mimeType\` | enum | \`IMAGE_JPEG\`, \`IMAGE_PNG\`, \`IMAGE_GIF\` |
+| \`imageAsset.fullSize\` | object | Full-size image dimensions |
+
+### Sitelink Asset
+| Field | Type | Description |
+|-------|------|-------------|
+| \`sitelinkAsset.linkText\` | string | Sitelink anchor text (max 25 chars) |
+| \`sitelinkAsset.description1\` | string | Description line 1 |
+| \`sitelinkAsset.description2\` | string | Description line 2 |
+| \`finalUrls\` | string[] | Landing page URLs |
+
+### Callout Asset
+| Field | Type | Description |
+|-------|------|-------------|
+| \`calloutAsset.calloutText\` | string | Callout text (max 25 chars) |
+
+### Call Asset
+| Field | Type | Description |
+|-------|------|-------------|
+| \`callAsset.countryCode\` | string | Two-letter country code |
+| \`callAsset.phoneNumber\` | string | Phone number string |
+
+## Notes
+- Assets replaced the legacy Extension Feed Items API (removed in API v23).
+- Create assets first, then link via \`CampaignAsset\` or \`AdGroupAsset\` associations.
+- Assets can be shared across multiple campaigns/ad groups.
+- At least 2 sitelink assets recommended for best ad performance.
+`;
+}
+const SCHEMA_GENERATORS = {
+    campaign: campaignSchemaMarkdown,
+    adgroup: adGroupSchemaMarkdown,
+    ad: adSchemaMarkdown,
+    keyword: keywordSchemaMarkdown,
+    campaignbudget: campaignBudgetSchemaMarkdown,
+    asset: assetSchemaMarkdown,
+};
+const ENTITY_TYPES = ["campaign", "adGroup", "ad", "keyword", "campaignBudget", "asset"];
+function getSchemaContent(entityType) {
+    const key = entityType.toLowerCase();
+    if (!cachedSchemas.has(key)) {
+        const generator = SCHEMA_GENERATORS[key];
+        if (generator) {
+            cachedSchemas.set(key, generator());
+        }
+        else {
+            return `# Unknown entity type: ${entityType}\n\nSupported types: ${ENTITY_TYPES.join(", ")}`;
+        }
+    }
+    return cachedSchemas.get(key);
+}
+let cachedAllSchemas;
+function getAllSchemasMarkdown() {
+    return ENTITY_TYPES.map((t) => getSchemaContent(t)).join("\n---\n\n");
+}
+export const entitySchemaResources = ENTITY_TYPES.map((entityType) => ({
+    uri: `entity-schema://${entityType}`,
+    name: `Google Ads ${entityType} Schema`,
+    description: `Field reference for Google Ads ${entityType} entities including required fields, types, and nested objects`,
+    mimeType: "text/markdown",
+    getContent: () => getSchemaContent(entityType),
+}));
+export const entitySchemaAllResource = {
+    uri: "entity-schema://all",
+    name: "Google Ads All Entity Schemas",
+    description: "Combined field reference for all Google Ads entity types",
+    mimeType: "text/markdown",
+    getContent: () => {
+        cachedAllSchemas ??= getAllSchemasMarkdown();
+        return cachedAllSchemas;
+    },
+};
+//# sourceMappingURL=entity-schemas.resource.js.map

package/dist/mcp-server/resources/definitions/entity-schemas.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-schemas.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-schemas.resource.ts"],"names":[],"mappings":"AAUA,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEhD,SAAS,sBAAsB;IAC7B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCR,CAAC;AACF,CAAC;AAED,SAAS,qBAAqB;IAC5B,OAAO;;;;;;;;;;;;;;;;;;;;;;CAsBR,CAAC;AACF,CAAC;AAED,SAAS,gBAAgB;IACvB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CR,CAAC;AACF,CAAC;AAED,SAAS,qBAAqB;IAC5B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BR,CAAC;AACF,CAAC;AAED,SAAS,4BAA4B;IACnC,OAAO;;;;;;;;;;;;;;;;;;CAkBR,CAAC;AACF,CAAC;AAED,SAAS,mBAAmB;IAC1B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDR,CAAC;AACF,CAAC;AAID,MAAM,iBAAiB,GAAiC;IACtD,QAAQ,EAAE,sBAAsB;IAChC,OAAO,EAAE,qBAAqB;IAC9B,EAAE,EAAE,gBAAgB;IACpB,OAAO,EAAE,qBAAqB;IAC9B,cAAc,EAAE,4BAA4B;IAC5C,KAAK,EAAE,mBAAmB;CAC3B,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,gBAAgB,EAAE,OAAO,CAAU,CAAC;AAElG,SAAS,gBAAgB,CAAC,UAAkB;IAC1C,MAAM,GAAG,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IACrC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,SAAS,EAAE,CAAC;YACd,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,OAAO,0BAA0B,UAAU,wBAAwB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/F,CAAC;IACH,CAAC;IACD,OAAO,aAAa,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;AACjC,CAAC;AAED,IAAI,gBAAoC,CAAC;AAEzC,SAAS,qBAAqB;IAC5B,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAe,YAAY,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IACjF,GAAG,EAAE,mBAAmB,UAAU,EAAE;IACpC,IAAI,EAAE,cAAc,UAAU,SAAS;IACvC,WAAW,EAAE,kCAAkC,UAAU,gEAAgE;IACzH,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE,CAAC,gBAAgB,CAAC,UAAU,CAAC;CAC/C,CAAC,CAAC,CAAC;AAEJ,MAAM,CAAC,MAAM,uBAAuB,GAAa;IAC/C,GAAG,EAAE,qBAAqB;IAC1B,IAAI,EAAE,+BAA+B;IACrC,WAAW,EAAE,0DAA0D;IACvE,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE;QACf,gBAAgB,KAAK,qBAAqB,EAAE,CAAC;QAC7C,OAAO,gBAAgB,CAAC;IAC1B,CAAC;CACF,CAAC"}

package/dist/mcp-server/resources/definitions/gaql-reference.resource.d.ts

@@ -0,0 +1,3 @@
+import type { Resource } from "../types.js";
+export declare const gaqlReferenceResource: Resource;
+//# sourceMappingURL=gaql-reference.resource.d.ts.map

package/dist/mcp-server/resources/definitions/gaql-reference.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaql-reference.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gaql-reference.resource.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAsJ5C,eAAO,MAAM,qBAAqB,EAAE,QAUnC,CAAC"}

package/dist/mcp-server/resources/definitions/gaql-reference.resource.js

@@ -0,0 +1,157 @@
+let cachedContent;
+function buildGaqlReferenceMarkdown() {
+    return `# GAQL (Google Ads Query Language) Reference
+
+## Query Structure
+
+\`\`\`
+SELECT field1, field2, metrics.metric1
+FROM resource
+WHERE condition1 AND condition2
+ORDER BY field1 ASC
+LIMIT 100
+PARAMETERS include_drafts=true
+\`\`\`
+
+Only \`SELECT\` and \`FROM\` are required. All other clauses are optional.
+
+## Field Types
+
+| Type | Example | Description |
+|------|---------|-------------|
+| **Resource fields** | \`campaign.name\`, \`campaign.id\` | Entity attributes |
+| **Segment fields** | \`segments.date\`, \`segments.device\` | Breakdowns/dimensions |
+| **Metrics** | \`metrics.impressions\`, \`metrics.clicks\` | Performance data |
+
+## Common Resources (FROM clause)
+
+| Resource | Description | Key Fields |
+|----------|-------------|------------|
+| \`campaign\` | Campaign data | \`campaign.id\`, \`campaign.name\`, \`campaign.status\` |
+| \`ad_group\` | Ad group data | \`ad_group.id\`, \`ad_group.name\`, \`ad_group.status\` |
+| \`ad_group_ad\` | Ad data | \`ad_group_ad.ad.id\`, \`ad_group_ad.status\` |
+| \`ad_group_criterion\` | Keywords/criteria | \`ad_group_criterion.keyword.text\`, \`ad_group_criterion.keyword.match_type\` |
+| \`campaign_budget\` | Budget data | \`campaign_budget.amount_micros\`, \`campaign_budget.status\` |
+| \`customer\` | Account data | \`customer.id\`, \`customer.descriptive_name\` |
+
+## Common Metrics
+
+| Metric | Description |
+|--------|-------------|
+| \`metrics.impressions\` | Number of impressions |
+| \`metrics.clicks\` | Number of clicks |
+| \`metrics.ctr\` | Click-through rate (clicks/impressions) |
+| \`metrics.average_cpc\` | Average cost per click (micros) |
+| \`metrics.average_cpm\` | Average cost per thousand impressions (micros) |
+| \`metrics.cost_micros\` | Total cost (micros) |
+| \`metrics.conversions\` | Number of conversions |
+| \`metrics.conversions_value\` | Total conversion value |
+| \`metrics.cost_per_conversion\` | Cost per conversion (micros) |
+| \`metrics.video_views\` | Video views |
+| \`metrics.video_view_rate\` | Video view rate |
+
+## Common Segments
+
+| Segment | Description |
+|---------|-------------|
+| \`segments.date\` | Date (YYYY-MM-DD) |
+| \`segments.device\` | \`MOBILE\`, \`DESKTOP\`, \`TABLET\` |
+| \`segments.ad_network_type\` | \`SEARCH\`, \`CONTENT\`, \`YOUTUBE_SEARCH\`, \`YOUTUBE_WATCH\` |
+| \`segments.day_of_week\` | \`MONDAY\` through \`SUNDAY\` |
+| \`segments.hour\` | Hour of day (0-23) |
+
+## WHERE Operators
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| \`=\` | \`campaign.status = 'ENABLED'\` | Equals |
+| \`!=\` | \`campaign.status != 'REMOVED'\` | Not equals |
+| \`>\`, \`<\`, \`>=\`, \`<=\` | \`metrics.impressions > 100\` | Comparison |
+| \`IN\` | \`campaign.status IN ('ENABLED', 'PAUSED')\` | Set membership |
+| \`NOT IN\` | \`campaign.status NOT IN ('REMOVED')\` | Set exclusion |
+| \`LIKE\` | \`campaign.name LIKE '%brand%'\` | Pattern match |
+| \`CONTAINS ANY\` | \`campaign.labels CONTAINS ANY ('label1')\` | Label matching |
+| \`IS NULL\` / \`IS NOT NULL\` | \`campaign.end_date IS NOT NULL\` | Null check |
+| \`BETWEEN\` | \`segments.date BETWEEN '2025-01-01' AND '2025-01-31'\` | Date range |
+| \`DURING\` | \`segments.date DURING LAST_30_DAYS\` | Relative date range |
+
+## DURING Predefined Ranges
+
+\`TODAY\`, \`YESTERDAY\`, \`LAST_7_DAYS\`, \`LAST_14_DAYS\`, \`LAST_30_DAYS\`,
+\`THIS_WEEK_MON_TODAY\`, \`THIS_MONTH\`, \`LAST_MONTH\`, \`THIS_QUARTER\`
+
+## Example Queries
+
+### Campaign Performance (Last 30 Days)
+\`\`\`
+SELECT campaign.name, campaign.status,
+       metrics.impressions, metrics.clicks, metrics.ctr,
+       metrics.cost_micros, metrics.conversions
+FROM campaign
+WHERE campaign.status != 'REMOVED'
+  AND segments.date DURING LAST_30_DAYS
+ORDER BY metrics.cost_micros DESC
+LIMIT 50
+\`\`\`
+
+### Active Ad Groups with Performance
+\`\`\`
+SELECT ad_group.name, ad_group.status, ad_group.campaign,
+       metrics.impressions, metrics.clicks, metrics.average_cpc
+FROM ad_group
+WHERE ad_group.status = 'ENABLED'
+  AND segments.date DURING LAST_7_DAYS
+ORDER BY metrics.impressions DESC
+\`\`\`
+
+### Keywords with Low Quality Score
+\`\`\`
+SELECT ad_group_criterion.keyword.text,
+       ad_group_criterion.keyword.match_type,
+       ad_group_criterion.quality_info.quality_score,
+       metrics.impressions, metrics.clicks, metrics.average_cpc
+FROM keyword_view
+WHERE ad_group_criterion.quality_info.quality_score < 5
+  AND segments.date DURING LAST_30_DAYS
+ORDER BY metrics.impressions DESC
+\`\`\`
+
+### Daily Campaign Spend
+\`\`\`
+SELECT campaign.name, segments.date,
+       metrics.cost_micros, metrics.impressions, metrics.clicks
+FROM campaign
+WHERE segments.date DURING LAST_14_DAYS
+  AND campaign.status = 'ENABLED'
+ORDER BY segments.date DESC
+\`\`\`
+
+### Device Breakdown
+\`\`\`
+SELECT campaign.name, segments.device,
+       metrics.impressions, metrics.clicks, metrics.ctr
+FROM campaign
+WHERE segments.date DURING LAST_7_DAYS
+  AND campaign.status = 'ENABLED'
+\`\`\`
+
+## Important Notes
+
+- **Micros**: All monetary values are in micros. Divide by 1,000,000 for display currency.
+- **Segment compatibility**: Not all segments can be combined. Use Google Ads FieldService for validation.
+- **Date segments**: Adding \`segments.date\` returns one row per entity per day.
+- **Resource limits**: Queries return max 10,000 rows by default; use \`LIMIT\` to control.
+- **Removed entities**: By default, REMOVED entities are excluded. Add \`PARAMETERS include_drafts=true\` to include them.
+`;
+}
+export const gaqlReferenceResource = {
+    uri: "gaql-reference://syntax",
+    name: "GAQL Syntax Reference",
+    description: "Google Ads Query Language syntax guide with common query patterns, operators, metrics, and segments",
+    mimeType: "text/markdown",
+    getContent: () => {
+        cachedContent ??= buildGaqlReferenceMarkdown();
+        return cachedContent;
+    },
+};
+//# sourceMappingURL=gaql-reference.resource.js.map

package/dist/mcp-server/resources/definitions/gaql-reference.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaql-reference.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gaql-reference.resource.ts"],"names":[],"mappings":"AAUA,IAAI,aAAiC,CAAC;AAEtC,SAAS,0BAA0B;IACjC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8IR,CAAC;AACF,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAa;IAC7C,GAAG,EAAE,yBAAyB;IAC9B,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EACT,qGAAqG;IACvG,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE;QACf,aAAa,KAAK,0BAA0B,EAAE,CAAC;QAC/C,OAAO,aAAa,CAAC;IACvB,CAAC;CACF,CAAC"}

package/dist/mcp-server/resources/definitions/index.d.ts

@@ -0,0 +1,8 @@
+export { entityHierarchyResource } from "./entity-hierarchy.resource.js";
+export { entitySchemaResources, entitySchemaAllResource } from "./entity-schemas.resource.js";
+export { entityExampleResources, entityExampleAllResource } from "./entity-examples.resource.js";
+export { gaqlReferenceResource } from "./gaql-reference.resource.js";
+export { insightsReferenceResource } from "./insights-reference.resource.js";
+import type { Resource } from "../types.js";
+export declare const allResources: Resource[];
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/resources/definitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC9F,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACjG,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAS7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAwB5C,eAAO,MAAM,YAAY,EAAE,QAAQ,EAUlC,CAAC"}

package/dist/mcp-server/resources/definitions/index.js

@@ -0,0 +1,42 @@
+export { entityHierarchyResource } from "./entity-hierarchy.resource.js";
+export { entitySchemaResources, entitySchemaAllResource } from "./entity-schemas.resource.js";
+export { entityExampleResources, entityExampleAllResource } from "./entity-examples.resource.js";
+export { gaqlReferenceResource } from "./gaql-reference.resource.js";
+export { insightsReferenceResource } from "./insights-reference.resource.js";
+import { entityHierarchyResource } from "./entity-hierarchy.resource.js";
+import { entitySchemaResources, entitySchemaAllResource } from "./entity-schemas.resource.js";
+import { entityExampleResources, entityExampleAllResource } from "./entity-examples.resource.js";
+import { gaqlReferenceResource } from "./gaql-reference.resource.js";
+import { insightsReferenceResource } from "./insights-reference.resource.js";
+import { allTools } from "../../tools/definitions/index.js";
+import { createToolExamplesResource, createServerCapabilitiesResource } from "@cesteral/shared";
+const toolExamplesResource = createToolExamplesResource(allTools, "gads-mcp");
+const serverCapabilitiesResource = createServerCapabilitiesResource({
+    serverName: "gads-mcp",
+    toolGroups: {
+        read: [
+            "gads_gaql_search",
+            "gads_list_accounts",
+            "gads_get_entity",
+            "gads_list_entities",
+            "gads_get_insights",
+        ],
+        write: ["gads_create_entity", "gads_update_entity", "gads_remove_entity"],
+        bulk: ["gads_bulk_mutate", "gads_bulk_update_status", "gads_adjust_bids"],
+        validation: ["gads_validate_entity"],
+    },
+    commonWorkflows: ["campaign_setup", "performance_analysis", "bulk_status_update"],
+    startHere: "gads_list_accounts",
+});
+export const allResources = [
+    entityHierarchyResource,
+    entitySchemaAllResource,
+    ...entitySchemaResources,
+    entityExampleAllResource,
+    ...entityExampleResources,
+    gaqlReferenceResource,
+    insightsReferenceResource,
+    ...(toolExamplesResource ? [toolExamplesResource] : []),
+    serverCapabilitiesResource,
+];
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/resources/definitions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC9F,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACjG,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAE7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC9F,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACjG,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAC5D,OAAO,EAAE,0BAA0B,EAAE,gCAAgC,EAAE,MAAM,kBAAkB,CAAC;AAGhG,MAAM,oBAAoB,GAAG,0BAA0B,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC9E,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;IAClE,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE;QACV,IAAI,EAAE;YACJ,kBAAkB;YAClB,oBAAoB;YACpB,iBAAiB;YACjB,oBAAoB;YACpB,mBAAmB;SACpB;QACD,KAAK,EAAE,CAAC,oBAAoB,EAAE,oBAAoB,EAAE,oBAAoB,CAAC;QACzE,IAAI,EAAE,CAAC,kBAAkB,EAAE,yBAAyB,EAAE,kBAAkB,CAAC;QACzE,UAAU,EAAE,CAAC,sBAAsB,CAAC;KACrC;IACD,eAAe,EAAE,CAAC,gBAAgB,EAAE,sBAAsB,EAAE,oBAAoB,CAAC;IACjF,SAAS,EAAE,oBAAoB;CAChC,CAAC,CAAC;AAKH,MAAM,CAAC,MAAM,YAAY,GAAe;IACtC,uBAAuB;IACvB,uBAAuB;IACvB,GAAG,qBAAqB;IACxB,wBAAwB;IACxB,GAAG,sBAAsB;IACzB,qBAAqB;IACrB,yBAAyB;IACzB,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,oBAA2C,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,0BAAiD;CAClD,CAAC"}

package/dist/mcp-server/resources/definitions/insights-reference.resource.d.ts

@@ -0,0 +1,3 @@
+import type { Resource } from "../types.js";
+export declare const insightsReferenceResource: Resource;
+//# sourceMappingURL=insights-reference.resource.d.ts.map

package/dist/mcp-server/resources/definitions/insights-reference.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights-reference.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/insights-reference.resource.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,eAAO,MAAM,yBAAyB,EAAE,QA6EvC,CAAC"}