@cesteral/ttd-mcp 1.0.0

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

@@ -0,0 +1,291 @@
+let cachedContent;
+function formatReportReferenceMarkdown() {
+    return `# TTD Report Reference (MyReports V3)
+
+## Overview
+
+TTD reports are generated via the MyReports V3 API which provides **188 dimensions** and **318 metrics**. Reports are **asynchronous**: you create a report schedule, TTD executes it, and you retrieve results when ready.
+
+### Two-Step Workflow
+1. \`ttd_get_report\` — create report schedule, poll for completion, get download URL
+2. \`ttd_download_report\` — fetch the CSV server-side and return a bounded summary or paged row slice
+
+---
+
+## Date Ranges
+
+| Value | Description |
+|-------|-------------|
+| \`Yesterday\` | Previous day only |
+| \`Last7Days\` | Last 7 days |
+| \`Last14Days\` | Last 14 days |
+| \`Last30Days\` | Last 30 days |
+| \`MonthToDate\` | Current month to date |
+| \`LastMonth\` | Previous full month |
+| \`LastWeek\` | Previous full week |
+| \`Last90Days\` | Last 90 days |
+| \`QuarterToDate\` | Current quarter to date |
+| \`LastQuarter\` | Previous full quarter |
+| \`YearToDate\` | Year to date |
+| \`Custom\` | Custom range (requires \`ReportStartDate\` and \`ReportEndDate\` in \`additionalConfig\`) |
+
+---
+
+## Dimensions (Key Selections from 188 Available)
+
+### Entity Dimensions
+| Dimension | Description |
+|-----------|-------------|
+| \`AdvertiserId\` | Advertiser identifier |
+| \`AdvertiserName\` | Advertiser display name |
+| \`AdvertiserCurrencyCode\` | Advertiser currency |
+| \`CampaignId\` | Campaign identifier |
+| \`CampaignName\` | Campaign display name |
+| \`AdGroupId\` | Ad group identifier |
+| \`AdGroupName\` | Ad group display name |
+| \`AdGroupBaseBidCPM\` | Ad group base bid setting |
+| \`AdGroupBudget\` | Ad group budget (currency) |
+| \`AdGroupBudgetImpressions\` | Ad group budget (impressions) |
+| \`AdGroupDailyCap\` | Daily spend cap |
+| \`AdGroupDailyTarget\` | Daily spend target |
+| \`AdId\` | Ad identifier |
+| \`AdName\` | Ad display name |
+| \`AdFormat\` | Ad format type |
+| \`AdType\` | Ad type |
+| \`CreativeId\` | Creative identifier |
+
+### Time Dimensions
+| Dimension | Description |
+|-----------|-------------|
+| \`Date\` | Date (daily granularity) |
+| \`Hour\` | Hour of day |
+| \`Week\` | Week number |
+| \`Month\` | Month |
+| \`DayOfWeek\` | Day of week |
+
+### Geo Dimensions
+| Dimension | Description |
+|-----------|-------------|
+| \`Country\` | Country |
+| \`Region\` | Region/State |
+| \`Metro\` | Metro/DMA |
+| \`City\` | City |
+| \`PostalCode\` | Postal code |
+
+### Technology Dimensions
+| Dimension | Description |
+|-----------|-------------|
+| \`DeviceType\` | Desktop, Mobile, Tablet, CTV |
+| \`OS\` | Operating system |
+| \`Browser\` | Browser |
+| \`Environment\` | Web, App, CTV |
+| \`ConnectionType\` | WiFi, Cellular, Wired |
+| \`DeviceMake\` | Device manufacturer |
+
+### Supply Dimensions
+| Dimension | Description |
+|-----------|-------------|
+| \`SupplyVendor\` | Exchange/SSP |
+| \`ChannelType\` | Display, Video, Audio, Native |
+| \`FoldPosition\` | Above/Below fold |
+| \`Site\` | Domain or app name |
+| \`AppName\` | Mobile app name |
+| \`DealId\` | PMP/PG deal identifier |
+| \`ContractId\` | Contract identifier |
+
+### Audience Dimensions
+| Dimension | Description |
+|-----------|-------------|
+| \`AudienceId\` | Audience segment ID |
+| \`AudienceName\` | Audience segment name |
+| \`DataProvider\` | Third-party data provider |
+
+---
+
+## Metrics (Key Selections from 318 Available)
+
+### Delivery Metrics
+| Metric | Description |
+|--------|-------------|
+| \`Impressions\` | Total impressions served |
+| \`Clicks\` | Total clicks |
+| \`TotalCost\` | Total advertiser spend |
+| \`MediaCost\` | Media cost only |
+| \`PartnerCostInAdvertiserCurrency\` | Partner cost |
+| \`AdvertiserCostInAdvertiserCurrency\` | Advertiser media cost |
+| \`DataCost\` | Third-party data cost |
+| \`UniqueReach\` | Unique users reached |
+| \`AverageFrequency\` | Average impressions per user |
+
+### Performance Metrics
+| Metric | Description |
+|--------|-------------|
+| \`CTR\` | Click-through rate |
+| \`eCPM\` | Effective CPM |
+| \`eCPC\` | Effective cost per click |
+| \`eCPA\` | Effective cost per action |
+| \`CPUR\` | Cost per unique reach |
+
+### Video Metrics
+| Metric | Description |
+|--------|-------------|
+| \`VideoStarted\` | Video starts |
+| \`VideoFirstQuartile\` | 25% completion |
+| \`VideoMidpoint\` | 50% completion |
+| \`VideoThirdQuartile\` | 75% completion |
+| \`VideoCompleted\` | 100% completion |
+| \`VCR\` | Video completion rate |
+| \`CPCV\` | Cost per completed view |
+
+### Conversion Metrics
+| Metric | Description |
+|--------|-------------|
+| \`TotalConversions\` | All conversions |
+| \`ClickConversions\` | Click-attributed conversions |
+| \`ViewConversions\` | View-attributed conversions |
+| \`ConversionRate\` | Conversion rate |
+| \`ROAS\` | Return on ad spend |
+| \`ConversionRevenue\` | Revenue from conversions |
+
+### Viewability Metrics
+| Metric | Description |
+|--------|-------------|
+| \`MeasuredImpressions\` | Impressions measured for viewability |
+| \`ViewableImpressions\` | Viewable impressions (MRC standard) |
+| \`ViewableRate\` | Viewability rate |
+| \`AverageInViewTime\` | Average time in view (seconds) |
+
+### CTV / Audio Metrics
+| Metric | Description |
+|--------|-------------|
+| \`AudioCompletions\` | Audio ad completions |
+| \`AudioCompletionRate\` | Audio completion rate |
+| \`CTVImpressions\` | Connected TV impressions |
+
+---
+
+## Common Report Templates
+
+### Campaign Performance Overview
+\`\`\`json
+{
+  "reportName": "Campaign Performance",
+  "dateRange": "Last7Days",
+  "dimensions": ["CampaignId", "CampaignName"],
+  "metrics": ["Impressions", "Clicks", "CTR", "TotalCost", "eCPM", "eCPC", "UniqueReach"],
+  "advertiserIds": ["abc123"]
+}
+\`\`\`
+
+### Daily Delivery Trend
+\`\`\`json
+{
+  "reportName": "Daily Delivery",
+  "dateRange": "Last30Days",
+  "dimensions": ["Date", "CampaignId", "CampaignName"],
+  "metrics": ["Impressions", "TotalCost", "UniqueReach"],
+  "advertiserIds": ["abc123"]
+}
+\`\`\`
+
+### Ad Group Bid Analysis
+\`\`\`json
+{
+  "reportName": "Ad Group Bids",
+  "dateRange": "Last7Days",
+  "dimensions": ["AdGroupId", "AdGroupName", "AdGroupBaseBidCPM"],
+  "metrics": ["Impressions", "Clicks", "TotalCost", "eCPM", "eCPC", "CTR"],
+  "advertiserIds": ["abc123"]
+}
+\`\`\`
+
+### Device Performance
+\`\`\`json
+{
+  "reportName": "Device Performance",
+  "dateRange": "Last14Days",
+  "dimensions": ["DeviceType", "CampaignName"],
+  "metrics": ["Impressions", "Clicks", "CTR", "TotalCost", "eCPM", "CPUR"],
+  "advertiserIds": ["abc123"]
+}
+\`\`\`
+
+### Video Campaign Completion Report
+\`\`\`json
+{
+  "reportName": "Video Completion",
+  "dateRange": "Last7Days",
+  "dimensions": ["CampaignId", "CampaignName", "AdGroupName"],
+  "metrics": ["VideoStarted", "VideoCompleted", "VCR", "CPCV", "TotalCost"],
+  "advertiserIds": ["abc123"]
+}
+\`\`\`
+
+### Geo Performance
+\`\`\`json
+{
+  "reportName": "Geo Performance",
+  "dateRange": "Last30Days",
+  "dimensions": ["Country", "Region", "CampaignName"],
+  "metrics": ["Impressions", "Clicks", "TotalCost", "CTR", "eCPM"],
+  "advertiserIds": ["abc123"]
+}
+\`\`\`
+
+### Conversion / ROAS Report
+\`\`\`json
+{
+  "reportName": "Conversion Analysis",
+  "dateRange": "Last30Days",
+  "dimensions": ["CampaignId", "CampaignName", "AdGroupName"],
+  "metrics": ["TotalConversions", "ClickConversions", "ViewConversions", "eCPA", "ROAS", "ConversionRevenue", "TotalCost"],
+  "advertiserIds": ["abc123"]
+}
+\`\`\`
+
+### Supply / Exchange Analysis
+\`\`\`json
+{
+  "reportName": "Supply Analysis",
+  "dateRange": "Last14Days",
+  "dimensions": ["SupplyVendor", "ChannelType", "CampaignName"],
+  "metrics": ["Impressions", "eCPM", "ViewableRate", "CTR"],
+  "advertiserIds": ["abc123"]
+}
+\`\`\`
+
+### Audience Segment Performance
+\`\`\`json
+{
+  "reportName": "Audience Performance",
+  "dateRange": "Last14Days",
+  "dimensions": ["AudienceId", "AudienceName", "CampaignName"],
+  "metrics": ["Impressions", "Clicks", "CTR", "TotalConversions", "eCPA"],
+  "advertiserIds": ["abc123"]
+}
+\`\`\`
+
+---
+
+## Tips
+
+- **Start small** — fewer dimensions = fewer rows = faster report.
+- **Always filter** — use \`advertiserIds\` to scope reports.
+- **Custom dates** — set \`ReportStartDate\` and \`ReportEndDate\` in \`additionalConfig\` (format: \`YYYY-MM-DDTHH:mm:ss\`).
+- **Download & inspect** — use \`ttd_download_report\` without row options first; it returns counts, headers, and a small preview.
+- **Narrow row payloads** — use \`mode: "rows"\`, \`columns\`, \`maxRows\`, and \`offset\` for paged access. \`maxRows\` is capped at 200 to avoid MCP response-size failures.
+- **Large reports** — may time out during polling or exceed useful response size. Use shorter date ranges, fewer dimensions, column projection, or pagination.
+- **V3 upgrade** — this reference covers MyReports V3 with 188 dimensions and 318 metrics. V2 had only 52 dimensions.
+`;
+}
+export const reportReferenceResource = {
+    uri: "report-reference://all",
+    name: "TTD Report Reference",
+    description: "Available report dimensions, metrics, date ranges, and common report combinations for TTD MyReports API",
+    mimeType: "text/markdown",
+    getContent: () => {
+        cachedContent ??= formatReportReferenceMarkdown();
+        return cachedContent;
+    },
+};
+//# sourceMappingURL=report-reference.resource.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report-reference.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/report-reference.resource.ts"],"names":[],"mappings":"AAWA,IAAI,aAAiC,CAAC;AAEtC,SAAS,6BAA6B;IACpC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoRR,CAAC;AACF,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAa;IAC/C,GAAG,EAAE,wBAAwB;IAC7B,IAAI,EAAE,sBAAsB;IAC5B,WAAW,EACT,yGAAyG;IAC3G,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/index.d.ts

