@cesteral/meta-mcp 1.0.0

package/dist/mcp-server/tools/definitions/get-entity.tool.d.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent, SdkContext } from "@cesteral/shared";
+export declare const GetEntityInputSchema: z.ZodObject<{
+    entityType: z.ZodEnum<[string, ...string[]]>;
+    entityId: z.ZodString;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    entityType: string;
+    entityId: string;
+    fields?: string[] | undefined;
+}, {
+    entityType: string;
+    entityId: string;
+    fields?: string[] | undefined;
+}>;
+export declare const GetEntityOutputSchema: z.ZodObject<{
+    entity: z.ZodRecord<z.ZodString, z.ZodAny>;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    timestamp: string;
+    entity: Record<string, any>;
+}, {
+    timestamp: string;
+    entity: Record<string, any>;
+}>;
+type GetEntityInput = z.infer<typeof GetEntityInputSchema>;
+type GetEntityOutput = z.infer<typeof GetEntityOutputSchema>;
+export declare function getEntityLogic(input: GetEntityInput, context: RequestContext, sdkContext?: SdkContext): Promise<GetEntityOutput>;
+export declare function getEntityResponseFormatter(result: GetEntityOutput): McpTextContent[];
+export declare const getEntityTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        entityType: z.ZodEnum<[string, ...string[]]>;
+        entityId: z.ZodString;
+        fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        entityType: string;
+        entityId: string;
+        fields?: string[] | undefined;
+    }, {
+        entityType: string;
+        entityId: string;
+        fields?: string[] | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        entity: z.ZodRecord<z.ZodString, z.ZodAny>;
+        timestamp: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        timestamp: string;
+        entity: Record<string, any>;
+    }, {
+        timestamp: string;
+        entity: Record<string, any>;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+        cesteral: {
+            kind: "read";
+            platform: string;
+            entityKinds: ("campaign" | "ad" | "ad_set")[];
+            entityIdArgs: string[];
+            schemaVersion: number;
+            contractId: string;
+        };
+    };
+    inputExamples: ({
+        label: string;
+        input: {
+            entityType: string;
+            entityId: string;
+            fields?: undefined;
+        };
+    } | {
+        label: string;
+        input: {
+            entityType: string;
+            entityId: string;
+            fields: string[];
+        };
+    })[];
+    logic: typeof getEntityLogic;
+    responseFormatter: typeof getEntityResponseFormatter;
+};
+export {};
+//# sourceMappingURL=get-entity.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-entity.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-entity.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,UAAU,EAEX,MAAM,kBAAkB,CAAC;AAU1B,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EASsB,CAAC;AAExD,eAAO,MAAM,qBAAqB;;;;;;;;;EAKI,CAAC;AAEvC,KAAK,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAC3D,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE7D,wBAAsB,cAAc,CAClC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,eAAe,CAAC,CAc1B;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,EAAE,CAOpF;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CzB,CAAC"}

package/dist/mcp-server/tools/definitions/get-entity.tool.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { getEntityTypeEnum } from "../utils/entity-mapping.js";
+const TOOL_NAME = "meta_get_entity";
+const TOOL_TITLE = "Get Meta Ads Entity";
+const TOOL_DESCRIPTION = `Get a single Meta Ads entity by ID.
+
+**Supported entity types:** ${getEntityTypeEnum().join(", ")}
+
+**Important:** Meta returns no fields by default. Specify \`fields\` or rely on defaults.`;
+export const GetEntityInputSchema = z
+    .object({
+    entityType: z.enum(getEntityTypeEnum()).describe("Type of entity to retrieve"),
+    entityId: z.string().min(1).describe("The entity ID to retrieve"),
+    fields: z
+        .array(z.string())
+        .optional()
+        .describe("Fields to return (defaults to common fields for the entity type)"),
+})
+    .describe("Parameters for getting a Meta Ads entity");
+export const GetEntityOutputSchema = z
+    .object({
+    entity: z.record(z.any()).describe("Retrieved entity data"),
+    timestamp: z.string().datetime(),
+})
+    .describe("Entity retrieval result");
+export async function getEntityLogic(input, context, sdkContext) {
+    const { metaService } = resolveSessionServices(sdkContext);
+    const entity = await metaService.getEntity(input.entityType, input.entityId, input.fields, context);
+    return {
+        entity: entity,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function getEntityResponseFormatter(result) {
+    return [
+        {
+            type: "text",
+            text: `Entity retrieved\n${JSON.stringify(result.entity, null, 2)}\n\nTimestamp: ${result.timestamp}`,
+        },
+    ];
+}
+export const getEntityTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: GetEntityInputSchema,
+    outputSchema: GetEntityOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        idempotentHint: true,
+        destructiveHint: false,
+        cesteral: {
+            kind: "read",
+            platform: "meta_ads",
+            entityKinds: ["campaign", "ad_set", "ad"],
+            entityIdArgs: ["entityId"],
+            schemaVersion: 1,
+            contractId: "meta.get_entity.v1",
+        },
+    },
+    inputExamples: [
+        {
+            label: "Get a campaign by ID",
+            input: {
+                entityType: "campaign",
+                entityId: "23456789012345",
+            },
+        },
+        {
+            label: "Get an ad set with specific fields",
+            input: {
+                entityType: "adSet",
+                entityId: "23456789012345",
+                fields: ["id", "name", "status", "targeting", "daily_budget"],
+            },
+        },
+    ],
+    logic: getEntityLogic,
+    responseFormatter: getEntityResponseFormatter,
+};
+//# sourceMappingURL=get-entity.tool.js.map

