@cesteral/tiktok-mcp 1.0.0

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

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { getEntityTypeEnum } from "../utils/entity-mapping.js";
+const TOOL_NAME = "tiktok_update_entity";
+const TOOL_TITLE = "Update TikTok Ads Entity";
+const TOOL_DESCRIPTION = `Update a TikTok Ads entity.
+
+**Supported entity types:** ${getEntityTypeEnum().join(", ")}
+
+TikTok uses POST for updates with entity ID in the body. Only provided fields are modified.
+
+**Gotchas:**
+- Use \`tiktok_bulk_update_status\` for status-only changes (more efficient)
+- advertiser_id is automatically injected`;
+export const UpdateEntityInputSchema = z
+    .object({
+    entityType: z.enum(getEntityTypeEnum()).describe("Type of entity to update"),
+    advertiserId: z.string().min(1).describe("TikTok Advertiser ID"),
+    entityId: z.string().min(1).describe("The entity ID to update"),
+    data: z.record(z.any()).describe("Fields to update as key-value pairs"),
+})
+    .describe("Parameters for updating a TikTok Ads entity");
+export const UpdateEntityOutputSchema = z
+    .object({
+    entityId: z.string(),
+    entityType: z.string(),
+    updated: z.boolean(),
+    timestamp: z.string().datetime(),
+})
+    .describe("Entity update result");
+export async function updateEntityLogic(input, context, sdkContext) {
+    const { tiktokService } = resolveSessionServices(sdkContext);
+    await tiktokService.updateEntity(input.entityType, input.entityId, input.data, context);
+    return {
+        entityId: input.entityId,
+        entityType: input.entityType,
+        updated: true,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function updateEntityResponseFormatter(result) {
+    return [
+        {
+            type: "text",
+            text: `${result.entityType} ${result.entityId} updated successfully\n\nTimestamp: ${result.timestamp}`,
+        },
+    ];
+}
+export const updateEntityTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: UpdateEntityInputSchema,
+    outputSchema: UpdateEntityOutputSchema,
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: false,
+        idempotentHint: true,
+        destructiveHint: false,
+    },
+    inputExamples: [
+        {
+            label: "Update campaign name and budget",
+            input: {
+                entityType: "campaign",
+                advertiserId: "1234567890",
+                entityId: "1800123456789",
+                data: {
+                    campaign_name: "Updated Campaign Name",
+                    budget: 200,
+                },
+            },
+        },
+        {
+            label: "Update ad group bid",
+            input: {
+                entityType: "adGroup",
+                advertiserId: "1234567890",
+                entityId: "1700123456789",
+                data: {
+                    bid_price: 1.5,
+                },
+            },
+        },
+    ],
+    logic: updateEntityLogic,
+    responseFormatter: updateEntityResponseFormatter,
+};
+//# sourceMappingURL=update-entity.tool.js.map

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

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

package/dist/mcp-server/tools/definitions/upload-image.tool.d.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const UploadImageInputSchema: z.ZodObject<{
+    advertiserId: z.ZodString;
+    mediaUrl: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    advertiserId: string;
+    mediaUrl: string;
+    filename?: string | undefined;
+}, {
+    advertiserId: string;
+    mediaUrl: string;
+    filename?: string | undefined;
+}>;
+export declare const UploadImageOutputSchema: z.ZodObject<{
+    imageId: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    size: z.ZodOptional<z.ZodNumber>;
+    uploadedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    imageId: string;
+    uploadedAt: string;
+    url?: string | undefined;
+    size?: number | undefined;
+}, {
+    imageId: string;
+    uploadedAt: string;
+    url?: string | undefined;
+    size?: number | undefined;
+}>;
+type UploadImageInput = z.infer<typeof UploadImageInputSchema>;
+type UploadImageOutput = z.infer<typeof UploadImageOutputSchema>;
+export declare function uploadImageLogic(input: UploadImageInput, context: RequestContext, sdkContext?: SdkContext): Promise<UploadImageOutput>;
+export declare function uploadImageResponseFormatter(result: UploadImageOutput): McpTextContent[];
+export declare const uploadImageTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        advertiserId: z.ZodString;
+        mediaUrl: z.ZodString;
+        filename: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        advertiserId: string;
+        mediaUrl: string;
+        filename?: string | undefined;
+    }, {
+        advertiserId: string;
+        mediaUrl: string;
+        filename?: string | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        imageId: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+        uploadedAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        imageId: string;
+        uploadedAt: string;
+        url?: string | undefined;
+        size?: number | undefined;
+    }, {
+        imageId: string;
+        uploadedAt: string;
+        url?: string | undefined;
+        size?: number | undefined;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+    };
+    inputExamples: {
+        label: string;
+        input: {
+            advertiserId: string;
+            mediaUrl: string;
+        };
+    }[];
+    logic: typeof uploadImageLogic;
+    responseFormatter: typeof uploadImageResponseFormatter;
+};
+export {};
+//# sourceMappingURL=upload-image.tool.d.ts.map