@@ -0,0 +1,3 @@
+export type { Resource } from "./types.js";
+export { allResources } from "./definitions/index.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/resources/index.ts"],"names":[],"mappings":"AAOA,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}

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

@@ -0,0 +1,2 @@
+export { allResources } from "./definitions/index.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp-server/resources/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/mcp-server/resources/types.d.ts

@@ -0,0 +1,8 @@
+export interface Resource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    getContent: () => string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp-server/resources/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/resources/types.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,QAAQ;IAEvB,GAAG,EAAE,MAAM,CAAC;IAEZ,IAAI,EAAE,MAAM,CAAC;IAEb,WAAW,EAAE,MAAM,CAAC;IAEpB,QAAQ,EAAE,MAAM,CAAC;IAEjB,UAAU,EAAE,MAAM,MAAM,CAAC;CAC1B"}

package/dist/mcp-server/resources/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp-server/resources/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/mcp-server/resources/types.ts"],"names":[],"mappings":""}

package/dist/mcp-server/resources/utils/field-rules.d.ts

@@ -0,0 +1,18 @@
+import type { FieldRule } from "@cesteral/shared";
+import type { TtdEntityType } from "../../tools/utils/entity-mapping.js";
+export declare const PACING_MODES: readonly ["Off", "PaceAhead"];
+export declare const AVAILABILITY: readonly ["Available", "Archived"];
+export declare const TRACKING_TAG_TYPES: readonly ["Universal", "Standard", "Pixel", "JavaScript", "ServerToServer"];
+export declare const COMMON_CURRENCIES: readonly ["USD", "EUR", "GBP", "JPY", "CAD", "AUD", "SGD", "CHF", "SEK", "NOK", "DKK", "MXN", "BRL", "INR", "CNY", "HKD", "NZD", "ZAR"];
+export declare const REQUIRED_FIELDS_CREATE: Record<TtdEntityType, FieldRule[]>;
+export declare const OPTIONAL_ENUM_FIELDS: Record<TtdEntityType, FieldRule[]>;
+export declare const READ_ONLY_FIELDS: string[];
+export declare const POSITIVE_NUMBER_FIELDS: string[];
+export interface TtdEntityFieldRules {
+    entityType: TtdEntityType;
+    requiredOnCreate: FieldRule[];
+    optionalEnums: FieldRule[];
+    readOnlyFields: string[];
+}
+export declare function getFieldRulesForEntity(entityType: TtdEntityType): TtdEntityFieldRules;
+//# sourceMappingURL=field-rules.d.ts.map

