@cesteral/meta-mcp 1.0.0

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

@@ -0,0 +1,113 @@
+export const insightsReferenceResource = {
+    uri: "insights-reference://all",
+    name: "Meta Insights Reference",
+    description: "Metrics, breakdowns, date presets, and attribution windows for Meta Ads Insights API",
+    mimeType: "text/markdown",
+    getContent: () => `# Meta Insights API Reference
+
+## Common Metrics (fields)
+
+| Metric | Description |
+|--------|-------------|
+| impressions | Total impressions |
+| clicks | Total clicks |
+| spend | Total spend (in account currency) |
+| cpc | Cost per click |
+| cpm | Cost per 1000 impressions |
+| ctr | Click-through rate |
+| reach | Unique people reached |
+| frequency | Average frequency |
+| actions | Action totals (purchases, leads, etc.) |
+| action_values | Monetary values of actions |
+| conversions | Total conversions |
+| cost_per_action_type | Cost per action by type |
+| unique_clicks | Unique clicks |
+| unique_ctr | Unique click-through rate |
+| video_avg_time_watched_actions | Avg video watch time |
+| video_p25_watched_actions | 25% video completions |
+| video_p50_watched_actions | 50% video completions |
+| video_p75_watched_actions | 75% video completions |
+| video_p100_watched_actions | 100% video completions |
+
+## Date Presets
+
+| Preset | Description |
+|--------|-------------|
+| today | Today |
+| yesterday | Yesterday |
+| this_month | Current month |
+| last_month | Previous month |
+| this_quarter | Current quarter |
+| last_quarter | Previous quarter |
+| this_year | Current year |
+| last_year | Previous year |
+| last_3d | Last 3 days |
+| last_7d | Last 7 days |
+| last_14d | Last 14 days |
+| last_28d | Last 28 days |
+| last_30d | Last 30 days |
+| last_90d | Last 90 days |
+| this_week_mon_today | This week (Monday to today) |
+| this_week_sun_today | This week (Sunday to today) |
+| last_week_mon_sun | Last week (Monday to Sunday) |
+| last_week_sun_sat | Last week (Sunday to Saturday) |
+| maximum | Maximum available range (up to 37 months) |
+| data_maximum | Maximum range with available data |
+
+## Custom Date Range
+
+Use \`time_range\` parameter:
+\`\`\`json
+{ "since": "2026-01-01", "until": "2026-01-31" }
+\`\`\`
+
+## Time Increments
+
+| Value | Description |
+|-------|-------------|
+| 1 | Daily |
+| 7 | Weekly |
+| monthly | Monthly |
+| all_days | All days aggregated |
+
+## Breakdowns
+
+### Demographic
+- \`age\` — Age ranges (18-24, 25-34, etc.)
+- \`gender\` — Male, Female, Unknown
+
+### Geographic
+- \`country\` — Country
+- \`region\` — State/Region
+- \`dma\` — Designated Market Area
+
+### Platform/Device
+- \`device_platform\` — Mobile, Desktop
+- \`platform_position\` — Feed, Stories, etc.
+- \`publisher_platform\` — Facebook, Instagram, Audience Network
+
+### Valid Combinations
+- age + gender ✓
+- country alone ✓
+- country + region ✗ (same dimension)
+- device_platform + publisher_platform ✓
+
+## Attribution Windows
+
+| Window | Description |
+|--------|-------------|
+| 1d_click | 1-day click attribution |
+| 7d_click | 7-day click attribution (default) |
+| 1d_view | 1-day view attribution |
+| 7d_view | 7-day view attribution |
+
+## Gotchas
+
+- Data may lag up to **48 hours**
+- Max date range: **37 months**
+- Limit ~**20 metrics** per call for performance
+- Results are **cursor-paginated** (use \`after\` param)
+- \`level\` parameter aggregates across hierarchy (campaign, adset, ad)
+`,
+};
+//# sourceMappingURL=insights-reference.resource.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"insights-reference.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/insights-reference.resource.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,yBAAyB,GAAa;IACjD,GAAG,EAAE,0BAA0B;IAC/B,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EACT,sFAAsF;IACxF,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyGnB;CACA,CAAC"}

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

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

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

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

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