package/dist/mcp-server/tools/definitions/upload-image.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-image.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/upload-image.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;AAgBnD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;EAUuB,CAAC;AAE3D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;EAOK,CAAC;AAE1C,KAAK,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC/D,KAAK,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAQjE,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAmC5B;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAOxF;AAED,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuB3B,CAAC"}

package/dist/mcp-server/tools/definitions/upload-image.tool.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { downloadFileToBuffer, McpError, JsonRpcErrorCode } from "@cesteral/shared";
+const TOOL_NAME = "tiktok_upload_image";
+const TOOL_TITLE = "Upload Image to TikTok Ads";
+const TOOL_DESCRIPTION = `Upload an image to TikTok Ads Library from a URL.
+
+The server downloads the image and uploads it to TikTok's ad image library.
+Returns the imageId for use in ad creatives.
+
+**Image requirements:**
+- Formats: JPEG, PNG
+- Max file size: 100KB (for feed ads), 500KB (for other placements)
+- Recommended dimensions: 1200x628px, 1080x1080px, 720x1280px
+
+**Usage:** The returned imageId is used in ad creative payloads.`;
+export const UploadImageInputSchema = z
+    .object({
+    advertiserId: z
+        .string()
+        .describe("TikTok Advertiser ID (informational — the session-bound advertiser from authentication is used for API calls)"),
+    mediaUrl: z.string().url().describe("Publicly accessible URL of the image to upload"),
+    filename: z.string().optional().describe("Override filename (otherwise derived from URL)"),
+})
+    .describe("Parameters for uploading an image to TikTok");
+export const UploadImageOutputSchema = z
+    .object({
+    imageId: z.string().describe("Image ID for use in ad creative payloads"),
+    url: z.string().optional().describe("Preview URL of the uploaded image"),
+    size: z.number().optional().describe("File size in bytes"),
+    uploadedAt: z.string().datetime(),
+})
+    .describe("Uploaded TikTok image info");
+export async function uploadImageLogic(input, context, sdkContext) {
+    const { tiktokService } = resolveSessionServices(sdkContext);
+    const { buffer, contentType, filename } = await downloadFileToBuffer(input.mediaUrl, 120_000, context);
+    const effectiveFilename = input.filename ?? filename;
+    const result = (await tiktokService.client.postMultipart(tiktokService.client.versionedPath("file/image/ad/upload/"), {}, "image_file", buffer, effectiveFilename, contentType, context));
+    const imageId = result.image_id;
+    if (!imageId) {
+        throw new McpError(JsonRpcErrorCode.InternalError, "TikTok image upload failed: no image_id returned");
+    }
+    return {
+        imageId,
+        url: result.image_url,
+        size: result.size,
+        uploadedAt: new Date().toISOString(),
+    };
+}
+export function uploadImageResponseFormatter(result) {
+    return [
+        {
+            type: "text",
+            text: `Image uploaded to TikTok!\n\nImage ID: ${result.imageId}${result.url ? `\nPreview URL: ${result.url}` : ""}${result.size !== undefined ? `\nSize: ${result.size} bytes` : ""}\n\nUse imageId in your ad creative payload`,
+        },
+    ];
+}
+export const uploadImageTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: UploadImageInputSchema,
+    outputSchema: UploadImageOutputSchema,
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: true,
+        idempotentHint: false,
+        destructiveHint: false,
+    },
+    inputExamples: [
+        {
+            label: "Upload a TikTok ad image",
+            input: {
+                advertiserId: "1234567890",
+                mediaUrl: "https://example.com/banner.jpg",
+            },
+        },
+    ],
+    logic: uploadImageLogic,
+    responseFormatter: uploadImageResponseFormatter,
+};
+//# sourceMappingURL=upload-image.tool.js.map