package/dist/mcp-server/tools/definitions/get-entity.tool.js.map

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

package/dist/mcp-server/tools/definitions/get-insights-breakdowns.tool.d.ts

@@ -0,0 +1,277 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const GetInsightsBreakdownsInputSchema: z.ZodObject<{
+    entityId: z.ZodString;
+    breakdowns: z.ZodArray<z.ZodString, "many">;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    datePreset: z.ZodOptional<z.ZodString>;
+    timeRange: z.ZodOptional<z.ZodObject<{
+        since: z.ZodString;
+        until: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        since: string;
+        until: string;
+    }, {
+        since: string;
+        until: string;
+    }>>;
+    timeIncrement: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodString>;
+    actionAttributionWindows: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    includeComputedMetrics: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+} & {
+    mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["summary", "rows"]>>>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    maxRows: z.ZodOptional<z.ZodNumber>;
+    aggregateBy: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aggregateMetrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["sum", "avg", "count", "min", "max"]>>>;
+}, "strip", z.ZodTypeAny, {
+    entityId: string;
+    breakdowns: string[];
+    includeComputedMetrics: boolean;
+    mode: "summary" | "rows";
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    datePreset?: string | undefined;
+    level?: string | undefined;
+    timeRange?: {
+        since: string;
+        until: string;
+    } | undefined;
+    timeIncrement?: string | undefined;
+    columns?: string[] | undefined;
+    offset?: number | undefined;
+    maxRows?: number | undefined;
+    aggregateBy?: string[] | undefined;
+    aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+    actionAttributionWindows?: string[] | undefined;
+}, {
+    entityId: string;
+    breakdowns: string[];
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    datePreset?: string | undefined;
+    level?: string | undefined;
+    timeRange?: {
+        since: string;
+        until: string;
+    } | undefined;
+    timeIncrement?: string | undefined;
+    includeComputedMetrics?: boolean | undefined;
+    mode?: "summary" | "rows" | undefined;
+    columns?: string[] | undefined;
+    offset?: number | undefined;
+    maxRows?: number | undefined;
+    aggregateBy?: string[] | undefined;
+    aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+    actionAttributionWindows?: string[] | undefined;
+}>;
+export declare const GetInsightsBreakdownsOutputSchema: z.ZodObject<{
+    nextCursor: z.ZodOptional<z.ZodString>;
+    has_more: z.ZodBoolean;
+    totalCount: z.ZodNumber;
+    timestamp: z.ZodString;
+    totalRows: z.ZodNumber;
+    returnedRows: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    nextOffset: z.ZodNullable<z.ZodNumber>;
+    headers: z.ZodArray<z.ZodString, "many">;
+    selectedColumns: z.ZodArray<z.ZodString, "many">;
+    mode: z.ZodEnum<["summary", "rows"]>;
+    previewRows: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+    rows: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+    warnings: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    timestamp: string;
+    mode: "summary" | "rows";
+    has_more: boolean;
+    totalCount: number;
+    totalRows: number;
+    returnedRows: number;
+    truncated: boolean;
+    nextOffset: number | null;
+    headers: string[];
+    selectedColumns: string[];
+    warnings: string[];
+    nextCursor?: string | undefined;
+    rows?: Record<string, any>[] | undefined;
+    previewRows?: Record<string, any>[] | undefined;
+}, {
+    timestamp: string;
+    mode: "summary" | "rows";
+    has_more: boolean;
+    totalCount: number;
+    totalRows: number;
+    returnedRows: number;
+    truncated: boolean;
+    nextOffset: number | null;
+    headers: string[];
+    selectedColumns: string[];
+    warnings: string[];
+    nextCursor?: string | undefined;
+    rows?: Record<string, any>[] | undefined;
+    previewRows?: Record<string, any>[] | undefined;
+}>;
+type GetInsightsBreakdownsInput = z.infer<typeof GetInsightsBreakdownsInputSchema>;
+type GetInsightsBreakdownsOutput = z.infer<typeof GetInsightsBreakdownsOutputSchema>;
+export declare function getInsightsBreakdownsLogic(input: GetInsightsBreakdownsInput, context: RequestContext, sdkContext?: SdkContext): Promise<GetInsightsBreakdownsOutput>;
+export declare function getInsightsBreakdownsResponseFormatter(result: GetInsightsBreakdownsOutput): McpTextContent[];
+export declare const getInsightsBreakdownsTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        entityId: z.ZodString;
+        breakdowns: z.ZodArray<z.ZodString, "many">;
+        fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        datePreset: z.ZodOptional<z.ZodString>;
+        timeRange: z.ZodOptional<z.ZodObject<{
+            since: z.ZodString;
+            until: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            since: string;
+            until: string;
+        }, {
+            since: string;
+            until: string;
+        }>>;
+        timeIncrement: z.ZodOptional<z.ZodString>;
+        level: z.ZodOptional<z.ZodString>;
+        actionAttributionWindows: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        includeComputedMetrics: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    } & {
+        mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["summary", "rows"]>>>;
+        columns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        offset: z.ZodOptional<z.ZodNumber>;
+        maxRows: z.ZodOptional<z.ZodNumber>;
+        aggregateBy: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        aggregateMetrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["sum", "avg", "count", "min", "max"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        entityId: string;
+        breakdowns: string[];
+        includeComputedMetrics: boolean;
+        mode: "summary" | "rows";
+        fields?: string[] | undefined;
+        limit?: number | undefined;
+        after?: string | undefined;
+        datePreset?: string | undefined;
+        level?: string | undefined;
+        timeRange?: {
+            since: string;
+            until: string;
+        } | undefined;
+        timeIncrement?: string | undefined;
+        columns?: string[] | undefined;
+        offset?: number | undefined;
+        maxRows?: number | undefined;
+        aggregateBy?: string[] | undefined;
+        aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+        actionAttributionWindows?: string[] | undefined;
+    }, {
+        entityId: string;
+        breakdowns: string[];
+        fields?: string[] | undefined;
+        limit?: number | undefined;
+        after?: string | undefined;
+        datePreset?: string | undefined;
+        level?: string | undefined;
+        timeRange?: {
+            since: string;
+            until: string;
+        } | undefined;
+        timeIncrement?: string | undefined;
+        includeComputedMetrics?: boolean | undefined;
+        mode?: "summary" | "rows" | undefined;
+        columns?: string[] | undefined;
+        offset?: number | undefined;
+        maxRows?: number | undefined;
+        aggregateBy?: string[] | undefined;
+        aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+        actionAttributionWindows?: string[] | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        nextCursor: z.ZodOptional<z.ZodString>;
+        has_more: z.ZodBoolean;
+        totalCount: z.ZodNumber;
+        timestamp: z.ZodString;
+        totalRows: z.ZodNumber;
+        returnedRows: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        nextOffset: z.ZodNullable<z.ZodNumber>;
+        headers: z.ZodArray<z.ZodString, "many">;
+        selectedColumns: z.ZodArray<z.ZodString, "many">;
+        mode: z.ZodEnum<["summary", "rows"]>;
+        previewRows: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+        rows: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+        warnings: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        timestamp: string;
+        mode: "summary" | "rows";
+        has_more: boolean;
+        totalCount: number;
+        totalRows: number;
+        returnedRows: number;
+        truncated: boolean;
+        nextOffset: number | null;
+        headers: string[];
+        selectedColumns: string[];
+        warnings: string[];
+        nextCursor?: string | undefined;
+        rows?: Record<string, any>[] | undefined;
+        previewRows?: Record<string, any>[] | undefined;
+    }, {
+        timestamp: string;
+        mode: "summary" | "rows";
+        has_more: boolean;
+        totalCount: number;
+        totalRows: number;
+        returnedRows: number;
+        truncated: boolean;
+        nextOffset: number | null;
+        headers: string[];
+        selectedColumns: string[];
+        warnings: string[];
+        nextCursor?: string | undefined;
+        rows?: Record<string, any>[] | undefined;
+        previewRows?: Record<string, any>[] | undefined;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+    };
+    inputExamples: ({
+        label: string;
+        input: {
+            entityId: string;
+            breakdowns: string[];
+            datePreset: string;
+            fields?: undefined;
+            actionAttributionWindows?: undefined;
+            level?: undefined;
+        };
+    } | {
+        label: string;
+        input: {
+            entityId: string;
+            breakdowns: string[];
+            fields: string[];
+            datePreset: string;
+            actionAttributionWindows: string[];
+            level: string;
+        };
+    })[];
+    logic: typeof getInsightsBreakdownsLogic;
+    responseFormatter: typeof getInsightsBreakdownsResponseFormatter;
+};
+export {};
+//# sourceMappingURL=get-insights-breakdowns.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-insights-breakdowns.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-insights-breakdowns.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-insights-breakdowns.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAyBnD,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoC0B,CAAC;AAExE,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQN,CAAC;AAEzC,KAAK,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AACnF,KAAK,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAErF,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,0BAA0B,EACjC,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,2BAA2B,CAAC,CAuEtC;AAED,wBAAgB,sCAAsC,CACpD,MAAM,EAAE,2BAA2B,GAClC,cAAc,EAAE,CAYlB;AAED,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCrC,CAAC"}