package/dist/mcp-server/resources/utils/field-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-rules.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/field-rules.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAKzE,eAAO,MAAM,YAAY,+BAAgC,CAAC;AAC1D,eAAO,MAAM,YAAY,oCAAqC,CAAC;AAC/D,eAAO,MAAM,kBAAkB,6EAMrB,CAAC;AACX,eAAO,MAAM,iBAAiB,yIAmBpB,CAAC;AAEX,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,aAAa,EAAE,SAAS,EAAE,CAyCrE,CAAC;AAGF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,aAAa,EAAE,SAAS,EAAE,CAkCnE,CAAC;AAGF,eAAO,MAAM,gBAAgB,UAAuC,CAAC;AAGrE,eAAO,MAAM,sBAAsB,UAAa,CAAC;AAMjD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,aAAa,CAAC;IAC1B,gBAAgB,EAAE,SAAS,EAAE,CAAC;IAC9B,aAAa,EAAE,SAAS,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,aAAa,GAAG,mBAAmB,CAOrF"}

package/dist/mcp-server/resources/utils/field-rules.js

@@ -0,0 +1,117 @@
+export const PACING_MODES = ["Off", "PaceAhead"];
+export const AVAILABILITY = ["Available", "Archived"];
+export const TRACKING_TAG_TYPES = [
+    "Universal",
+    "Standard",
+    "Pixel",
+    "JavaScript",
+    "ServerToServer",
+];
+export const COMMON_CURRENCIES = [
+    "USD",
+    "EUR",
+    "GBP",
+    "JPY",
+    "CAD",
+    "AUD",
+    "SGD",
+    "CHF",
+    "SEK",
+    "NOK",
+    "DKK",
+    "MXN",
+    "BRL",
+    "INR",
+    "CNY",
+    "HKD",
+    "NZD",
+    "ZAR",
+];
+export const REQUIRED_FIELDS_CREATE = {
+    advertiser: [
+        { field: "PartnerId", expectedType: "string" },
+        { field: "AdvertiserName", expectedType: "string" },
+        {
+            field: "CurrencyCode",
+            expectedType: "string",
+            hint: "ISO 4217 currency code",
+            suggestedValues: COMMON_CURRENCIES,
+        },
+    ],
+    campaign: [
+        { field: "AdvertiserId", expectedType: "string" },
+        { field: "CampaignName", expectedType: "string" },
+        { field: "Budget", expectedType: "object", hint: "{ Amount, CurrencyCode }" },
+        { field: "StartDate", expectedType: "string", hint: "ISO-8601 datetime" },
+        {
+            field: "PacingMode",
+            expectedType: "string",
+            hint: "Budget pacing strategy",
+            suggestedValues: PACING_MODES,
+        },
+    ],
+    adGroup: [
+        { field: "AdvertiserId", expectedType: "string" },
+        { field: "CampaignId", expectedType: "string" },
+        { field: "AdGroupName", expectedType: "string" },
+        {
+            field: "RTBAttributes",
+            expectedType: "object",
+            hint: "must contain BudgetSettings and BaseBidCPM",
+        },
+    ],
+    creative: [
+        { field: "AdvertiserId", expectedType: "string" },
+        { field: "CreativeName", expectedType: "string" },
+    ],
+    conversionTracker: [
+        { field: "AdvertiserId", expectedType: "string" },
+        { field: "TrackingTagName", expectedType: "string" },
+    ],
+};
+export const OPTIONAL_ENUM_FIELDS = {
+    advertiser: [
+        {
+            field: "Availability",
+            expectedType: "string",
+            hint: "Advertiser availability state",
+            suggestedValues: AVAILABILITY,
+        },
+    ],
+    campaign: [
+        {
+            field: "Availability",
+            expectedType: "string",
+            hint: "Campaign availability state",
+            suggestedValues: AVAILABILITY,
+        },
+    ],
+    adGroup: [
+        {
+            field: "Availability",
+            expectedType: "string",
+            hint: "Ad group availability state",
+            suggestedValues: AVAILABILITY,
+        },
+    ],
+    creative: [],
+    conversionTracker: [
+        {
+            field: "TrackingTagType",
+            expectedType: "string",
+            hint: "Conversion tracker tag type",
+            suggestedValues: TRACKING_TAG_TYPES,
+        },
+    ],
+};
+export const READ_ONLY_FIELDS = ["CreatedAtUtc", "LastUpdatedAtUtc"];
+export const POSITIVE_NUMBER_FIELDS = ["Amount"];
+export function getFieldRulesForEntity(entityType) {
+    return {
+        entityType,
+        requiredOnCreate: REQUIRED_FIELDS_CREATE[entityType] ?? [],
+        optionalEnums: OPTIONAL_ENUM_FIELDS[entityType] ?? [],
+        readOnlyFields: READ_ONLY_FIELDS,
+    };
+}
+//# sourceMappingURL=field-rules.js.map