package/dist/mcp-server/tools/definitions/upload-image.tool.js.map

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

package/dist/mcp-server/tools/definitions/upload-video.tool.d.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const UploadVideoInputSchema: z.ZodObject<{
+    advertiserId: z.ZodString;
+    mediaUrl: z.ZodString;
+    videoName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    advertiserId: string;
+    mediaUrl: string;
+    videoName?: string | undefined;
+}, {
+    advertiserId: string;
+    mediaUrl: string;
+    videoName?: string | undefined;
+}>;
+export declare const UploadVideoOutputSchema: z.ZodObject<{
+    videoId: z.ZodString;
+    videoName: z.ZodOptional<z.ZodString>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    uploadedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    uploadedAt: string;
+    videoId: string;
+    videoName?: string | undefined;
+    duration?: number | undefined;
+}, {
+    uploadedAt: string;
+    videoId: string;
+    videoName?: string | undefined;
+    duration?: number | undefined;
+}>;
+type UploadVideoInput = z.infer<typeof UploadVideoInputSchema>;
+type UploadVideoOutput = z.infer<typeof UploadVideoOutputSchema>;
+export declare function uploadVideoLogic(input: UploadVideoInput, context: RequestContext, sdkContext?: SdkContext): Promise<UploadVideoOutput>;
+export declare function uploadVideoResponseFormatter(result: UploadVideoOutput): McpTextContent[];
+export declare const uploadVideoTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        advertiserId: z.ZodString;
+        mediaUrl: z.ZodString;
+        videoName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        advertiserId: string;
+        mediaUrl: string;
+        videoName?: string | undefined;
+    }, {
+        advertiserId: string;
+        mediaUrl: string;
+        videoName?: string | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        videoId: z.ZodString;
+        videoName: z.ZodOptional<z.ZodString>;
+        duration: z.ZodOptional<z.ZodNumber>;
+        uploadedAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        uploadedAt: string;
+        videoId: string;
+        videoName?: string | undefined;
+        duration?: number | undefined;
+    }, {
+        uploadedAt: string;
+        videoId: string;
+        videoName?: string | undefined;
+        duration?: number | undefined;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+    };
+    inputExamples: {
+        label: string;
+        input: {
+            advertiserId: string;
+            mediaUrl: string;
+            videoName: string;
+        };
+    }[];
+    logic: typeof uploadVideoLogic;
+    responseFormatter: typeof uploadVideoResponseFormatter;
+};
+export {};
+//# sourceMappingURL=upload-video.tool.d.ts.map

package/dist/mcp-server/tools/definitions/upload-video.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-video.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/upload-video.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAkBnD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;EAUsB,CAAC;AAE1D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;EAOK,CAAC;AAE1C,KAAK,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC/D,KAAK,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAkBjE,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,iBAAiB,CAAC,CA0E5B;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAOxF;AAED,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwB3B,CAAC"}