package/dist/mcp-server/tools/definitions/get-insights-breakdowns.tool.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { computeMetrics, createReportView, formatReportViewResponse, getReportViewFetchLimit, ReportViewInputSchema, ReportViewOutputSchema, } from "@cesteral/shared";
+const TOOL_NAME = "meta_get_insights_breakdowns";
+const TOOL_TITLE = "Get Meta Ads Insights with Breakdowns";
+const TOOL_DESCRIPTION = `Get performance insights broken down by dimension (age, gender, country, device, etc.).
+
+**Common breakdowns:** age, gender, country, region, dma, device_platform, platform_position, publisher_platform
+
+**Valid combinations:** age+gender OK, country+region NOT OK (same dimension).
+
+**Action attribution windows:** 1d_click, 7d_click, 1d_view, 7d_view
+
+**Gotchas:**
+- Not all breakdown combinations are valid.
+- Some breakdowns dramatically increase result volume.
+- Use \`limit\` to control page size.`;
+export const GetInsightsBreakdownsInputSchema = z
+    .object({
+    entityId: z.string().min(1).describe("Entity ID to get insights for"),
+    breakdowns: z
+        .array(z.string())
+        .min(1)
+        .describe("Breakdown dimensions (e.g., ['age', 'gender'])"),
+    fields: z.array(z.string()).optional().describe("Metrics to return"),
+    datePreset: z.string().optional().describe("Date preset (last_7d, last_30d, etc.)"),
+    timeRange: z
+        .object({
+        since: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format"),
+        until: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format"),
+    })
+        .optional()
+        .describe("Custom date range"),
+    timeIncrement: z.string().optional().describe("Time granularity"),
+    level: z.string().optional().describe("Aggregation level"),
+    actionAttributionWindows: z
+        .array(z.string())
+        .optional()
+        .describe("Attribution windows (e.g., ['1d_click', '7d_click'])"),
+    limit: z
+        .number()
+        .min(1)
+        .max(500)
+        .optional()
+        .describe("Deprecated. Use maxRows for the returned row count."),
+    after: z.string().optional().describe("Cursor for next page"),
+    includeComputedMetrics: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Include computed CPA, ROAS, CPM, CTR, CPC derived from raw metrics"),
+})
+    .merge(ReportViewInputSchema)
+    .describe("Parameters for getting Meta Ads insights with breakdowns");
+export const GetInsightsBreakdownsOutputSchema = z
+    .object({
+    ...ReportViewOutputSchema.shape,
+    nextCursor: z.string().optional(),
+    has_more: z.boolean().describe("Whether more results are available via pagination"),
+    totalCount: z.number(),
+    timestamp: z.string().datetime(),
+})
+    .describe("Breakdown insights result");
+export async function getInsightsBreakdownsLogic(input, context, sdkContext) {
+    const { metaInsightsService } = resolveSessionServices(sdkContext);
+    const viewInput = input.maxRows === undefined && input.limit !== undefined
+        ? { ...input, maxRows: input.limit }
+        : input;
+    const result = await metaInsightsService.getInsightsBreakdowns(input.entityId, {
+        breakdowns: input.breakdowns,
+        fields: input.fields,
+        datePreset: input.datePreset,
+        timeRange: input.timeRange,
+        timeIncrement: input.timeIncrement,
+        level: input.level,
+        actionAttributionWindows: input.actionAttributionWindows,
+        limit: getReportViewFetchLimit(viewInput),
+        after: input.after,
+    }, context);
+    let rows = result.data;
+    if (input.includeComputedMetrics) {
+        rows = rows.map((row) => {
+            const cost = Number(row.spend || 0);
+            const impressions = Number(row.impressions || 0);
+            const clicks = Number(row.clicks || 0);
+            const isConversionAction = (actionType) => actionType.startsWith("offsite_conversion") ||
+                actionType === "purchase" ||
+                actionType === "complete_registration" ||
+                actionType === "lead";
+            const conversions = Array.isArray(row.actions)
+                ? row.actions
+                    .filter((a) => isConversionAction(a.action_type ?? ""))
+                    .reduce((sum, a) => sum + Number(a.value || 0), 0)
+                : 0;
+            const conversionValue = Array.isArray(row.action_values)
+                ? row.action_values
+                    .filter((a) => isConversionAction(a.action_type ?? ""))
+                    .reduce((sum, a) => sum + Number(a.value || 0), 0)
+                : 0;
+            return {
+                ...row,
+                computedMetrics: computeMetrics({
+                    cost,
+                    impressions,
+                    clicks,
+                    conversions,
+                    conversionValue,
+                }),
+            };
+        });
+    }
+    return {
+        ...createReportView({
+            rows,
+            totalRows: rows.length + (result.nextCursor ? 1 : 0),
+            input: viewInput,
+            warnings: result.nextCursor
+                ? ["More rows are available. Call again with after set to nextCursor to continue."]
+                : [],
+        }),
+        nextCursor: result.nextCursor,
+        has_more: !!result.nextCursor,
+        totalCount: rows.length,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function getInsightsBreakdownsResponseFormatter(result) {
+    const summary = `Retrieved ${result.returnedRows} breakdown row(s)`;
+    const pagination = result.nextCursor
+        ? `\n\nMore results available. Use after: "${result.nextCursor}"`
+        : "";
+    return [
+        {
+            type: "text",
+            text: `${summary}\n\n${formatReportViewResponse(result, "Breakdown data")}${pagination}\n\nTimestamp: ${result.timestamp}`,
+        },
+    ];
+}
+export const getInsightsBreakdownsTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: GetInsightsBreakdownsInputSchema,
+    outputSchema: GetInsightsBreakdownsOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        idempotentHint: true,
+        destructiveHint: false,
+    },
+    inputExamples: [
+        {
+            label: "Get age and gender breakdown for a campaign",
+            input: {
+                entityId: "23456789012345",
+                breakdowns: ["age", "gender"],
+                datePreset: "last_30d",
+            },
+        },
+        {
+            label: "Get country breakdown with attribution",
+            input: {
+                entityId: "act_123456789",
+                breakdowns: ["country"],
+                fields: ["impressions", "clicks", "spend", "actions"],
+                datePreset: "last_7d",
+                actionAttributionWindows: ["1d_click", "7d_click"],
+                level: "campaign",
+            },
+        },
+    ],
+    logic: getInsightsBreakdownsLogic,
+    responseFormatter: getInsightsBreakdownsResponseFormatter,
+};
+//# sourceMappingURL=get-insights-breakdowns.tool.js.map

package/dist/mcp-server/tools/definitions/get-insights-breakdowns.tool.js.map

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