@cesteral/meta-mcp 1.0.0

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

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const CheckReportStatusInputSchema: z.ZodObject<{
+    reportRunId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reportRunId: string;
+}, {
+    reportRunId: string;
+}>;
+export declare const CheckReportStatusOutputSchema: z.ZodObject<{
+    state: z.ZodEnum<["pending", "running", "complete", "failed", "cancelled"]>;
+    progress: z.ZodOptional<z.ZodNumber>;
+    downloadUrl: z.ZodOptional<z.ZodString>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    submittedAt: z.ZodOptional<z.ZodString>;
+    completedAt: z.ZodOptional<z.ZodString>;
+} & {
+    reportRunId: z.ZodString;
+    rawStatus: z.ZodString;
+    isComplete: z.ZodBoolean;
+    asyncPercentCompletion: z.ZodOptional<z.ZodNumber>;
+    errorCode: z.ZodOptional<z.ZodNumber>;
+    errorMessage: z.ZodOptional<z.ZodString>;
+    errorSubcode: z.ZodOptional<z.ZodNumber>;
+    errorUserTitle: z.ZodOptional<z.ZodString>;
+    errorUserMsg: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reportRunId: string;
+    timestamp: string;
+    rawStatus: string;
+    isComplete: boolean;
+    state: "pending" | "running" | "complete" | "failed" | "cancelled";
+    asyncPercentCompletion?: number | undefined;
+    errorCode?: number | undefined;
+    errorMessage?: string | undefined;
+    errorSubcode?: number | undefined;
+    errorUserTitle?: string | undefined;
+    errorUserMsg?: string | undefined;
+    progress?: number | undefined;
+    downloadUrl?: string | undefined;
+    errors?: string[] | undefined;
+    submittedAt?: string | undefined;
+    completedAt?: string | undefined;
+}, {
+    reportRunId: string;
+    timestamp: string;
+    rawStatus: string;
+    isComplete: boolean;
+    state: "pending" | "running" | "complete" | "failed" | "cancelled";
+    asyncPercentCompletion?: number | undefined;
+    errorCode?: number | undefined;
+    errorMessage?: string | undefined;
+    errorSubcode?: number | undefined;
+    errorUserTitle?: string | undefined;
+    errorUserMsg?: string | undefined;
+    progress?: number | undefined;
+    downloadUrl?: string | undefined;
+    errors?: string[] | undefined;
+    submittedAt?: string | undefined;
+    completedAt?: string | undefined;
+}>;
+type CheckReportStatusInput = z.infer<typeof CheckReportStatusInputSchema>;
+type CheckReportStatusOutput = z.infer<typeof CheckReportStatusOutputSchema>;
+export declare function checkReportStatusLogic(input: CheckReportStatusInput, context: RequestContext, sdkContext?: SdkContext): Promise<CheckReportStatusOutput>;
+export declare function checkReportStatusResponseFormatter(result: CheckReportStatusOutput): McpTextContent[];
+export declare const checkReportStatusTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        reportRunId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        reportRunId: string;
+    }, {
+        reportRunId: string;
+    }>;
+    outputSchema: z.ZodObject<{
+        state: z.ZodEnum<["pending", "running", "complete", "failed", "cancelled"]>;
+        progress: z.ZodOptional<z.ZodNumber>;
+        downloadUrl: z.ZodOptional<z.ZodString>;
+        errors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        submittedAt: z.ZodOptional<z.ZodString>;
+        completedAt: z.ZodOptional<z.ZodString>;
+    } & {
+        reportRunId: z.ZodString;
+        rawStatus: z.ZodString;
+        isComplete: z.ZodBoolean;
+        asyncPercentCompletion: z.ZodOptional<z.ZodNumber>;
+        errorCode: z.ZodOptional<z.ZodNumber>;
+        errorMessage: z.ZodOptional<z.ZodString>;
+        errorSubcode: z.ZodOptional<z.ZodNumber>;
+        errorUserTitle: z.ZodOptional<z.ZodString>;
+        errorUserMsg: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        reportRunId: string;
+        timestamp: string;
+        rawStatus: string;
+        isComplete: boolean;
+        state: "pending" | "running" | "complete" | "failed" | "cancelled";
+        asyncPercentCompletion?: number | undefined;
+        errorCode?: number | undefined;
+        errorMessage?: string | undefined;
+        errorSubcode?: number | undefined;
+        errorUserTitle?: string | undefined;
+        errorUserMsg?: string | undefined;
+        progress?: number | undefined;
+        downloadUrl?: string | undefined;
+        errors?: string[] | undefined;
+        submittedAt?: string | undefined;
+        completedAt?: string | undefined;
+    }, {
+        reportRunId: string;
+        timestamp: string;
+        rawStatus: string;
+        isComplete: boolean;
+        state: "pending" | "running" | "complete" | "failed" | "cancelled";
+        asyncPercentCompletion?: number | undefined;
+        errorCode?: number | undefined;
+        errorMessage?: string | undefined;
+        errorSubcode?: number | undefined;
+        errorUserTitle?: string | undefined;
+        errorUserMsg?: string | undefined;
+        progress?: number | undefined;
+        downloadUrl?: string | undefined;
+        errors?: string[] | undefined;
+        submittedAt?: string | undefined;
+        completedAt?: string | undefined;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+    };
+    inputExamples: {
+        label: string;
+        input: {
+            reportRunId: string;
+        };
+    }[];
+    logic: typeof checkReportStatusLogic;
+    responseFormatter: typeof checkReportStatusResponseFormatter;
+};
+export {};
+//# sourceMappingURL=check-report-status.tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"check-report-status.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/check-report-status.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAWnD,eAAO,MAAM,4BAA4B;;;;;;EAIkB,CAAC;AAE5D,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqBD,CAAC;AAE1C,KAAK,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAC3E,KAAK,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAE7E,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,uBAAuB,CAAC,CAuBlC;AAED,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,uBAAuB,GAC9B,cAAc,EAAE,CAyBlB;AAED,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsBjC,CAAC"}

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

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { fromMetaStatus, ReportStatusSchema } from "@cesteral/shared";
+const TOOL_NAME = "meta_check_report_status";
+const TOOL_TITLE = "Check Meta Report Status";
+const TOOL_DESCRIPTION = `Check the status of an async Meta Ads insights report job.
+
+Poll this tool after \`meta_submit_report\` until \`isComplete\` is true, then call \`meta_download_report\`.
+
+**Canonical states:** \`pending\`, \`running\`, \`complete\`, \`failed\`, \`cancelled\`.
+Meta source states are mapped — "Job Completed" → \`complete\`, "Job Failed" → \`failed\`, "Job Started"/"Job Running" → \`running\`, everything else → \`pending\`. The original Meta status string is returned as \`rawStatus\`.`;
+export const CheckReportStatusInputSchema = z
+    .object({
+    reportRunId: z.string().min(1).describe("Report run ID from meta_submit_report"),
+})
+    .describe("Parameters for checking a Meta report status");
+export const CheckReportStatusOutputSchema = ReportStatusSchema.extend({
+    reportRunId: z.string(),
+    rawStatus: z
+        .string()
+        .describe("Raw Meta async_status string (e.g. 'Job Completed', 'Job Running')"),
+    isComplete: z
+        .boolean()
+        .describe("True when canonical state is 'complete' — safe to call meta_download_report"),
+    asyncPercentCompletion: z.number().optional().describe("Completion percentage (0–100)"),
+    errorCode: z.number().optional().describe("Meta error code (set when state is 'failed')"),
+    errorMessage: z.string().optional().describe("Meta error message (set when state is 'failed')"),
+    errorSubcode: z.number().optional().describe("Meta error subcode (set when state is 'failed')"),
+    errorUserTitle: z
+        .string()
+        .optional()
+        .describe("User-facing error title (set when state is 'failed')"),
+    errorUserMsg: z
+        .string()
+        .optional()
+        .describe("User-facing error message (set when state is 'failed')"),
+    timestamp: z.string().datetime(),
+}).describe("Report status check result");
+export async function checkReportStatusLogic(input, context, sdkContext) {
+    const { metaInsightsService } = resolveSessionServices(sdkContext);
+    const result = await metaInsightsService.checkReportStatus(input.reportRunId, context);
+    const canonical = fromMetaStatus({
+        async_status: result.status,
+        async_percent_completion: result.asyncPercentCompletion,
+    });
+    return {
+        ...canonical,
+        reportRunId: result.reportRunId,
+        rawStatus: result.status,
+        isComplete: canonical.state === "complete",
+        asyncPercentCompletion: result.asyncPercentCompletion,
+        errorCode: result.errorCode,
+        errorMessage: result.errorMessage,
+        errorSubcode: result.errorSubcode,
+        errorUserTitle: result.errorUserTitle,
+        errorUserMsg: result.errorUserMsg,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function checkReportStatusResponseFormatter(result) {
+    const pct = result.asyncPercentCompletion != null ? ` (${result.asyncPercentCompletion}%)` : "";
+    const failureDetail = result.state === "failed"
+        ? [
+            result.errorUserTitle,
+            result.errorUserMsg ?? result.errorMessage,
+            result.errorCode != null ? `code=${result.errorCode}` : undefined,
+            result.errorSubcode != null ? `subcode=${result.errorSubcode}` : undefined,
+        ]
+            .filter(Boolean)
+            .join(" | ")
+        : "";
+    const next = result.isComplete
+        ? `\n\nReport complete — call \`meta_download_report\` with reportRunId: "${result.reportRunId}"`
+        : result.state === "failed"
+            ? `\n\nReport failed${failureDetail ? `: ${failureDetail}` : ""}. Submit a new report with \`meta_submit_report\`.`
+            : `\n\nReport in progress${pct}. Poll again in ~10 seconds.`;
+    return [
+        {
+            type: "text",
+            text: `Report ${result.reportRunId}: ${result.state} (${result.rawStatus})${next}\n\nTimestamp: ${result.timestamp}`,
+        },
+    ];
+}
+export const checkReportStatusTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: CheckReportStatusInputSchema,
+    outputSchema: CheckReportStatusOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    },
+    inputExamples: [
+        {
+            label: "Check status of a submitted report",
+            input: {
+                reportRunId: "6082575495383",
+            },
+        },
+    ],
+    logic: checkReportStatusLogic,
+    responseFormatter: checkReportStatusResponseFormatter,
+};
+//# sourceMappingURL=check-report-status.tool.js.map

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

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

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

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const CreateEntityInputSchema: z.ZodObject<{
+    entityType: z.ZodEnum<[string, ...string[]]>;
+    adAccountId: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodAny>;
+}, "strip", z.ZodTypeAny, {
+    data: Record<string, any>;
+    entityType: string;
+    adAccountId: string;
+}, {
+    data: Record<string, any>;
+    entityType: string;
+    adAccountId: string;
+}>;
+export declare const CreateEntityOutputSchema: z.ZodObject<{
+    entity: z.ZodRecord<z.ZodString, z.ZodAny>;
+    entityType: z.ZodString;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    entityType: string;
+    timestamp: string;
+    entity: Record<string, any>;
+}, {
+    entityType: string;
+    timestamp: string;
+    entity: Record<string, any>;
+}>;
+type CreateEntityInput = z.infer<typeof CreateEntityInputSchema>;
+type CreateEntityOutput = z.infer<typeof CreateEntityOutputSchema>;
+export declare function createEntityLogic(input: CreateEntityInput, context: RequestContext, sdkContext?: SdkContext): Promise<CreateEntityOutput>;
+export declare function createEntityResponseFormatter(result: CreateEntityOutput): McpTextContent[];
+export declare const createEntityTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        entityType: z.ZodEnum<[string, ...string[]]>;
+        adAccountId: z.ZodString;
+        data: z.ZodRecord<z.ZodString, z.ZodAny>;
+    }, "strip", z.ZodTypeAny, {
+        data: Record<string, any>;
+        entityType: string;
+        adAccountId: string;
+    }, {
+        data: Record<string, any>;
+        entityType: string;
+        adAccountId: string;
+    }>;
+    outputSchema: z.ZodObject<{
+        entity: z.ZodRecord<z.ZodString, z.ZodAny>;
+        entityType: z.ZodString;
+        timestamp: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        entityType: string;
+        timestamp: string;
+        entity: Record<string, any>;
+    }, {
+        entityType: string;
+        timestamp: string;
+        entity: Record<string, any>;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+    };
+    inputExamples: ({
+        label: string;
+        input: {
+            entityType: string;
+            adAccountId: string;
+            data: {
+                name: string;
+                objective: string;
+                status: string;
+                special_ad_categories: never[];
+                campaign_id?: undefined;
+                optimization_goal?: undefined;
+                billing_event?: undefined;
+                daily_budget?: undefined;
+                targeting?: undefined;
+            };
+        };
+    } | {
+        label: string;
+        input: {
+            entityType: string;
+            adAccountId: string;
+            data: {
+                name: string;
+                campaign_id: string;
+                optimization_goal: string;
+                billing_event: string;
+                daily_budget: number;
+                targeting: {
+                    age_min: number;
+                    age_max: number;
+                    geo_locations: {
+                        countries: string[];
+                    };
+                };
+                status: string;
+                objective?: undefined;
+                special_ad_categories?: undefined;
+            };
+        };
+    })[];
+    logic: typeof createEntityLogic;
+    responseFormatter: typeof createEntityResponseFormatter;
+};
+export {};
+//# sourceMappingURL=create-entity.tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/create-entity.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAsBnD,eAAO,MAAM,uBAAuB;;;;;;;;;;;;EAMoB,CAAC;AAEzD,eAAO,MAAM,wBAAwB;;;;;;;;;;;;EAMA,CAAC;AAEtC,KAAK,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACjE,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEnE,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAe7B;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,kBAAkB,GAAG,cAAc,EAAE,CAO1F;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiD5B,CAAC"}

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

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { getEntityTypeEnum } from "../utils/entity-mapping.js";
+const TOOL_NAME = "meta_create_entity";
+const TOOL_TITLE = "Create Meta Ads Entity";
+const TOOL_DESCRIPTION = `Create a new Meta Ads entity.
+
+**Supported entity types:** ${getEntityTypeEnum().join(", ")}
+
+All entities are created under an ad account via POST /act_{id}/{edge}.
+
+**Key requirements by entity type:**
+- **campaign**: requires \`name\`, \`objective\` (e.g., OUTCOME_AWARENESS), \`special_ad_categories\` (array, can be empty [])
+- **adSet**: requires \`name\`, \`campaign_id\`, \`optimization_goal\`, \`billing_event\`, \`targeting\`, \`status\`
+- **ad**: requires \`name\`, \`adset_id\`, \`creative\` (object with creative_id)
+- **adCreative**: requires \`name\` and creative content fields (object_story_spec, etc.)
+- **customAudience**: requires \`name\`, \`subtype\`
+
+**Gotchas:**
+- Budget values are in cents (1000 = $10 USD)
+- Campaigns need \`special_ad_categories\` even if empty ([])
+- Writes are rate-limited at 3x read cost`;
+export const CreateEntityInputSchema = z
+    .object({
+    entityType: z.enum(getEntityTypeEnum()).describe("Type of entity to create"),
+    adAccountId: z.string().describe("Ad Account ID (with or without act_ prefix)"),
+    data: z.record(z.any()).describe("Entity fields as key-value pairs"),
+})
+    .describe("Parameters for creating a Meta Ads entity");
+export const CreateEntityOutputSchema = z
+    .object({
+    entity: z.record(z.any()).describe("Created entity (returns id at minimum)"),
+    entityType: z.string(),
+    timestamp: z.string().datetime(),
+})
+    .describe("Entity creation result");
+export async function createEntityLogic(input, context, sdkContext) {
+    const { metaService } = resolveSessionServices(sdkContext);
+    const entity = await metaService.createEntity(input.entityType, input.adAccountId, input.data, context);
+    return {
+        entity: entity,
+        entityType: input.entityType,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function createEntityResponseFormatter(result) {
+    return [
+        {
+            type: "text",
+            text: `${result.entityType} created successfully\n${JSON.stringify(result.entity, null, 2)}\n\nTimestamp: ${result.timestamp}`,
+        },
+    ];
+}
+export const createEntityTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: CreateEntityInputSchema,
+    outputSchema: CreateEntityOutputSchema,
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: false,
+        idempotentHint: false,
+        destructiveHint: true,
+    },
+    inputExamples: [
+        {
+            label: "Create a traffic campaign",
+            input: {
+                entityType: "campaign",
+                adAccountId: "act_123456789",
+                data: {
+                    name: "Summer Sale 2026",
+                    objective: "OUTCOME_TRAFFIC",
+                    status: "PAUSED",
+                    special_ad_categories: [],
+                },
+            },
+        },
+        {
+            label: "Create an ad set",
+            input: {
+                entityType: "adSet",
+                adAccountId: "act_123456789",
+                data: {
+                    name: "US 25-44 Interest Targeting",
+                    campaign_id: "23456789012345",
+                    optimization_goal: "LINK_CLICKS",
+                    billing_event: "IMPRESSIONS",
+                    daily_budget: 5000,
+                    targeting: {
+                        age_min: 25,
+                        age_max: 44,
+                        geo_locations: { countries: ["US"] },
+                    },
+                    status: "PAUSED",
+                },
+            },
+        },
+    ],
+    logic: createEntityLogic,
+    responseFormatter: createEntityResponseFormatter,
+};
+//# sourceMappingURL=create-entity.tool.js.map

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

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

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

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const DeleteEntityInputSchema: z.ZodObject<{
+    entityType: z.ZodEnum<[string, ...string[]]>;
+    entityId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    entityType: string;
+    entityId: string;
+}, {
+    entityType: string;
+    entityId: string;
+}>;
+export declare const DeleteEntityOutputSchema: z.ZodObject<{
+    confirmed: z.ZodBoolean;
+    declineReason: z.ZodOptional<z.ZodString>;
+    success: z.ZodBoolean;
+    entityId: z.ZodString;
+    entityType: z.ZodString;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    entityType: string;
+    entityId: string;
+    timestamp: string;
+    success: boolean;
+    confirmed: boolean;
+    declineReason?: string | undefined;
+}, {
+    entityType: string;
+    entityId: string;
+    timestamp: string;
+    success: boolean;
+    confirmed: boolean;
+    declineReason?: string | undefined;
+}>;
+type DeleteEntityInput = z.infer<typeof DeleteEntityInputSchema>;
+type DeleteEntityOutput = z.infer<typeof DeleteEntityOutputSchema>;
+export declare function deleteEntityLogic(input: DeleteEntityInput, context: RequestContext, sdkContext?: SdkContext): Promise<DeleteEntityOutput>;
+export declare function deleteEntityResponseFormatter(result: DeleteEntityOutput): McpTextContent[];
+export declare const deleteEntityTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        entityType: z.ZodEnum<[string, ...string[]]>;
+        entityId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        entityType: string;
+        entityId: string;
+    }, {
+        entityType: string;
+        entityId: string;
+    }>;
+    outputSchema: z.ZodObject<{
+        confirmed: z.ZodBoolean;
+        declineReason: z.ZodOptional<z.ZodString>;
+        success: z.ZodBoolean;
+        entityId: z.ZodString;
+        entityType: z.ZodString;
+        timestamp: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        entityType: string;
+        entityId: string;
+        timestamp: string;
+        success: boolean;
+        confirmed: boolean;
+        declineReason?: string | undefined;
+    }, {
+        entityType: string;
+        entityId: string;
+        timestamp: string;
+        success: boolean;
+        confirmed: boolean;
+        declineReason?: string | undefined;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+    };
+    inputExamples: {
+        label: string;
+        input: {
+            entityType: string;
+            entityId: string;
+        };
+    }[];
+    logic: typeof deleteEntityLogic;
+    responseFormatter: typeof deleteEntityResponseFormatter;
+};
+export {};
+//# sourceMappingURL=delete-entity.tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delete-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/delete-entity.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAgBnD,eAAO,MAAM,uBAAuB;;;;;;;;;EAKoB,CAAC;AAEzD,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;EASA,CAAC;AAEtC,KAAK,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACjE,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEnE,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,kBAAkB,CAAC,CA6B7B;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,kBAAkB,GAAG,cAAc,EAAE,CAgB1F;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuB5B,CAAC"}