@cesteral/tiktok-mcp 1.0.0

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

@@ -0,0 +1,303 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const GetReportInputSchema: z.ZodEffects<z.ZodObject<{
+    advertiserId: z.ZodString;
+    reportType: z.ZodDefault<z.ZodOptional<z.ZodEnum<["BASIC", "AUDIENCE", "PLAYABLE_MATERIAL"]>>>;
+    dimensions: z.ZodArray<z.ZodString, "many">;
+    metrics: z.ZodArray<z.ZodString, "many">;
+    datePreset: z.ZodOptional<z.ZodEnum<["TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH", "LAST_90_DAYS"]>>;
+    startDate: z.ZodOptional<z.ZodString>;
+    endDate: z.ZodOptional<z.ZodString>;
+    orderField: z.ZodOptional<z.ZodString>;
+    orderType: z.ZodOptional<z.ZodEnum<["ASC", "DESC"]>>;
+    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, {
+    dimensions: string[];
+    metrics: string[];
+    advertiserId: string;
+    reportType: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL";
+    includeComputedMetrics: boolean;
+    mode: "rows" | "summary";
+    datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+    startDate?: string | undefined;
+    endDate?: string | undefined;
+    orderField?: string | undefined;
+    orderType?: "ASC" | "DESC" | undefined;
+    columns?: string[] | undefined;
+    offset?: number | undefined;
+    maxRows?: number | undefined;
+    aggregateBy?: string[] | undefined;
+    aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+}, {
+    dimensions: string[];
+    metrics: string[];
+    advertiserId: string;
+    reportType?: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL" | undefined;
+    datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+    startDate?: string | undefined;
+    endDate?: string | undefined;
+    orderField?: string | undefined;
+    orderType?: "ASC" | "DESC" | undefined;
+    includeComputedMetrics?: boolean | undefined;
+    mode?: "rows" | "summary" | undefined;
+    columns?: string[] | undefined;
+    offset?: number | undefined;
+    maxRows?: number | undefined;
+    aggregateBy?: string[] | undefined;
+    aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+}>, {
+    dimensions: string[];
+    metrics: string[];
+    advertiserId: string;
+    reportType: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL";
+    includeComputedMetrics: boolean;
+    mode: "rows" | "summary";
+    datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+    startDate?: string | undefined;
+    endDate?: string | undefined;
+    orderField?: string | undefined;
+    orderType?: "ASC" | "DESC" | undefined;
+    columns?: string[] | undefined;
+    offset?: number | undefined;
+    maxRows?: number | undefined;
+    aggregateBy?: string[] | undefined;
+    aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+}, {
+    dimensions: string[];
+    metrics: string[];
+    advertiserId: string;
+    reportType?: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL" | undefined;
+    datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+    startDate?: string | undefined;
+    endDate?: string | undefined;
+    orderField?: string | undefined;
+    orderType?: "ASC" | "DESC" | undefined;
+    includeComputedMetrics?: boolean | undefined;
+    mode?: "rows" | "summary" | undefined;
+    columns?: string[] | undefined;
+    offset?: number | undefined;
+    maxRows?: number | undefined;
+    aggregateBy?: string[] | undefined;
+    aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+}>;
+export declare const GetReportOutputSchema: z.ZodObject<{
+    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">;
+    taskId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    taskId: string;
+    totalRows: number;
+    headers: string[];
+    timestamp: string;
+    mode: "rows" | "summary";
+    returnedRows: number;
+    truncated: boolean;
+    nextOffset: number | null;
+    selectedColumns: string[];
+    warnings: string[];
+    rows?: Record<string, any>[] | undefined;
+    previewRows?: Record<string, any>[] | undefined;
+}, {
+    taskId: string;
+    totalRows: number;
+    headers: string[];
+    timestamp: string;
+    mode: "rows" | "summary";
+    returnedRows: number;
+    truncated: boolean;
+    nextOffset: number | null;
+    selectedColumns: string[];
+    warnings: string[];
+    rows?: Record<string, any>[] | undefined;
+    previewRows?: Record<string, any>[] | undefined;
+}>;
+type GetReportInput = z.infer<typeof GetReportInputSchema>;
+type GetReportOutput = z.infer<typeof GetReportOutputSchema>;
+export declare function getReportLogic(input: GetReportInput, context: RequestContext, sdkContext?: SdkContext): Promise<GetReportOutput>;
+export declare function getReportResponseFormatter(result: GetReportOutput): McpTextContent[];
+export declare const getReportTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodEffects<z.ZodObject<{
+        advertiserId: z.ZodString;
+        reportType: z.ZodDefault<z.ZodOptional<z.ZodEnum<["BASIC", "AUDIENCE", "PLAYABLE_MATERIAL"]>>>;
+        dimensions: z.ZodArray<z.ZodString, "many">;
+        metrics: z.ZodArray<z.ZodString, "many">;
+        datePreset: z.ZodOptional<z.ZodEnum<["TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH", "LAST_90_DAYS"]>>;
+        startDate: z.ZodOptional<z.ZodString>;
+        endDate: z.ZodOptional<z.ZodString>;
+        orderField: z.ZodOptional<z.ZodString>;
+        orderType: z.ZodOptional<z.ZodEnum<["ASC", "DESC"]>>;
+        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, {
+        dimensions: string[];
+        metrics: string[];
+        advertiserId: string;
+        reportType: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL";
+        includeComputedMetrics: boolean;
+        mode: "rows" | "summary";
+        datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        orderField?: string | undefined;
+        orderType?: "ASC" | "DESC" | undefined;
+        columns?: string[] | undefined;
+        offset?: number | undefined;
+        maxRows?: number | undefined;
+        aggregateBy?: string[] | undefined;
+        aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+    }, {
+        dimensions: string[];
+        metrics: string[];
+        advertiserId: string;
+        reportType?: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL" | undefined;
+        datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        orderField?: string | undefined;
+        orderType?: "ASC" | "DESC" | undefined;
+        includeComputedMetrics?: boolean | undefined;
+        mode?: "rows" | "summary" | undefined;
+        columns?: string[] | undefined;
+        offset?: number | undefined;
+        maxRows?: number | undefined;
+        aggregateBy?: string[] | undefined;
+        aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+    }>, {
+        dimensions: string[];
+        metrics: string[];
+        advertiserId: string;
+        reportType: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL";
+        includeComputedMetrics: boolean;
+        mode: "rows" | "summary";
+        datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        orderField?: string | undefined;
+        orderType?: "ASC" | "DESC" | undefined;
+        columns?: string[] | undefined;
+        offset?: number | undefined;
+        maxRows?: number | undefined;
+        aggregateBy?: string[] | undefined;
+        aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+    }, {
+        dimensions: string[];
+        metrics: string[];
+        advertiserId: string;
+        reportType?: "BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL" | undefined;
+        datePreset?: "TODAY" | "YESTERDAY" | "LAST_7_DAYS" | "LAST_14_DAYS" | "LAST_30_DAYS" | "THIS_MONTH" | "LAST_MONTH" | "LAST_90_DAYS" | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        orderField?: string | undefined;
+        orderType?: "ASC" | "DESC" | undefined;
+        includeComputedMetrics?: boolean | undefined;
+        mode?: "rows" | "summary" | undefined;
+        columns?: string[] | undefined;
+        offset?: number | undefined;
+        maxRows?: number | undefined;
+        aggregateBy?: string[] | undefined;
+        aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        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">;
+        taskId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        taskId: string;
+        totalRows: number;
+        headers: string[];
+        timestamp: string;
+        mode: "rows" | "summary";
+        returnedRows: number;
+        truncated: boolean;
+        nextOffset: number | null;
+        selectedColumns: string[];
+        warnings: string[];
+        rows?: Record<string, any>[] | undefined;
+        previewRows?: Record<string, any>[] | undefined;
+    }, {
+        taskId: string;
+        totalRows: number;
+        headers: string[];
+        timestamp: string;
+        mode: "rows" | "summary";
+        returnedRows: number;
+        truncated: boolean;
+        nextOffset: number | null;
+        selectedColumns: string[];
+        warnings: string[];
+        rows?: Record<string, any>[] | undefined;
+        previewRows?: Record<string, any>[] | undefined;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+    };
+    inputExamples: ({
+        label: string;
+        input: {
+            advertiserId: string;
+            dimensions: string[];
+            metrics: string[];
+            datePreset: string;
+            reportType?: undefined;
+            startDate?: undefined;
+            endDate?: undefined;
+            orderField?: undefined;
+            orderType?: undefined;
+        };
+    } | {
+        label: string;
+        input: {
+            advertiserId: string;
+            reportType: string;
+            dimensions: string[];
+            metrics: string[];
+            startDate: string;
+            endDate: string;
+            orderField: string;
+            orderType: string;
+            datePreset?: undefined;
+        };
+    })[];
+    logic: typeof getReportLogic;
+    responseFormatter: typeof getReportResponseFormatter;
+};
+export {};
+//# sourceMappingURL=get-report.tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-report.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-report.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAcnD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiD2B,CAAC;AAE7D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMN,CAAC;AAE7B,KAAK,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAC3D,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAsC7D,wBAAsB,cAAc,CAClC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,eAAe,CAAC,CA0C1B;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,EAAE,CAOpF;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCzB,CAAC"}

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

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { arrayRowsToRecords, computeMetrics, createReportView, formatReportViewResponse, getReportViewFetchLimit, resolveDatePreset, DATE_PRESET_VALUES, ReportViewInputSchema, ReportViewOutputSchema, } from "@cesteral/shared";
+const TOOL_NAME = "tiktok_get_report";
+const TOOL_TITLE = "Get TikTok Ads Report";
+const TOOL_DESCRIPTION = `Submit and retrieve an async TikTok Ads performance report.
+
+Follows the async polling pattern: submit task → poll until DONE → download CSV.
+This may take 30s–5 minutes depending on the data volume.
+
+**Common dimensions:** campaign_id, adgroup_id, ad_id, stat_time_day, stat_time_hour, country_code
+**Common metrics:** spend, impressions, clicks, ctr, cpm, cpc, conversions, conversion_rate, reach, frequency
+
+**Report types:** BASIC (default), AUDIENCE, PLAYABLE_MATERIAL`;
+export const GetReportInputSchema = z
+    .object({
+    advertiserId: z
+        .string()
+        .min(1)
+        .describe("TikTok Advertiser ID (informational — the session-bound advertiser from authentication is used for API calls)"),
+    reportType: z
+        .enum(["BASIC", "AUDIENCE", "PLAYABLE_MATERIAL"])
+        .optional()
+        .default("BASIC")
+        .describe("Report type (default: BASIC)"),
+    dimensions: z
+        .array(z.string())
+        .min(1)
+        .describe("Dimensions for the report (e.g., ['campaign_id', 'stat_time_day'])"),
+    metrics: z
+        .array(z.string())
+        .min(1)
+        .describe("Metrics to include (e.g., ['impressions', 'clicks', 'spend'])"),
+    datePreset: z
+        .enum(DATE_PRESET_VALUES)
+        .optional()
+        .describe("Preset date range. Use this OR startDate+endDate (not both)"),
+    startDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe("Start date (YYYY-MM-DD, required if datePreset not provided)"),
+    endDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe("End date (YYYY-MM-DD, required if datePreset not provided)"),
+    orderField: z.string().optional().describe("Field to order results by"),
+    orderType: z.enum(["ASC", "DESC"]).optional().describe("Sort order"),
+    includeComputedMetrics: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Include computed CPA, ROAS, CPM, CTR, CPC derived from raw metrics"),
+})
+    .merge(ReportViewInputSchema)
+    .refine((data) => data.datePreset !== undefined || (data.startDate !== undefined && data.endDate !== undefined), { message: "Provide either datePreset or both startDate and endDate" })
+    .describe("Parameters for generating a TikTok Ads report");
+export const GetReportOutputSchema = z
+    .object({
+    taskId: z.string().describe("Report task ID"),
+    ...ReportViewOutputSchema.shape,
+    timestamp: z.string().datetime(),
+})
+    .describe("Report result");
+function appendComputedMetricsToRows(headers, rows) {
+    const idx = (name) => headers.findIndex((h) => h.toLowerCase() === name.toLowerCase());
+    const spendIdx = idx("spend");
+    const impIdx = idx("impressions");
+    const clickIdx = idx("clicks");
+    const convIdx = idx("conversions");
+    const newHeaders = [
+        ...headers,
+        "computed_cpa",
+        "computed_roas",
+        "computed_cpm",
+        "computed_ctr",
+        "computed_cpc",
+    ];
+    const newRows = rows.map((row) => {
+        const cost = spendIdx >= 0 ? Number(row[spendIdx] || 0) : 0;
+        const impressions = impIdx >= 0 ? Number(row[impIdx] || 0) : 0;
+        const clicks = clickIdx >= 0 ? Number(row[clickIdx] || 0) : 0;
+        const conversions = convIdx >= 0 ? Number(row[convIdx] || 0) : 0;
+        const m = computeMetrics({ cost, impressions, clicks, conversions, conversionValue: 0 });
+        return [
+            ...row,
+            m.cpa !== null ? String(m.cpa) : "",
+            m.roas !== null ? String(m.roas) : "",
+            m.cpm !== null ? String(m.cpm) : "",
+            m.ctr !== null ? String(m.ctr) : "",
+            m.cpc !== null ? String(m.cpc) : "",
+        ];
+    });
+    return { headers: newHeaders, rows: newRows };
+}
+export async function getReportLogic(input, context, sdkContext) {
+    const { tiktokReportingService } = resolveSessionServices(sdkContext);
+    let resolvedStartDate = input.startDate;
+    let resolvedEndDate = input.endDate;
+    if (input.datePreset) {
+        const resolved = resolveDatePreset(input.datePreset);
+        resolvedStartDate = resolved.startDate;
+        resolvedEndDate = resolved.endDate;
+    }
+    const result = await tiktokReportingService.getReport({
+        report_type: input.reportType,
+        dimensions: input.dimensions,
+        metrics: input.metrics,
+        start_date: resolvedStartDate,
+        end_date: resolvedEndDate,
+        ...(input.orderField ? { order_field: input.orderField } : {}),
+        ...(input.orderType ? { order_type: input.orderType } : {}),
+    }, getReportViewFetchLimit(input), context);
+    let headers = result.headers;
+    let rows = result.rows;
+    if (input.includeComputedMetrics) {
+        ({ headers, rows } = appendComputedMetricsToRows(headers, rows));
+    }
+    return {
+        taskId: result.taskId,
+        ...createReportView({
+            headers,
+            rows: arrayRowsToRecords(headers, rows),
+            totalRows: result.totalRows,
+            input,
+        }),
+        timestamp: new Date().toISOString(),
+    };
+}
+export function getReportResponseFormatter(result) {
+    return [
+        {
+            type: "text",
+            text: `Report task: ${result.taskId}\n\n${formatReportViewResponse(result, "Report data")}`,
+        },
+    ];
+}
+export const getReportTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: GetReportInputSchema,
+    outputSchema: GetReportOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        idempotentHint: false,
+        destructiveHint: false,
+    },
+    inputExamples: [
+        {
+            label: "Campaign delivery report for last 7 days",
+            input: {
+                advertiserId: "1234567890",
+                dimensions: ["campaign_id", "stat_time_day"],
+                metrics: ["impressions", "clicks", "spend", "ctr", "cpc"],
+                datePreset: "LAST_7_DAYS",
+            },
+        },
+        {
+            label: "Ad group performance report",
+            input: {
+                advertiserId: "1234567890",
+                reportType: "BASIC",
+                dimensions: ["adgroup_id"],
+                metrics: ["impressions", "clicks", "spend", "conversions", "conversion_rate"],
+                startDate: "2026-03-01",
+                endDate: "2026-03-04",
+                orderField: "spend",
+                orderType: "DESC",
+            },
+        },
+    ],
+    logic: getReportLogic,
+    responseFormatter: getReportResponseFormatter,
+};
+//# sourceMappingURL=get-report.tool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-report.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-report.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAI1B,MAAM,SAAS,GAAG,mBAAmB,CAAC;AACtC,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAC3C,MAAM,gBAAgB,GAAG;;;;;;;;+DAQsC,CAAC;AAEhE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC;IACN,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,+GAA+G,CAChH;IACH,UAAU,EAAE,CAAC;SACV,IAAI,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,mBAAmB,CAAC,CAAC;SAChD,QAAQ,EAAE;SACV,OAAO,CAAC,OAAO,CAAC;SAChB,QAAQ,CAAC,8BAA8B,CAAC;IAC3C,UAAU,EAAE,CAAC;SACV,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,oEAAoE,CAAC;IACjF,OAAO,EAAE,CAAC;SACP,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,+DAA+D,CAAC;IAC5E,UAAU,EAAE,CAAC;SACV,IAAI,CAAC,kBAAkB,CAAC;SACxB,QAAQ,EAAE;SACV,QAAQ,CAAC,6DAA6D,CAAC;IAC1E,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,KAAK,CAAC,qBAAqB,CAAC;SAC5B,QAAQ,EAAE;SACV,QAAQ,CAAC,8DAA8D,CAAC;IAC3E,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,KAAK,CAAC,qBAAqB,CAAC;SAC5B,QAAQ,EAAE;SACV,QAAQ,CAAC,4DAA4D,CAAC;IACzE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IACvE,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;IACpE,sBAAsB,EAAE,CAAC;SACtB,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,oEAAoE,CAAC;CAClF,CAAC;KACD,KAAK,CAAC,qBAAqB,CAAC;KAC5B,MAAM,CACL,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,EAC/F,EAAE,OAAO,EAAE,yDAAyD,EAAE,CACvE;KACA,QAAQ,CAAC,+CAA+C,CAAC,CAAC;AAE7D,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC;KACnC,MAAM,CAAC;IACN,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAC7C,GAAG,sBAAsB,CAAC,KAAK;IAC/B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC;KACD,QAAQ,CAAC,eAAe,CAAC,CAAC;AAK7B,SAAS,2BAA2B,CAClC,OAAiB,EACjB,IAAgB;IAEhB,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/F,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAG,GAAG,CAAC,aAAa,CAAC,CAAC;IAEnC,MAAM,UAAU,GAAG;QACjB,GAAG,OAAO;QACV,cAAc;QACd,eAAe;QACf,cAAc;QACd,cAAc;QACd,cAAc;KACf,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAC/B,MAAM,IAAI,GAAG,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9D,MAAM,WAAW,GAAG,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjE,MAAM,CAAC,GAAG,cAAc,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC,CAAC;QACzF,OAAO;YACL,GAAG,GAAG;YACN,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE;YACnC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE;YACrC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE;YACnC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE;YACnC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE;SACpC,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAqB,EACrB,OAAuB,EACvB,UAAuB;IAEvB,MAAM,EAAE,sBAAsB,EAAE,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAEtE,IAAI,iBAAiB,GAAG,KAAK,CAAC,SAAS,CAAC;IACxC,IAAI,eAAe,GAAG,KAAK,CAAC,OAAO,CAAC;IACpC,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACrD,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC;QACvC,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC;IACrC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,sBAAsB,CAAC,SAAS,CACnD;QACE,WAAW,EAAE,KAAK,CAAC,UAAU;QAC7B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,iBAAkB;QAC9B,QAAQ,EAAE,eAAgB;QAC1B,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5D,EACD,uBAAuB,CAAC,KAAK,CAAC,EAC9B,OAAO,CACR,CAAC;IAEF,IAAI,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC7B,IAAI,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IAEvB,IAAI,KAAK,CAAC,sBAAsB,EAAE,CAAC;QACjC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,2BAA2B,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IACnE,CAAC;IAED,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,gBAAgB,CAAC;YAClB,OAAO;YACP,IAAI,EAAE,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC;YACvC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,KAAK;SACN,CAAC;QACF,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,MAAuB;IAChE,OAAO;QACL;YACE,IAAI,EAAE,MAAe;YACrB,IAAI,EAAE,gBAAgB,MAAM,CAAC,MAAM,OAAO,wBAAwB,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE;SAC5F;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,UAAU;IACjB,WAAW,EAAE,gBAAgB;IAC7B,WAAW,EAAE,oBAAoB;IACjC,YAAY,EAAE,qBAAqB;IACnC,WAAW,EAAE;QACX,YAAY,EAAE,IAAI;QAClB,aAAa,EAAE,KAAK;QACpB,cAAc,EAAE,KAAK;QACrB,eAAe,EAAE,KAAK;KACvB;IACD,aAAa,EAAE;QACb;YACE,KAAK,EAAE,0CAA0C;YACjD,KAAK,EAAE;gBACL,YAAY,EAAE,YAAY;gBAC1B,UAAU,EAAE,CAAC,aAAa,EAAE,eAAe,CAAC;gBAC5C,OAAO,EAAE,CAAC,aAAa,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC;gBACzD,UAAU,EAAE,aAAa;aAC1B;SACF;QACD;YACE,KAAK,EAAE,6BAA6B;YACpC,KAAK,EAAE;gBACL,YAAY,EAAE,YAAY;gBAC1B,UAAU,EAAE,OAAO;gBACnB,UAAU,EAAE,CAAC,YAAY,CAAC;gBAC1B,OAAO,EAAE,CAAC,aAAa,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,CAAC;gBAC7E,SAAS,EAAE,YAAY;gBACvB,OAAO,EAAE,YAAY;gBACrB,UAAU,EAAE,OAAO;gBACnB,SAAS,EAAE,MAAM;aAClB;SACF;KACF;IACD,KAAK,EAAE,cAAc;IACrB,iBAAiB,EAAE,0BAA0B;CAC9C,CAAC"}

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

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const GetTargetingOptionsInputSchema: z.ZodObject<{
+    advertiserId: z.ZodString;
+    optionType: z.ZodEnum<["ACTION_CATEGORY", "CARRIER", "DEVICE_MODEL", "INTEREST_CATEGORY", "INTEREST_KEYWORD", "ISP", "LANGUAGE", "LOCATION"]>;
+    keyword: z.ZodOptional<z.ZodString>;
+    placements: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    objectiveType: z.ZodOptional<z.ZodString>;
+    promotionType: z.ZodOptional<z.ZodString>;
+    operatingSystem: z.ZodOptional<z.ZodEnum<["ANDROID", "IOS"]>>;
+    locationIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    scene: z.ZodOptional<z.ZodEnum<["ISP"]>>;
+    specialIndustries: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    advertiserId: string;
+    optionType: "ACTION_CATEGORY" | "CARRIER" | "DEVICE_MODEL" | "INTEREST_CATEGORY" | "INTEREST_KEYWORD" | "LANGUAGE" | "LOCATION" | "ISP";
+    scene?: "ISP" | undefined;
+    placements?: string[] | undefined;
+    objectiveType?: string | undefined;
+    promotionType?: string | undefined;
+    operatingSystem?: "ANDROID" | "IOS" | undefined;
+    keyword?: string | undefined;
+    locationIds?: string[] | undefined;
+    specialIndustries?: string[] | undefined;
+}, {
+    advertiserId: string;
+    optionType: "ACTION_CATEGORY" | "CARRIER" | "DEVICE_MODEL" | "INTEREST_CATEGORY" | "INTEREST_KEYWORD" | "LANGUAGE" | "LOCATION" | "ISP";
+    scene?: "ISP" | undefined;
+    placements?: string[] | undefined;
+    objectiveType?: string | undefined;
+    promotionType?: string | undefined;
+    operatingSystem?: "ANDROID" | "IOS" | undefined;
+    keyword?: string | undefined;
+    locationIds?: string[] | undefined;
+    specialIndustries?: string[] | undefined;
+}>;
+export declare const GetTargetingOptionsOutputSchema: z.ZodObject<{
+    options: z.ZodRecord<z.ZodString, z.ZodAny>;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    options: Record<string, any>;
+    timestamp: string;
+}, {
+    options: Record<string, any>;
+    timestamp: string;
+}>;
+type GetTargetingOptionsInput = z.infer<typeof GetTargetingOptionsInputSchema>;
+type GetTargetingOptionsOutput = z.infer<typeof GetTargetingOptionsOutputSchema>;
+export declare function getTargetingOptionsLogic(input: GetTargetingOptionsInput, context: RequestContext, sdkContext?: SdkContext): Promise<GetTargetingOptionsOutput>;
+export declare function getTargetingOptionsResponseFormatter(result: GetTargetingOptionsOutput): McpTextContent[];
+export declare const getTargetingOptionsTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        advertiserId: z.ZodString;
+        optionType: z.ZodEnum<["ACTION_CATEGORY", "CARRIER", "DEVICE_MODEL", "INTEREST_CATEGORY", "INTEREST_KEYWORD", "ISP", "LANGUAGE", "LOCATION"]>;
+        keyword: z.ZodOptional<z.ZodString>;
+        placements: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        objectiveType: z.ZodOptional<z.ZodString>;
+        promotionType: z.ZodOptional<z.ZodString>;
+        operatingSystem: z.ZodOptional<z.ZodEnum<["ANDROID", "IOS"]>>;
+        locationIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        scene: z.ZodOptional<z.ZodEnum<["ISP"]>>;
+        specialIndustries: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        advertiserId: string;
+        optionType: "ACTION_CATEGORY" | "CARRIER" | "DEVICE_MODEL" | "INTEREST_CATEGORY" | "INTEREST_KEYWORD" | "LANGUAGE" | "LOCATION" | "ISP";
+        scene?: "ISP" | undefined;
+        placements?: string[] | undefined;
+        objectiveType?: string | undefined;
+        promotionType?: string | undefined;
+        operatingSystem?: "ANDROID" | "IOS" | undefined;
+        keyword?: string | undefined;
+        locationIds?: string[] | undefined;
+        specialIndustries?: string[] | undefined;
+    }, {
+        advertiserId: string;
+        optionType: "ACTION_CATEGORY" | "CARRIER" | "DEVICE_MODEL" | "INTEREST_CATEGORY" | "INTEREST_KEYWORD" | "LANGUAGE" | "LOCATION" | "ISP";
+        scene?: "ISP" | undefined;
+        placements?: string[] | undefined;
+        objectiveType?: string | undefined;
+        promotionType?: string | undefined;
+        operatingSystem?: "ANDROID" | "IOS" | undefined;
+        keyword?: string | undefined;
+        locationIds?: string[] | undefined;
+        specialIndustries?: string[] | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        options: z.ZodRecord<z.ZodString, z.ZodAny>;
+        timestamp: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        options: Record<string, any>;
+        timestamp: string;
+    }, {
+        options: Record<string, any>;
+        timestamp: string;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+    };
+    inputExamples: ({
+        label: string;
+        input: {
+            advertiserId: string;
+            optionType: string;
+            placements?: undefined;
+            objectiveType?: undefined;
+        };
+    } | {
+        label: string;
+        input: {
+            advertiserId: string;
+            optionType: string;
+            placements: string[];
+            objectiveType: string;
+        };
+    })[];
+    logic: typeof getTargetingOptionsLogic;
+    responseFormatter: typeof getTargetingOptionsResponseFormatter;
+};
+export {};
+//# sourceMappingURL=get-targeting-options.tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-targeting-options.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-targeting-options.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;AAanD,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0CoB,CAAC;AAEhE,eAAO,MAAM,+BAA+B;;;;;;;;;EAKL,CAAC;AAExC,KAAK,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAC/E,KAAK,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAEjF,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,wBAAwB,EAC/B,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,yBAAyB,CAAC,CAsBpC;AAED,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,yBAAyB,GAChC,cAAc,EAAE,CAOlB;AAED,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCnC,CAAC"}