@@ -0,0 +1,98 @@
+export const targetingReferenceResource = {
+    uri: "targeting-reference://all",
+    name: "Meta Targeting Reference",
+    description: "Targeting specification structure, search types, and patterns for Meta Ads",
+    mimeType: "text/markdown",
+    getContent: () => `# Meta Targeting Reference
+
+## Targeting Spec Structure
+
+\`\`\`json
+{
+  "age_min": 18,
+  "age_max": 65,
+  "genders": [1, 2],
+  "geo_locations": {
+    "countries": ["US"],
+    "regions": [{ "key": "4081" }],
+    "cities": [{ "key": "2420379" }],
+    "zips": [{ "key": "US:10001" }]
+  },
+  "interests": [
+    { "id": "6003139266461", "name": "Fitness and wellness" }
+  ],
+  "flexible_spec": [
+    { "interests": [{ "id": "6003371567474" }] },
+    { "behaviors": [{ "id": "6002714895372" }] }
+  ],
+  "exclusions": {
+    "interests": [{ "id": "6003384285372" }]
+  },
+  "custom_audiences": [{ "id": "AUDIENCE_ID" }],
+  "excluded_custom_audiences": [{ "id": "AUDIENCE_ID" }],
+  "targeting_automation": { "advantage_audience": 0 }
+}
+\`\`\`
+
+## Targeting Search Types
+
+Use \`meta_search_targeting\` with these types:
+
+| Type | Description | Example Query |
+|------|-------------|---------------|
+| adinterest | Search interests | "running shoes" |
+| adinterestsuggestion | Get suggestions | (uses interest_list) |
+| adinterestvalid | Validate interests | (uses interest IDs) |
+| adbehavior | Search behaviors | "purchase" |
+| adTargetingCategory | Browse categories | "behaviors" |
+| adgeolocation | Search locations | "New York" |
+| adlocale | Search languages | "English" |
+
+## Gender Values
+- 1 = Male
+- 2 = Female
+
+## Targeting Automation (Advantage+)
+- \`targeting_automation.advantage_audience\`: 0 = disabled, 1 = enabled
+- API v21+ may require this field
+- When enabled, requires \`age_max >= 65\`
+
+## Key Targeting Patterns
+
+### Interest OR Logic (flexible_spec)
+Each array element in \`flexible_spec\` is OR'd together:
+\`\`\`json
+{
+  "flexible_spec": [
+    { "interests": [{ "id": "A" }, { "id": "B" }] },
+    { "behaviors": [{ "id": "C" }] }
+  ]
+}
+\`\`\`
+Matches: (Interest A OR Interest B) AND (Behavior C)
+
+### Exclusion Targeting
+\`\`\`json
+{
+  "exclusions": {
+    "interests": [{ "id": "6003384285372" }]
+  }
+}
+\`\`\`
+
+### Custom Audience + Exclusion
+\`\`\`json
+{
+  "custom_audiences": [{ "id": "INCLUDE_ID" }],
+  "excluded_custom_audiences": [{ "id": "EXCLUDE_ID" }]
+}
+\`\`\`
+
+## Important Notes
+
+- \`targeting\` field on ad set **replaces entirely** (no merge with existing)
+- Always include \`geo_locations\` or \`custom_audiences\` (at least one required)
+- Interest IDs must be valid Meta IDs (use \`meta_search_targeting\` to find them)
+`,
+};
+//# sourceMappingURL=targeting-reference.resource.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"targeting-reference.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/targeting-reference.resource.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,0BAA0B,GAAa;IAClD,GAAG,EAAE,2BAA2B;IAChC,IAAI,EAAE,0BAA0B;IAChC,WAAW,EAAE,4EAA4E;IACzF,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0FnB;CACA,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 { MetaEntityType } from "../../tools/utils/entity-mapping.js";
+export declare const CAMPAIGN_OBJECTIVES: readonly ["OUTCOME_AWARENESS", "OUTCOME_TRAFFIC", "OUTCOME_ENGAGEMENT", "OUTCOME_LEADS", "OUTCOME_APP_PROMOTION", "OUTCOME_SALES"];
+export declare const STATUS_VALUES: readonly ["ACTIVE", "PAUSED", "DELETED", "ARCHIVED"];
+export declare const ADSET_OPTIMIZATION_GOALS: readonly ["LINK_CLICKS", "IMPRESSIONS", "REACH", "POST_ENGAGEMENT", "OFFSITE_CONVERSIONS", "VALUE", "THRUPLAY"];
+export declare const ADSET_BILLING_EVENTS: readonly ["IMPRESSIONS", "LINK_CLICKS", "THRUPLAY"];
+export declare const CUSTOM_AUDIENCE_SUBTYPES: readonly ["CUSTOM", "LOOKALIKE", "WEBSITE", "APP", "ENGAGEMENT"];
+export declare const REQUIRED_FIELDS_CREATE: Record<MetaEntityType, FieldRule[]>;
+export declare const READ_ONLY_FIELDS: string[];
+export declare const BUDGET_FIELDS: string[];
+export interface MetaEntityFieldRules {
+    entityType: MetaEntityType;
+    requiredOnCreate: FieldRule[];
+    readOnlyFields: string[];
+    budgetFields: string[];
+}
+export declare function getFieldRulesForEntity(entityType: MetaEntityType): MetaEntityFieldRules;
+//# 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,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAE1E,eAAO,MAAM,mBAAmB,oIAOtB,CAAC;AACX,eAAO,MAAM,aAAa,sDAAuD,CAAC;AAClF,eAAO,MAAM,wBAAwB,iHAQ3B,CAAC;AACX,eAAO,MAAM,oBAAoB,qDAAsD,CAAC;AACxF,eAAO,MAAM,wBAAwB,kEAM3B,CAAC;AAEX,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,cAAc,EAAE,SAAS,EAAE,CA2DtE,CAAC;AAGF,eAAO,MAAM,gBAAgB,UAM5B,CAAC;AAGF,eAAO,MAAM,aAAa,UAAoD,CAAC;AAM/E,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,cAAc,CAAC;IAC3B,gBAAgB,EAAE,SAAS,EAAE,CAAC;IAC9B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,cAAc,GAAG,oBAAoB,CAOvF"}

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

