@cesteral/gads-mcp 1.0.0

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity-examples.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-examples.resource.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA6jB5C,eAAO,MAAM,sBAAsB,EAAE,QAAQ,EAM1C,CAAC;AAEJ,eAAO,MAAM,wBAAwB,EAAE,QAStC,CAAC"}

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

@@ -0,0 +1,574 @@
+const cachedExamples = new Map();
+function campaignExamplesMarkdown() {
+    return `# Google Ads Campaign Examples
+
+## Create Search Campaign
+
+\`\`\`json
+{
+  "entityType": "campaign",
+  "customerId": "1234567890",
+  "data": {
+    "name": "Q1 2025 Brand Search",
+    "advertisingChannelType": "SEARCH",
+    "status": "PAUSED",
+    "campaignBudget": "customers/1234567890/campaignBudgets/111222333",
+    "startDate": "2025-03-01",
+    "networkSettings": {
+      "targetGoogleSearch": true,
+      "targetSearchNetwork": true,
+      "targetContentNetwork": false,
+      "targetPartnerSearchNetwork": false
+    },
+    "manualCpc": {
+      "enhancedCpcEnabled": false
+    }
+  }
+}
+\`\`\`
+> \`campaignBudget\` must reference an existing CampaignBudget resource name.
+> Set \`status: "PAUSED"\` initially, enable after full setup.
+
+## Create Display Campaign
+
+\`\`\`json
+{
+  "entityType": "campaign",
+  "customerId": "1234567890",
+  "data": {
+    "name": "Q1 Display Remarketing",
+    "advertisingChannelType": "DISPLAY",
+    "status": "PAUSED",
+    "campaignBudget": "customers/1234567890/campaignBudgets/111222333",
+    "startDate": "2025-03-01",
+    "targetCpa": {
+      "targetCpaMicros": "5000000"
+    }
+  }
+}
+\`\`\`
+
+## Get Campaign
+
+\`\`\`json
+{
+  "entityType": "campaign",
+  "customerId": "1234567890",
+  "entityId": "444555666"
+}
+\`\`\`
+
+## List Campaigns
+
+\`\`\`json
+{
+  "entityType": "campaign",
+  "customerId": "1234567890"
+}
+\`\`\`
+
+## Update Campaign (Pause)
+
+\`\`\`json
+{
+  "entityType": "campaign",
+  "customerId": "1234567890",
+  "entityId": "444555666",
+  "data": {
+    "status": "PAUSED"
+  },
+  "updateMask": "status"
+}
+\`\`\`
+> \`updateMask\` is required — only listed fields are updated.
+
+## Remove Campaign
+
+\`\`\`json
+{
+  "entityType": "campaign",
+  "customerId": "1234567890",
+  "entityId": "444555666"
+}
+\`\`\`
+> Removal sets status to REMOVED. This cannot be undone.
+`;
+}
+function adGroupExamplesMarkdown() {
+    return `# Google Ads Ad Group Examples
+
+## Create Ad Group
+
+\`\`\`json
+{
+  "entityType": "adGroup",
+  "customerId": "1234567890",
+  "data": {
+    "name": "Running Shoes - Exact Match",
+    "campaign": "customers/1234567890/campaigns/444555666",
+    "status": "ENABLED",
+    "type": "SEARCH_STANDARD",
+    "cpcBidMicros": "2500000"
+  }
+}
+\`\`\`
+> \`cpcBidMicros\` is the default max CPC bid in micros. $2.50 = "2500000".
+> \`campaign\` must be the full resource name.
+
+## Create Display Ad Group
+
+\`\`\`json
+{
+  "entityType": "adGroup",
+  "customerId": "1234567890",
+  "data": {
+    "name": "Remarketing - All Visitors",
+    "campaign": "customers/1234567890/campaigns/444555666",
+    "status": "ENABLED",
+    "type": "DISPLAY_STANDARD",
+    "cpmBidMicros": "3000000"
+  }
+}
+\`\`\`
+
+## Get Ad Group
+
+\`\`\`json
+{
+  "entityType": "adGroup",
+  "customerId": "1234567890",
+  "entityId": "777888999"
+}
+\`\`\`
+
+## List Ad Groups for Campaign
+
+\`\`\`json
+{
+  "entityType": "adGroup",
+  "customerId": "1234567890",
+  "filters": {
+    "ad_group.campaign": "= 'customers/1234567890/campaigns/444555666'"
+  }
+}
+\`\`\`
+
+## Update Ad Group (Adjust Bid)
+
+\`\`\`json
+{
+  "entityType": "adGroup",
+  "customerId": "1234567890",
+  "entityId": "777888999",
+  "data": {
+    "cpcBidMicros": "3500000"
+  },
+  "updateMask": "cpcBidMicros"
+}
+\`\`\`
+
+## Update Ad Group (Pause)
+
+\`\`\`json
+{
+  "entityType": "adGroup",
+  "customerId": "1234567890",
+  "entityId": "777888999",
+  "data": {
+    "status": "PAUSED"
+  },
+  "updateMask": "status"
+}
+\`\`\`
+`;
+}
+function adExamplesMarkdown() {
+    return `# Google Ads Ad Examples
+
+## Create Responsive Search Ad
+
+\`\`\`json
+{
+  "entityType": "ad",
+  "customerId": "1234567890",
+  "data": {
+    "adGroup": "customers/1234567890/adGroups/777888999",
+    "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"]
+    }
+  }
+}
+\`\`\`
+> Provide 8-15 headlines (max 30 chars) and 3-4 descriptions (max 90 chars) for best performance.
+> Google auto-tests headline/description combinations.
+
+## Create Responsive Display Ad
+
+\`\`\`json
+{
+  "entityType": "ad",
+  "customerId": "1234567890",
+  "data": {
+    "adGroup": "customers/1234567890/adGroups/777888999",
+    "status": "ENABLED",
+    "ad": {
+      "responsiveDisplayAd": {
+        "headlines": [{ "text": "Summer Sale" }],
+        "longHeadline": { "text": "Huge Summer Sale - Up to 50% Off" },
+        "descriptions": [{ "text": "Don't miss our biggest sale of the year." }],
+        "businessName": "Acme Store"
+      },
+      "finalUrls": ["https://www.example.com/summer-sale"]
+    }
+  }
+}
+\`\`\`
+
+## Get Ad
+
+\`\`\`json
+{
+  "entityType": "ad",
+  "customerId": "1234567890",
+  "entityId": "777888999~111222333"
+}
+\`\`\`
+> Ad IDs are composite: \`{adGroupId}~{adId}\`.
+
+## Update Ad (Pause)
+
+\`\`\`json
+{
+  "entityType": "ad",
+  "customerId": "1234567890",
+  "entityId": "777888999~111222333",
+  "data": {
+    "status": "PAUSED"
+  },
+  "updateMask": "status"
+}
+\`\`\`
+
+## Remove Ad
+
+\`\`\`json
+{
+  "entityType": "ad",
+  "customerId": "1234567890",
+  "entityId": "777888999~111222333"
+}
+\`\`\`
+`;
+}
+function keywordExamplesMarkdown() {
+    return `# Google Ads Keyword Examples
+
+## Create Exact Match Keyword
+
+\`\`\`json
+{
+  "entityType": "keyword",
+  "customerId": "1234567890",
+  "data": {
+    "adGroup": "customers/1234567890/adGroups/777888999",
+    "status": "ENABLED",
+    "keyword": {
+      "text": "running shoes",
+      "matchType": "EXACT"
+    },
+    "cpcBidMicros": "3000000"
+  }
+}
+\`\`\`
+> Match types: BROAD, PHRASE, EXACT.
+> \`cpcBidMicros\` overrides the ad group default bid.
+
+## Create Phrase Match Keyword
+
+\`\`\`json
+{
+  "entityType": "keyword",
+  "customerId": "1234567890",
+  "data": {
+    "adGroup": "customers/1234567890/adGroups/777888999",
+    "status": "ENABLED",
+    "keyword": {
+      "text": "best running shoes",
+      "matchType": "PHRASE"
+    }
+  }
+}
+\`\`\`
+> Omitting \`cpcBidMicros\` uses the ad group default bid.
+
+## Create Negative Keyword
+
+\`\`\`json
+{
+  "entityType": "keyword",
+  "customerId": "1234567890",
+  "data": {
+    "adGroup": "customers/1234567890/adGroups/777888999",
+    "status": "ENABLED",
+    "negative": true,
+    "keyword": {
+      "text": "free",
+      "matchType": "BROAD"
+    }
+  }
+}
+\`\`\`
+
+## Get Keyword
+
+\`\`\`json
+{
+  "entityType": "keyword",
+  "customerId": "1234567890",
+  "entityId": "777888999~444555666"
+}
+\`\`\`
+> Keyword IDs are composite: \`{adGroupId}~{criterionId}\`.
+
+## List Keywords for Ad Group
+
+\`\`\`json
+{
+  "entityType": "keyword",
+  "customerId": "1234567890",
+  "filters": {
+    "ad_group_criterion.ad_group": "= 'customers/1234567890/adGroups/777888999'"
+  }
+}
+\`\`\`
+
+## Update Keyword (Change Bid)
+
+\`\`\`json
+{
+  "entityType": "keyword",
+  "customerId": "1234567890",
+  "entityId": "777888999~444555666",
+  "data": {
+    "cpcBidMicros": "4000000"
+  },
+  "updateMask": "cpcBidMicros"
+}
+\`\`\`
+`;
+}
+function campaignBudgetExamplesMarkdown() {
+    return `# Google Ads Campaign Budget Examples
+
+## Create Daily Budget
+
+\`\`\`json
+{
+  "entityType": "campaignBudget",
+  "customerId": "1234567890",
+  "data": {
+    "name": "Daily Budget - $50",
+    "amountMicros": "50000000",
+    "deliveryMethod": "STANDARD"
+  }
+}
+\`\`\`
+> \`amountMicros\` is the daily budget in micros. $50/day = "50000000".
+> \`deliveryMethod\`: STANDARD (evenly throughout the day) or ACCELERATED (spend as quickly as possible).
+
+## Create Shared Budget
+
+\`\`\`json
+{
+  "entityType": "campaignBudget",
+  "customerId": "1234567890",
+  "data": {
+    "name": "Shared Budget - Brand Campaigns",
+    "amountMicros": "100000000",
+    "deliveryMethod": "STANDARD",
+    "explicitlyShared": true
+  }
+}
+\`\`\`
+> Shared budgets can be linked to multiple campaigns. Set \`explicitlyShared: true\`.
+
+## Get Campaign Budget
+
+\`\`\`json
+{
+  "entityType": "campaignBudget",
+  "customerId": "1234567890",
+  "entityId": "111222333"
+}
+\`\`\`
+
+## List Campaign Budgets
+
+\`\`\`json
+{
+  "entityType": "campaignBudget",
+  "customerId": "1234567890"
+}
+\`\`\`
+
+## Update Campaign Budget (Increase)
+
+\`\`\`json
+{
+  "entityType": "campaignBudget",
+  "customerId": "1234567890",
+  "entityId": "111222333",
+  "data": {
+    "amountMicros": "75000000"
+  },
+  "updateMask": "amountMicros"
+}
+\`\`\`
+`;
+}
+function assetExamplesMarkdown() {
+    return `# Google Ads Asset Examples
+
+## Create Sitelink Asset
+
+\`\`\`json
+{
+  "entityType": "asset",
+  "customerId": "1234567890",
+  "data": {
+    "name": "Summer Sale Sitelink",
+    "sitelinkAsset": {
+      "linkText": "Summer Sale",
+      "description1": "Up to 50% off all items",
+      "description2": "Free shipping on orders over $50"
+    },
+    "finalUrls": ["https://www.example.com/summer-sale"]
+  }
+}
+\`\`\`
+
+## Create Callout Asset
+
+\`\`\`json
+{
+  "entityType": "asset",
+  "customerId": "1234567890",
+  "data": {
+    "name": "Free Shipping Callout",
+    "calloutAsset": {
+      "calloutText": "Free Shipping"
+    }
+  }
+}
+\`\`\`
+
+## Create Structured Snippet Asset
+
+\`\`\`json
+{
+  "entityType": "asset",
+  "customerId": "1234567890",
+  "data": {
+    "name": "Brand Snippets",
+    "structuredSnippetAsset": {
+      "header": "Brands",
+      "values": ["Nike", "Adidas", "New Balance", "Brooks"]
+    }
+  }
+}
+\`\`\`
+
+## Create Image Asset
+
+\`\`\`json
+{
+  "entityType": "asset",
+  "customerId": "1234567890",
+  "data": {
+    "name": "Hero Banner Image",
+    "imageAsset": {
+      "data": "BASE64_ENCODED_IMAGE_DATA"
+    }
+  }
+}
+\`\`\`
+> Image data must be base64-encoded. Supported formats: PNG, JPG, GIF.
+
+## Get Asset
+
+\`\`\`json
+{
+  "entityType": "asset",
+  "customerId": "1234567890",
+  "entityId": "999888777"
+}
+\`\`\`
+
+## List Assets
+
+\`\`\`json
+{
+  "entityType": "asset",
+  "customerId": "1234567890"
+}
+\`\`\`
+`;
+}
+const EXAMPLE_GENERATORS = {
+    campaign: campaignExamplesMarkdown,
+    adgroup: adGroupExamplesMarkdown,
+    ad: adExamplesMarkdown,
+    keyword: keywordExamplesMarkdown,
+    campaignbudget: campaignBudgetExamplesMarkdown,
+    asset: assetExamplesMarkdown,
+};
+function getExampleContent(entityType) {
+    const key = entityType.toLowerCase();
+    if (!cachedExamples.has(key)) {
+        const generator = EXAMPLE_GENERATORS[key];
+        if (generator) {
+            cachedExamples.set(key, generator());
+        }
+        else {
+            return `# Unknown entity type: ${entityType}\n\nSupported types: ${ENTITY_TYPES.join(", ")}`;
+        }
+    }
+    return cachedExamples.get(key);
+}
+let cachedAllExamples;
+function getAllExamplesMarkdown() {
+    return ENTITY_TYPES.map((t) => getExampleContent(t)).join("\n---\n\n");
+}
+const ENTITY_TYPES = ["campaign", "adGroup", "ad", "keyword", "campaignBudget", "asset"];
+export const entityExampleResources = ENTITY_TYPES.map((entityType) => ({
+    uri: `entity-examples://${entityType}`,
+    name: `Google Ads ${entityType} Examples`,
+    description: `CRUD example payloads for Google Ads ${entityType} entities including create, get, list, update, and remove`,
+    mimeType: "text/markdown",
+    getContent: () => getExampleContent(entityType),
+}));
+export const entityExampleAllResource = {
+    uri: "entity-examples://all",
+    name: "Google Ads All Entity Examples",
+    description: "Combined CRUD example payloads for all Google Ads entity types",
+    mimeType: "text/markdown",
+    getContent: () => {
+        cachedAllExamples ??= getAllExamplesMarkdown();
+        return cachedAllExamples;
+    },
+};
+//# sourceMappingURL=entity-examples.resource.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity-examples.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-examples.resource.ts"],"names":[],"mappings":"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"}

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

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

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

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