package/dist/mcp-server/resources/utils/field-rules.js.map

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

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

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Logger } from "pino";
+export declare function createMcpServer(logger: Logger, sessionId?: string, gcsBucket?: string): Promise<McpServer>;
+export declare function runStdioServer(server: McpServer, logger: Logger): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp-server/server.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AAqBtF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAwDnC,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,SAAS,CAAC,CA4IpB;AAKD,wBAAsB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrF"}

package/dist/mcp-server/server.js

@@ -0,0 +1,162 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { allTools } from "./tools/index.js";
+import { allResources } from "./resources/index.js";
+import { fieldRulesResource } from "./resources/definitions/field-rules.resource.js";
+import { promptRegistry } from "./prompts/index.js";
+import { createOperationContext } from "@cesteral/shared";
+import { reportCsvStore, sessionServiceStore } from "../services/session-services.js";
+import { extractZodShape, registerReportCsvResource, registerToolsFromDefinitions, registerPromptsFromDefinitions, registerStaticResourcesFromDefinitions, registerTemplatedResourcesFromDefinitions, InteractionLogger, isConformanceFixturesEnabled, } from "@cesteral/shared";
+import packageJson from "../../package.json" with { type: "json" };
+const TTD_PACKAGE_NAME = "ttd-mcp";
+const TTD_PLATFORM = "ttd";
+const ttdWorkflowIdByToolName = {
+    ttd_get_context: "mcp.execute.ttd_entity_read",
+    ttd_list_entities: "mcp.execute.ttd_entity_read",
+    ttd_get_entity: "mcp.execute.ttd_entity_read",
+    ttd_create_entity: "mcp.execute.ttd_entity_update",
+    ttd_update_entity: "mcp.execute.ttd_entity_update",
+    ttd_delete_entity: "mcp.execute.ttd_entity_update",
+    ttd_validate_entity: "mcp.execute.ttd_entity_update",
+    ttd_get_report: "mcp.execute.ttd_reporting",
+    ttd_submit_report: "mcp.execute.ttd_reporting",
+    ttd_check_report_status: "mcp.execute.ttd_reporting",
+    ttd_download_report: "mcp.execute.ttd_reporting",
+    ttd_bulk_create_entities: "mcp.execute.ttd_bulk_operations",
+    ttd_bulk_update_entities: "mcp.execute.ttd_bulk_operations",
+    ttd_bulk_update_status: "mcp.execute.ttd_bulk_operations",
+    ttd_archive_entities: "mcp.execute.ttd_bulk_operations",
+    ttd_adjust_bids: "mcp.execute.ttd_bulk_operations",
+    ttd_graphql_query: "mcp.execute.ttd_graphql",
+    ttd_graphql_query_bulk: "mcp.execute.ttd_graphql",
+    ttd_graphql_mutation_bulk: "mcp.execute.ttd_graphql",
+    ttd_graphql_bulk_job: "mcp.execute.ttd_graphql",
+    ttd_graphql_cancel_bulk_job: "mcp.execute.ttd_graphql",
+    ttd_create_report_template: "mcp.execute.ttd_reporting",
+    ttd_update_report_template: "mcp.execute.ttd_reporting",
+    ttd_get_report_template: "mcp.execute.ttd_reporting",
+    ttd_list_report_templates: "mcp.execute.ttd_reporting",
+    ttd_create_template_schedule: "mcp.execute.ttd_reporting",
+    ttd_create_report_schedule: "mcp.execute.ttd_reporting",
+    ttd_update_report_schedule: "mcp.execute.ttd_reporting",
+    ttd_list_report_schedules: "mcp.execute.ttd_reporting",
+    ttd_get_report_schedule: "mcp.execute.ttd_reporting",
+    ttd_delete_report_schedule: "mcp.execute.ttd_reporting",
+    ttd_cancel_report_execution: "mcp.execute.ttd_reporting",
+    ttd_rerun_report_schedule: "mcp.execute.ttd_reporting",
+    ttd_get_report_executions: "mcp.execute.ttd_reporting",
+    ttd_execute_entity_report: "mcp.execute.ttd_reporting",
+    ttd_get_entity_report_types: "mcp.execute.ttd_reporting",
+    ttd_get_ad_preview: "mcp.execute.ttd_entity_read",
+};
+export async function createMcpServer(logger, sessionId, gcsBucket) {
+    const server = new McpServer({
+        name: "ttd-mcp",
+        version: packageJson.version,
+        description: "The Trade Desk campaign management, reporting, and optimization via TTD's documented Platform API (REST v3 + GraphQL). Supports first-class CRUD entities, GraphQL bulk operations for >100-record writes, and async report generation.",
+    }, {
+        capabilities: {
+            logging: {},
+        },
+        instructions: "The Trade Desk campaign management and reporting server. Surfaces TTD's documented Platform API only (REST + GraphQL per TTD Foundations §1, §6). " +
+            "Progressive discovery: (1) start with ttd_get_context to resolve partner/advertiser IDs for the current credentials, then ttd_list_entities for entity discovery; " +
+            "(2) before authoring writes, read MCP Resources entity-schema://all for field shapes, entity-hierarchy://all for parent/child rules, entity-examples://all for payload examples, graphql-reference://ttd for GraphQL passthrough, and report-reference://all for MyReports field semantics; " +
+            "(3) for multi-step flows use MCP Prompts: ttd_campaign_setup_workflow, ttd_targeting_discovery_workflow, ttd_entity_update_workflow, ttd_bulk_operations_workflow, ttd_entity_duplication_workflow. " +
+            "For single-record writes use ttd_create_entity / ttd_update_entity (REST). For >100-record batch writes use ttd_graphql_mutation_bulk (TTD's documented bulk path).",
+    });
+    const interactionLogger = new InteractionLogger({
+        serverName: TTD_PACKAGE_NAME,
+        logger,
+        gcsBucket,
+    });
+    registerToolsFromDefinitions({
+        server,
+        tools: allTools,
+        logger,
+        sessionId,
+        transformSchema: (schema) => extractZodShape(schema),
+        createRequestContext: (params) => createOperationContext({
+            operation: params.operation,
+            additionalContext: params.additionalContext,
+        }),
+        defaultTextFormat: "compact",
+        packageName: TTD_PACKAGE_NAME,
+        platform: TTD_PLATFORM,
+        workflowIdByToolName: ttdWorkflowIdByToolName,
+        interactionLogger,
+        authContextResolver: sessionId
+            ? () => sessionServiceStore.getAuthContext(sessionId)
+            : undefined,
+    });
+    registerStaticResourcesFromDefinitions({
+        server,
+        resources: allResources,
+        logger,
+    });
+    registerTemplatedResourcesFromDefinitions({
+        server,
+        templateBuilder: (uriTemplate, options) => new ResourceTemplate(uriTemplate, options),
+        resources: [fieldRulesResource],
+        logger,
+    });
+    registerReportCsvResource({
+        server,
+        ResourceTemplate,
+        store: reportCsvStore,
+        platform: "TTD",
+        downloadToolName: "ttd_download_report",
+        logger,
+    });
+    if (isConformanceFixturesEnabled()) {
+        const { conformanceResources, conformanceResourceTemplate, conformancePrompts } = await import("@cesteral/shared");
+        const { ResourceTemplate: McpResourceTemplate } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+        registerStaticResourcesFromDefinitions({
+            server,
+            resources: conformanceResources,
+            logger,
+        });
+        const template = new McpResourceTemplate(conformanceResourceTemplate.uriTemplate, {
+            list: undefined,
+        });
+        server.registerResource("conformance_template", template, {
+            description: conformanceResourceTemplate.description,
+            mimeType: conformanceResourceTemplate.mimeType,
+        }, async (uri, variables) => {
+            const id = variables.id || "unknown";
+            const content = conformanceResourceTemplate.getContent(id);
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: conformanceResourceTemplate.mimeType,
+                        text: content,
+                    },
+                ],
+            };
+        });
+        registerPromptsFromDefinitions({
+            server: server,
+            prompts: conformancePrompts,
+            logger,
+        });
+    }
+    const allPrompts = Array.from(promptRegistry.values()).map((def) => ({
+        name: def.prompt.name,
+        description: def.prompt.description ?? "",
+        arguments: def.prompt.arguments,
+        generateMessage: def.generateMessage,
+    }));
+    registerPromptsFromDefinitions({
+        server: server,
+        prompts: allPrompts,
+        logger,
+    });
+    return server;
+}
+export async function runStdioServer(server, logger) {
+    logger.info("Starting MCP server with stdio transport");
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("MCP server connected via stdio");
+}
+//# sourceMappingURL=server.js.map

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

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