package/dist/mcp-server/tools/definitions/upload-video.tool.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { downloadFileToBuffer, McpError, JsonRpcErrorCode, pollUntilComplete, ReportTimeoutError, ReportFailedError, } from "@cesteral/shared";
+import { mcpConfig } from "../../../config/index.js";
+const TOOL_NAME = "tiktok_upload_video";
+const TOOL_TITLE = "Upload Video to TikTok Ads";
+const TOOL_DESCRIPTION = `Upload a video to TikTok Ads Library from a URL.
+
+The server downloads the video and uploads it to TikTok's ad video library.
+Polls until binding is complete (up to 10 minutes).
+
+**Video requirements:**
+- Formats: MP4, MOV, AVI (H.264/H.265 codec recommended)
+- Max file size: 500MB
+- Min resolution: 540x960px (9:16), 960x540px (16:9), or 640x640px (1:1)
+- Duration: 5 to 60 seconds for In-Feed ads
+
+**Usage:** The returned videoId is used in ad creative payloads.`;
+export const UploadVideoInputSchema = z
+    .object({
+    advertiserId: z
+        .string()
+        .describe("TikTok Advertiser ID (informational — the session-bound advertiser from authentication is used for API calls)"),
+    mediaUrl: z.string().url().describe("Publicly accessible URL of the video to upload"),
+    videoName: z.string().optional().describe("Optional name for the video in the library"),
+})
+    .describe("Parameters for uploading a video to TikTok");
+export const UploadVideoOutputSchema = z
+    .object({
+    videoId: z.string().describe("Video ID for use in ad creative payloads"),
+    videoName: z.string().optional(),
+    duration: z.number().optional().describe("Video duration in seconds"),
+    uploadedAt: z.string().datetime(),
+})
+    .describe("Uploaded TikTok video info");
+export async function uploadVideoLogic(input, context, sdkContext) {
+    const { tiktokService } = resolveSessionServices(sdkContext);
+    const { buffer, contentType, filename } = await downloadFileToBuffer(input.mediaUrl, 600_000, context);
+    const fields = {};
+    if (input.videoName)
+        fields.video_name = input.videoName;
+    const uploadResult = (await tiktokService.client.postMultipart(tiktokService.client.versionedPath("file/video/ad/upload/"), fields, "video_file", buffer, filename, contentType, context));
+    const videoId = uploadResult.video_id;
+    if (!videoId) {
+        throw new McpError(JsonRpcErrorCode.InternalError, "TikTok video upload failed: no video_id returned");
+    }
+    const maxAttempts = mcpConfig.tiktokVideoUploadMaxPollAttempts;
+    const pollIntervalMs = mcpConfig.tiktokVideoUploadPollIntervalMs;
+    try {
+        const videoInfo = await pollUntilComplete({
+            fetchStatus: async () => {
+                const statusResult = (await tiktokService.client.get(tiktokService.client.versionedPath("file/video/ad/info/"), { video_ids: JSON.stringify([videoId]) }, context));
+                return statusResult.list?.[0];
+            },
+            isComplete: (info) => info?.video_status === "bind_success",
+            isFailed: (info) => info?.video_status === "error" || info?.video_status === "deleted",
+            initialDelayMs: pollIntervalMs,
+            maxDelayMs: pollIntervalMs,
+            maxAttempts,
+            backoffFactor: 1,
+        });
+        return {
+            videoId,
+            videoName: videoInfo?.video_name ?? input.videoName,
+            duration: videoInfo?.duration,
+            uploadedAt: new Date().toISOString(),
+        };
+    }
+    catch (error) {
+        if (error instanceof ReportFailedError) {
+            const status = error.status?.video_status ?? "unknown";
+            throw new McpError(JsonRpcErrorCode.InternalError, `TikTok video processing failed: status=${status}`);
+        }
+        if (error instanceof ReportTimeoutError) {
+            throw new McpError(JsonRpcErrorCode.InternalError, `Video ${videoId} upload timed out: binding did not complete after ${maxAttempts} polling attempts (${(maxAttempts * pollIntervalMs) / 1000}s). The video may still be processing — check status manually.`);
+        }
+        throw error;
+    }
+}
+export function uploadVideoResponseFormatter(result) {
+    return [
+        {
+            type: "text",
+            text: `Video uploaded to TikTok!\n\nVideo ID: ${result.videoId}${result.videoName ? `\nName: ${result.videoName}` : ""}${result.duration !== undefined ? `\nDuration: ${result.duration}s` : ""}\n\nUse videoId in your ad creative payload`,
+        },
+    ];
+}
+export const uploadVideoTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: UploadVideoInputSchema,
+    outputSchema: UploadVideoOutputSchema,
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: true,
+        idempotentHint: false,
+        destructiveHint: false,
+    },
+    inputExamples: [
+        {
+            label: "Upload a TikTok campaign video",
+            input: {
+                advertiserId: "1234567890",
+                mediaUrl: "https://example.com/video.mp4",
+                videoName: "Summer Campaign 2025",
+            },
+        },
+    ],
+    logic: uploadVideoLogic,
+    responseFormatter: uploadVideoResponseFormatter,
+};
+//# sourceMappingURL=upload-video.tool.js.map

package/dist/mcp-server/tools/definitions/upload-video.tool.js.map

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