@@ -0,0 +1,103 @@
+export const CAMPAIGN_OBJECTIVES = [
+    "OUTCOME_AWARENESS",
+    "OUTCOME_TRAFFIC",
+    "OUTCOME_ENGAGEMENT",
+    "OUTCOME_LEADS",
+    "OUTCOME_APP_PROMOTION",
+    "OUTCOME_SALES",
+];
+export const STATUS_VALUES = ["ACTIVE", "PAUSED", "DELETED", "ARCHIVED"];
+export const ADSET_OPTIMIZATION_GOALS = [
+    "LINK_CLICKS",
+    "IMPRESSIONS",
+    "REACH",
+    "POST_ENGAGEMENT",
+    "OFFSITE_CONVERSIONS",
+    "VALUE",
+    "THRUPLAY",
+];
+export const ADSET_BILLING_EVENTS = ["IMPRESSIONS", "LINK_CLICKS", "THRUPLAY"];
+export const CUSTOM_AUDIENCE_SUBTYPES = [
+    "CUSTOM",
+    "LOOKALIKE",
+    "WEBSITE",
+    "APP",
+    "ENGAGEMENT",
+];
+export const REQUIRED_FIELDS_CREATE = {
+    campaign: [
+        { field: "name", expectedType: "string" },
+        {
+            field: "objective",
+            expectedType: "string",
+            hint: "e.g., OUTCOME_AWARENESS, OUTCOME_TRAFFIC",
+            suggestedValues: CAMPAIGN_OBJECTIVES,
+        },
+        {
+            field: "special_ad_categories",
+            expectedType: "array",
+            hint: "must be an array (can be empty [])",
+        },
+    ],
+    adSet: [
+        { field: "name", expectedType: "string" },
+        { field: "campaign_id", expectedType: "string" },
+        {
+            field: "optimization_goal",
+            expectedType: "string",
+            hint: "e.g., LINK_CLICKS, IMPRESSIONS",
+            suggestedValues: ADSET_OPTIMIZATION_GOALS,
+        },
+        {
+            field: "billing_event",
+            expectedType: "string",
+            hint: "e.g., IMPRESSIONS, LINK_CLICKS",
+            suggestedValues: ADSET_BILLING_EVENTS,
+        },
+        { field: "targeting", expectedType: "object", hint: "must be an object with targeting spec" },
+        {
+            field: "status",
+            expectedType: "string",
+            hint: "e.g., PAUSED, ACTIVE",
+            suggestedValues: STATUS_VALUES,
+        },
+    ],
+    ad: [
+        { field: "name", expectedType: "string" },
+        { field: "adset_id", expectedType: "string" },
+        { field: "creative", expectedType: "object", hint: "must be an object with creative_id" },
+        {
+            field: "status",
+            expectedType: "string",
+            hint: "e.g., PAUSED, ACTIVE",
+            suggestedValues: STATUS_VALUES,
+        },
+    ],
+    adCreative: [{ field: "name", expectedType: "string" }],
+    customAudience: [
+        { field: "name", expectedType: "string" },
+        {
+            field: "subtype",
+            expectedType: "string",
+            hint: "e.g., CUSTOM, LOOKALIKE, WEBSITE",
+            suggestedValues: CUSTOM_AUDIENCE_SUBTYPES,
+        },
+    ],
+};
+export const READ_ONLY_FIELDS = [
+    "id",
+    "created_time",
+    "updated_time",
+    "time_created",
+    "time_updated",
+];
+export const BUDGET_FIELDS = ["daily_budget", "lifetime_budget", "bid_amount"];
+export function getFieldRulesForEntity(entityType) {
+    return {
+        entityType,
+        requiredOnCreate: REQUIRED_FIELDS_CREATE[entityType] ?? [],
+        readOnlyFields: READ_ONLY_FIELDS,
+        budgetFields: BUDGET_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;AAoBtF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAmCnC,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,SAAS,CAAC,CAgIpB;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,133 @@
+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 { sessionServiceStore } from "../services/session-services.js";
+import { extractZodShape, registerToolsFromDefinitions, registerPromptsFromDefinitions, registerStaticResourcesFromDefinitions, registerTemplatedResourcesFromDefinitions, InteractionLogger, isConformanceFixturesEnabled, } from "@cesteral/shared";
+import packageJson from "../../package.json" with { type: "json" };
+const META_PACKAGE_NAME = "meta-mcp";
+const META_PLATFORM = "meta";
+const metaWorkflowIdByToolName = {
+    meta_list_entities: "mcp.execute.meta_entity_read",
+    meta_get_entity: "mcp.execute.meta_entity_read",
+    meta_list_ad_accounts: "mcp.execute.meta_entity_read",
+    meta_create_entity: "mcp.execute.meta_entity_update",
+    meta_update_entity: "mcp.execute.meta_entity_update",
+    meta_delete_entity: "mcp.execute.meta_entity_update",
+    meta_get_insights: "mcp.execute.meta_insights",
+    meta_get_insights_breakdowns: "mcp.execute.meta_insights",
+    meta_bulk_update_status: "mcp.execute.meta_bulk_operations",
+    meta_bulk_create_entities: "mcp.execute.meta_bulk_operations",
+    meta_search_targeting: "mcp.execute.meta_entity_read",
+    meta_get_targeting_options: "mcp.execute.meta_entity_read",
+    meta_duplicate_entity: "mcp.execute.meta_entity_update",
+    meta_get_delivery_estimate: "mcp.execute.meta_entity_read",
+    meta_get_ad_preview: "mcp.execute.meta_entity_read",
+    meta_validate_entity: "mcp.execute.meta_entity_read",
+    meta_adjust_bids: "mcp.execute.meta_bulk_operations",
+};
+export async function createMcpServer(logger, sessionId, gcsBucket) {
+    const server = new McpServer({
+        name: "meta-mcp",
+        version: packageJson.version,
+        description: "Meta Ads campaign management, reporting, and optimization via the configured Meta Graph API (default: v25.0). Supports 5 entity types (campaign, adSet, ad, adCreative, customAudience), insights with breakdowns, bulk operations, targeting search, entity duplication, delivery estimates, and ad previews.",
+    }, {
+        capabilities: {
+            logging: {},
+        },
+        instructions: "Meta Ads campaign management server. Supports 5 entity types (campaign, adSet, ad, adCreative, customAudience), insights, targeting, and bulk operations via the configured Meta Graph API (default: v25.0). " +
+            "Progressive discovery: (1) start with meta_list_ad_accounts to resolve accessible account IDs, then meta_list_entities to browse campaigns/adSets/ads (always pass `fields` — Graph API returns nothing by default); " +
+            "(2) before authoring writes, read MCP Resources entity-schema://all for field shapes, entity-hierarchy://all for campaign→adSet→ad rules, entity-examples://all for payloads, targeting-reference://all for targeting spec, and insights-reference://all for metrics/breakdowns; " +
+            "(3) for multi-step flows use MCP Prompts: meta_insights_reporting_workflow, meta_targeting_discovery_workflow, meta_entity_update_workflow, meta_bulk_operations_workflow, meta_entity_duplication_workflow.",
+    });
+    const interactionLogger = new InteractionLogger({
+        serverName: META_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: META_PACKAGE_NAME,
+        platform: META_PLATFORM,
+        workflowIdByToolName: metaWorkflowIdByToolName,
+        interactionLogger,
+        authContextResolver: sessionId
+            ? () => sessionServiceStore.getAuthContext(sessionId)
+            : undefined,
+    });
+    registerStaticResourcesFromDefinitions({
+        server,
+        resources: allResources,
+        logger,
+    });
+    registerTemplatedResourcesFromDefinitions({
+        server,
+        templateBuilder: (uriTemplate, options) => new ResourceTemplate(uriTemplate, options),
+        resources: [fieldRulesResource],
+        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":"AAGA,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,8BAA8B,EAC9B,sCAAsC,EACtC,yCAAyC,EACzC,iBAAiB,EACjB,4BAA4B,GAI7B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,WAAW,MAAM,oBAAoB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAEnE,MAAM,iBAAiB,GAAG,UAAU,CAAC;AACrC,MAAM,aAAa,GAAG,MAAM,CAAC;AAE7B,MAAM,wBAAwB,GAA2B;IAEvD,kBAAkB,EAAE,8BAA8B;IAClD,eAAe,EAAE,8BAA8B;IAC/C,qBAAqB,EAAE,8BAA8B;IAErD,kBAAkB,EAAE,gCAAgC;IACpD,kBAAkB,EAAE,gCAAgC;IACpD,kBAAkB,EAAE,gCAAgC;IAEpD,iBAAiB,EAAE,2BAA2B;IAC9C,4BAA4B,EAAE,2BAA2B;IAEzD,uBAAuB,EAAE,kCAAkC;IAC3D,yBAAyB,EAAE,kCAAkC;IAE7D,qBAAqB,EAAE,8BAA8B;IACrD,0BAA0B,EAAE,8BAA8B;IAE1D,qBAAqB,EAAE,gCAAgC;IACvD,0BAA0B,EAAE,8BAA8B;IAC1D,mBAAmB,EAAE,8BAA8B;IACnD,oBAAoB,EAAE,8BAA8B;IACpD,gBAAgB,EAAE,kCAAkC;CACrD,CAAC;AAKF,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAc,EACd,SAAkB,EAClB,SAAkB;IAElB,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,WAAW,CAAC,OAAO;QAC5B,WAAW,EACT,gTAAgT;KACnT,EACD;QACE,YAAY,EAAE;YACZ,OAAO,EAAE,EAAE;SACZ;QACD,YAAY,EACV,+MAA+M;YAC/M,uNAAuN;YACvN,mRAAmR;YACnR,8MAA8M;KACjN,CACF,CAAC;IAGF,MAAM,iBAAiB,GAAG,IAAI,iBAAiB,CAAC;QAC9C,UAAU,EAAE,iBAAiB;QAC7B,MAAM;QACN,SAAS;KACV,CAAC,CAAC;IAGH,4BAA4B,CAAC;QAC3B,MAAM;QACN,KAAK,EAAE,QAAQ;QACf,MAAM;QACN,SAAS;QACT,eAAe,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC;QACpD,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE,CAC/B,sBAAsB,CAAC;YACrB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;SAC5C,CAAC;QACJ,iBAAiB,EAAE,SAAS;QAC5B,WAAW,EAAE,iBAAiB;QAC9B,QAAQ,EAAE,aAAa;QACvB,oBAAoB,EAAE,wBAAwB;QAC9C,iBAAiB;QACjB,mBAAmB,EAAE,SAAS;YAC5B,CAAC,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,cAAc,CAAC,SAAS,CAAC;YACrD,CAAC,CAAC,SAAS;KACd,CAAC,CAAC;IAGH,sCAAsC,CAAC;QACrC,MAAM;QACN,SAAS,EAAE,YAAY;QACvB,MAAM;KACP,CAAC,CAAC;IAIH,yCAAyC,CAAC;QACxC,MAAM;QACN,eAAe,EAAE,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,gBAAgB,CAAC,WAAW,EAAE,OAAO,CAAC;QACrF,SAAS,EAAE,CAAC,kBAAkB,CAAC;QAC/B,MAAM;KACP,CAAC,CAAC;IAGH,IAAI,4BAA4B,EAAE,EAAE,CAAC;QACnC,MAAM,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAC5F,kBAAkB,CACnB,CAAC;QACF,MAAM,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAC5D,yCAAyC,CAC1C,CAAC;QAEF,sCAAsC,CAAC;YACrC,MAAM;YACN,SAAS,EAAE,oBAAoB;YAC/B,MAAM;SACP,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,IAAI,mBAAmB,CAAC,2BAA2B,CAAC,WAAW,EAAE;YAChF,IAAI,EAAE,SAAS;SAChB,CAAC,CAAC;QACH,MAAM,CAAC,gBAAgB,CACrB,sBAAsB,EACtB,QAAQ,EACR;YACE,WAAW,EAAE,2BAA2B,CAAC,WAAW;YACpD,QAAQ,EAAE,2BAA2B,CAAC,QAAQ;SAC/C,EACD,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE;YACvB,MAAM,EAAE,GAAI,SAAS,CAAC,EAAa,IAAI,SAAS,CAAC;YACjD,MAAM,OAAO,GAAG,2BAA2B,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YAC3D,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,GAAG,CAAC,IAAI;wBACb,QAAQ,EAAE,2BAA2B,CAAC,QAAQ;wBAC9C,IAAI,EAAE,OAAO;qBACd;iBACF;aACF,CAAC;QACJ,CAAC,CACF,CAAC;QAEF,8BAA8B,CAAC;YAC7B,MAAM,EAAE,MAAwC;YAChD,OAAO,EAAE,kBAAkB;YAC3B,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAGD,MAAM,UAAU,GAAiC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CACtF,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACR,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI;QACrB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE;QACzC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,SAAmD;QACzE,eAAe,EAAE,GAAG,CAAC,eAAe;KACrC,CAAC,CACH,CAAC;IACF,8BAA8B,CAAC;QAC7B,MAAM,EAAE,MAAwC;QAChD,OAAO,EAAE,UAAU;QACnB,MAAM;KACP,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAKD,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAiB,EAAE,MAAc;IACpE,MAAM,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;AAChD,CAAC"}