@cesteral/tiktok-mcp 1.0.0

package/dist/mcp-server/prompts/index.js

@@ -0,0 +1,97 @@
+import { campaignSetupWorkflowPrompt, getCampaignSetupWorkflowMessage, } from "./definitions/campaign-setup-workflow.prompt.js";
+import { bulkOperationsWorkflowPrompt, getBulkOperationsWorkflowMessage, } from "./definitions/bulk-operations-workflow.prompt.js";
+import { tiktokToolSchemaExplorationPrompt, getTiktokToolSchemaExplorationMessage, } from "./definitions/tool-schema-exploration.prompt.js";
+import { tiktokTroubleshootEntityPrompt, getTiktokTroubleshootEntityMessage, } from "./definitions/troubleshoot-entity.prompt.js";
+import { tiktokReportingWorkflowPrompt, getTiktokReportingWorkflowMessage, } from "./definitions/reporting-workflow.prompt.js";
+import { tiktokEntityUpdateWorkflowPrompt, getTiktokEntityUpdateWorkflowMessage, } from "./definitions/entity-update-workflow.prompt.js";
+import { tiktokTargetingDiscoveryWorkflowPrompt, getTiktokTargetingDiscoveryWorkflowMessage, } from "./definitions/targeting-discovery-workflow.prompt.js";
+import { tiktokEntityDuplicationWorkflowPrompt, getTiktokEntityDuplicationWorkflowMessage, } from "./definitions/entity-duplication-workflow.prompt.js";
+import { crossPlatformPerformancePrompt, getCrossPlatformPerformanceMessage, } from "./definitions/cross-platform-performance.prompt.js";
+import { crossPlatformCampaignSetupPrompt, getCrossPlatformCampaignSetupMessage, } from "./definitions/cross-platform-campaign-setup.prompt.js";
+import { tiktokCreativeUploadWorkflowPrompt, getTiktokCreativeUploadWorkflowMessage, } from "./definitions/creative-upload-workflow.prompt.js";
+export const promptRegistry = new Map([
+    [
+        campaignSetupWorkflowPrompt.name,
+        {
+            prompt: campaignSetupWorkflowPrompt,
+            generateMessage: getCampaignSetupWorkflowMessage,
+        },
+    ],
+    [
+        bulkOperationsWorkflowPrompt.name,
+        {
+            prompt: bulkOperationsWorkflowPrompt,
+            generateMessage: getBulkOperationsWorkflowMessage,
+        },
+    ],
+    [
+        tiktokToolSchemaExplorationPrompt.name,
+        {
+            prompt: tiktokToolSchemaExplorationPrompt,
+            generateMessage: getTiktokToolSchemaExplorationMessage,
+        },
+    ],
+    [
+        tiktokTroubleshootEntityPrompt.name,
+        {
+            prompt: tiktokTroubleshootEntityPrompt,
+            generateMessage: getTiktokTroubleshootEntityMessage,
+        },
+    ],
+    [
+        tiktokReportingWorkflowPrompt.name,
+        {
+            prompt: tiktokReportingWorkflowPrompt,
+            generateMessage: getTiktokReportingWorkflowMessage,
+        },
+    ],
+    [
+        tiktokEntityUpdateWorkflowPrompt.name,
+        {
+            prompt: tiktokEntityUpdateWorkflowPrompt,
+            generateMessage: getTiktokEntityUpdateWorkflowMessage,
+        },
+    ],
+    [
+        tiktokTargetingDiscoveryWorkflowPrompt.name,
+        {
+            prompt: tiktokTargetingDiscoveryWorkflowPrompt,
+            generateMessage: getTiktokTargetingDiscoveryWorkflowMessage,
+        },
+    ],
+    [
+        tiktokEntityDuplicationWorkflowPrompt.name,
+        {
+            prompt: tiktokEntityDuplicationWorkflowPrompt,
+            generateMessage: getTiktokEntityDuplicationWorkflowMessage,
+        },
+    ],
+    [
+        crossPlatformPerformancePrompt.name,
+        {
+            prompt: crossPlatformPerformancePrompt,
+            generateMessage: getCrossPlatformPerformanceMessage,
+        },
+    ],
+    [
+        crossPlatformCampaignSetupPrompt.name,
+        {
+            prompt: crossPlatformCampaignSetupPrompt,
+            generateMessage: getCrossPlatformCampaignSetupMessage,
+        },
+    ],
+    [
+        tiktokCreativeUploadWorkflowPrompt.name,
+        {
+            prompt: tiktokCreativeUploadWorkflowPrompt,
+            generateMessage: getTiktokCreativeUploadWorkflowMessage,
+        },
+    ],
+]);
+export function getAllPrompts() {
+    return Array.from(promptRegistry.values()).map((def) => def.prompt);
+}
+export function getPromptDefinition(name) {
+    return promptRegistry.get(name);
+}
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/prompts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp-server/prompts/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,iDAAiD,CAAC;AACzD,OAAO,EACL,4BAA4B,EAC5B,gCAAgC,GACjC,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EACL,iCAAiC,EACjC,qCAAqC,GACtC,MAAM,iDAAiD,CAAC;AACzD,OAAO,EACL,8BAA8B,EAC9B,kCAAkC,GACnC,MAAM,6CAA6C,CAAC;AACrD,OAAO,EACL,6BAA6B,EAC7B,iCAAiC,GAClC,MAAM,4CAA4C,CAAC;AACpD,OAAO,EACL,gCAAgC,EAChC,oCAAoC,GACrC,MAAM,gDAAgD,CAAC;AACxD,OAAO,EACL,sCAAsC,EACtC,0CAA0C,GAC3C,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EACL,qCAAqC,EACrC,yCAAyC,GAC1C,MAAM,qDAAqD,CAAC;AAC7D,OAAO,EACL,8BAA8B,EAC9B,kCAAkC,GACnC,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EACL,gCAAgC,EAChC,oCAAoC,GACrC,MAAM,uDAAuD,CAAC;AAC/D,OAAO,EACL,kCAAkC,EAClC,sCAAsC,GACvC,MAAM,kDAAkD,CAAC;AAO1D,MAAM,CAAC,MAAM,cAAc,GAAkC,IAAI,GAAG,CAAC;IACnE;QACE,2BAA2B,CAAC,IAAI;QAChC;YACE,MAAM,EAAE,2BAA2B;YACnC,eAAe,EAAE,+BAA+B;SACjD;KACF;IACD;QACE,4BAA4B,CAAC,IAAI;QACjC;YACE,MAAM,EAAE,4BAA4B;YACpC,eAAe,EAAE,gCAAgC;SAClD;KACF;IACD;QACE,iCAAiC,CAAC,IAAI;QACtC;YACE,MAAM,EAAE,iCAAiC;YACzC,eAAe,EAAE,qCAAqC;SACvD;KACF;IACD;QACE,8BAA8B,CAAC,IAAI;QACnC;YACE,MAAM,EAAE,8BAA8B;YACtC,eAAe,EAAE,kCAAkC;SACpD;KACF;IACD;QACE,6BAA6B,CAAC,IAAI;QAClC;YACE,MAAM,EAAE,6BAA6B;YACrC,eAAe,EAAE,iCAAiC;SACnD;KACF;IACD;QACE,gCAAgC,CAAC,IAAI;QACrC;YACE,MAAM,EAAE,gCAAgC;YACxC,eAAe,EAAE,oCAAoC;SACtD;KACF;IACD;QACE,sCAAsC,CAAC,IAAI;QAC3C;YACE,MAAM,EAAE,sCAAsC;YAC9C,eAAe,EAAE,0CAA0C;SAC5D;KACF;IACD;QACE,qCAAqC,CAAC,IAAI;QAC1C;YACE,MAAM,EAAE,qCAAqC;YAC7C,eAAe,EAAE,yCAAyC;SAC3D;KACF;IACD;QACE,8BAA8B,CAAC,IAAI;QACnC;YACE,MAAM,EAAE,8BAA8B;YACtC,eAAe,EAAE,kCAAkC;SACpD;KACF;IACD;QACE,gCAAgC,CAAC,IAAI;QACrC;YACE,MAAM,EAAE,gCAAgC;YACxC,eAAe,EAAE,oCAAoC;SACtD;KACF;IACD;QACE,kCAAkC,CAAC,IAAI;QACvC;YACE,MAAM,EAAE,kCAAkC;YAC1C,eAAe,EAAE,sCAAsC;SACxD;KACF;CACF,CAAC,CAAC;AAEH,MAAM,UAAU,aAAa;IAC3B,OAAO,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/dist/mcp-server/resources/definitions/entity-examples.resource.d.ts

@@ -0,0 +1,4 @@
+import type { Resource } from "../types.js";
+export declare const entityExampleResources: Resource[];
+export declare const entityExampleAllResource: Resource;
+//# sourceMappingURL=entity-examples.resource.d.ts.map

package/dist/mcp-server/resources/definitions/entity-examples.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-examples.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-examples.resource.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAgL5C,eAAO,MAAM,sBAAsB,EAAE,QAAQ,EAQ1C,CAAC;AAEJ,eAAO,MAAM,wBAAwB,EAAE,QAMtC,CAAC"}

package/dist/mcp-server/resources/definitions/entity-examples.resource.js

@@ -0,0 +1,182 @@
+import { getSupportedEntityTypes, } from "../../tools/utils/entity-mapping.js";
+const ENTITY_EXAMPLE_CONTENT = {
+    campaign: `# TikTok Campaign Examples
+
+## Create a Traffic Campaign (daily budget)
+\`\`\`json
+{
+  "entityType": "campaign",
+  "advertiserId": "1234567890",
+  "data": {
+    "campaign_name": "Summer Sale 2026 - Traffic",
+    "objective_type": "TRAFFIC",
+    "budget_mode": "BUDGET_MODE_DAY",
+    "budget": 100
+  }
+}
+\`\`\`
+
+## Create an App Install Campaign (lifetime budget)
+\`\`\`json
+{
+  "entityType": "campaign",
+  "advertiserId": "1234567890",
+  "data": {
+    "campaign_name": "App Install Q1 2026",
+    "objective_type": "APP_PROMOTION",
+    "budget_mode": "BUDGET_MODE_TOTAL",
+    "budget": 5000,
+    "app_promotion_type": "APP_INSTALL"
+  }
+}
+\`\`\`
+
+## Update Campaign Budget
+\`\`\`json
+{
+  "entityType": "campaign",
+  "advertiserId": "1234567890",
+  "entityId": "1800123456789",
+  "data": {
+    "budget": 200
+  }
+}
+\`\`\`
+`,
+    adGroup: `# TikTok Ad Group Examples
+
+## Create an Ad Group with Interest Targeting
+\`\`\`json
+{
+  "entityType": "adGroup",
+  "advertiserId": "1234567890",
+  "data": {
+    "campaign_id": "1800123456789",
+    "adgroup_name": "US Gaming 18-34",
+    "placements": ["PLACEMENT_TIKTOK"],
+    "budget_mode": "BUDGET_MODE_DAY",
+    "budget": 50,
+    "schedule_type": "SCHEDULE_START_END",
+    "pacing": "PACING_MODE_SMOOTH",
+    "schedule_start_time": "2026-03-01 00:00:00",
+    "schedule_end_time": "2026-03-31 23:59:59",
+    "optimization_goal": "CLICK",
+    "bid_price": 0.5,
+    "age": ["AGE_18_24", "AGE_25_34"],
+    "gender": ["GENDER_UNLIMITED"],
+    "location_ids": ["US"],
+    "interest_category_ids": ["123456789"]
+  }
+}
+\`\`\`
+
+## Create an Always-On Ad Group (no schedule end)
+\`\`\`json
+{
+  "entityType": "adGroup",
+  "advertiserId": "1234567890",
+  "data": {
+    "campaign_id": "1800123456789",
+    "adgroup_name": "Retargeting - Website Visitors",
+    "placements": ["PLACEMENT_TIKTOK"],
+    "budget_mode": "BUDGET_MODE_DAY",
+    "budget": 30,
+    "schedule_type": "SCHEDULE_ALWAYS",
+    "optimization_goal": "CLICK"
+  }
+}
+\`\`\`
+`,
+    ad: `# TikTok Ad Examples
+
+## Create a Single Video Ad
+\`\`\`json
+{
+  "entityType": "ad",
+  "advertiserId": "1234567890",
+  "data": {
+    "adgroup_id": "1700123456789",
+    "creatives": [
+      {
+        "ad_name": "Summer Sale Video Ad",
+        "video_id": "v0200fg10000cekdqpbc77ue1tvq1ns0",
+        "call_to_action": "SHOP_NOW",
+        "landing_page_url": "https://example.com/summer-sale"
+      }
+    ]
+  }
+}
+\`\`\`
+
+## Create a Single Image Ad
+\`\`\`json
+{
+  "entityType": "ad",
+  "advertiserId": "1234567890",
+  "data": {
+    "adgroup_id": "1700123456789",
+    "creatives": [
+      {
+        "ad_name": "Product Banner Ad",
+        "image_ids": ["imt0000100000011abc123"],
+        "call_to_action": "LEARN_MORE",
+        "landing_page_url": "https://example.com/new-arrivals"
+      }
+    ]
+  }
+}
+\`\`\`
+`,
+    creative: `# TikTok Creative Examples
+
+## Create a Video Creative
+\`\`\`json
+{
+  "entityType": "creative",
+  "advertiserId": "1234567890",
+  "data": {
+    "display_name": "Summer Sale Video Creative",
+    "video_id": "v0200fg10000cekdqpbc77ue1tvq1ns0",
+    "ad_text": "Shop the Summer Sale — 50% off!",
+    "call_to_action": "SHOP_NOW",
+    "landing_page_url": "https://example.com/sale"
+  }
+}
+\`\`\`
+
+## Create an Image Creative
+\`\`\`json
+{
+  "entityType": "creative",
+  "advertiserId": "1234567890",
+  "data": {
+    "display_name": "Product Banner Creative",
+    "image_ids": ["imt0000100000011abc123"],
+    "ad_text": "New arrivals every week",
+    "call_to_action": "LEARN_MORE"
+  }
+}
+\`\`\`
+`,
+};
+function buildAllExamplesMarkdown() {
+    return getSupportedEntityTypes()
+        .map((t) => ENTITY_EXAMPLE_CONTENT[t])
+        .join("\n\n---\n\n");
+}
+export const entityExampleResources = getSupportedEntityTypes().map((entityType) => ({
+    uri: `entity-examples://tiktok/${entityType}`,
+    name: `TikTok ${entityType} Examples`,
+    description: `Example payloads for creating and updating TikTok ${entityType} entities`,
+    mimeType: "text/markdown",
+    getContent: () => ENTITY_EXAMPLE_CONTENT[entityType] ??
+        `# TikTok ${entityType} Examples\n\nNo examples available.\n`,
+}));
+export const entityExampleAllResource = {
+    uri: "entity-examples://tiktok/all",
+    name: "TikTok All Entity Examples",
+    description: "Combined example payloads for all TikTok Ads entity types",
+    mimeType: "text/markdown",
+    getContent: buildAllExamplesMarkdown,
+};
+//# sourceMappingURL=entity-examples.resource.js.map

package/dist/mcp-server/resources/definitions/entity-examples.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-examples.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-examples.resource.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,uBAAuB,GAExB,MAAM,qCAAqC,CAAC;AAE7C,MAAM,sBAAsB,GAAqC;IAC/D,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CX;IAEC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CV;IAEC,EAAE,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCL;IAEC,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BX;CACA,CAAC;AAEF,SAAS,wBAAwB;IAC/B,OAAO,uBAAuB,EAAE;SAC7B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;SACrC,IAAI,CAAC,aAAa,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAe,uBAAuB,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC/F,GAAG,EAAE,4BAA4B,UAAU,EAAE;IAC7C,IAAI,EAAE,UAAU,UAAU,WAAW;IACrC,WAAW,EAAE,qDAAqD,UAAU,WAAW;IACvF,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE,CACf,sBAAsB,CAAC,UAAU,CAAC;QAClC,YAAY,UAAU,uCAAuC;CAChE,CAAC,CAAC,CAAC;AAEJ,MAAM,CAAC,MAAM,wBAAwB,GAAa;IAChD,GAAG,EAAE,8BAA8B;IACnC,IAAI,EAAE,4BAA4B;IAClC,WAAW,EAAE,2DAA2D;IACxE,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,wBAAwB;CACrC,CAAC"}

package/dist/mcp-server/resources/definitions/entity-hierarchy.resource.d.ts

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

package/dist/mcp-server/resources/definitions/entity-hierarchy.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-hierarchy.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-hierarchy.resource.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA4I5C,eAAO,MAAM,uBAAuB,EAAE,QAUrC,CAAC"}

package/dist/mcp-server/resources/definitions/entity-hierarchy.resource.js

@@ -0,0 +1,147 @@
+let cachedContent;
+function formatEntityHierarchyMarkdown() {
+    return `# TikTok Ads Entity Hierarchy
+
+## Relationship Diagram
+
+\`\`\`
+Advertiser (advertiser_id: XXXXXXXXXX)
+  ├── Campaign (campaign_id)
+  │     └── Ad Group (adgroup_id)
+  │           └── Ad (ad_id)  ← references Creative
+  └── Creative (creative_id, reusable across ads)
+\`\`\`
+
+## Entity Types (4 total)
+
+| Entity Type | List Endpoint | Create Endpoint | ID Field |
+|-------------|---------------|-----------------|----------|
+| **campaign** | \`/open_api/v1.3/campaign/get/\` | \`/open_api/v1.3/campaign/create/\` | campaign_id |
+| **adGroup** | \`/open_api/v1.3/adgroup/get/\` | \`/open_api/v1.3/adgroup/create/\` | adgroup_id |
+| **ad** | \`/open_api/v1.3/ad/get/\` | \`/open_api/v1.3/ad/create/\` | ad_id |
+| **creative** | \`/open_api/v1.3/creative/adcreative/get/\` | \`/open_api/v1.3/creative/adcreative/create/\` | creative_id |
+
+## Key Relationships
+
+### Core Hierarchy: Advertiser → Campaign → Ad Group → Ad
+- A campaign has one or more ad groups.
+- An ad group has one or more ads.
+- An ad references creative assets (video_id or image_ids).
+
+### Reusable Entities
+- **Creatives** can be referenced by multiple ads within the same advertiser.
+
+## Creation Order
+
+Full campaign structure (top-down):
+
+1. **Advertiser** — pre-exists; discover with \`tiktok_list_advertisers\`
+2. **Creative(s)** — optional; can upload via Creative Library or reference video/image IDs
+3. **Campaign** — requires \`campaign_name\`, \`objective_type\`, \`budget_mode\`, \`budget\`
+4. **Ad Group(s)** — requires \`campaign_id\`, \`adgroup_name\`, plus objective-dependent delivery fields
+5. **Ad(s)** — requires \`adgroup_id\` and \`creatives\`
+
+## TikTok API Patterns
+
+### Read: GET with advertiser_id in query params
+\`\`\`
+GET /open_api/v1.3/campaign/get/?advertiser_id=123&page=1&page_size=10
+Authorization: Bearer <token>
+\`\`\`
+
+### Create: POST with advertiser_id in JSON body
+\`\`\`
+POST /open_api/v1.3/campaign/create/
+{ "advertiser_id": "123", "campaign_name": "...", ... }
+\`\`\`
+
+### Update: POST with entity ID + advertiser_id in JSON body
+\`\`\`
+POST /open_api/v1.3/campaign/update/
+{ "advertiser_id": "123", "campaign_id": "456", "budget": 200 }
+\`\`\`
+
+### Status Update: Separate endpoint, POST with IDs array
+\`\`\`
+POST /open_api/v1.3/campaign/status/update/
+{ "advertiser_id": "123", "campaign_ids": ["456", "789"], "operation_status": "DISABLE" }
+\`\`\`
+
+### Delete: Separate endpoint, POST with IDs array
+\`\`\`
+POST /open_api/v1.3/campaign/delete/
+{ "advertiser_id": "123", "campaign_ids": ["456"] }
+\`\`\`
+
+### Response Shape
+All TikTok API responses follow this structure:
+\`\`\`json
+{
+  "code": 0,
+  "message": "OK",
+  "data": { "list": [...], "page_info": { "page": 1, "page_size": 10, "total_number": 100, "total_page": 10 } }
+}
+\`\`\`
+- \`code: 0\` = success
+- \`code != 0\` = error (check \`message\` for details)
+
+## Pagination
+
+TikTok uses page-based pagination (NOT cursor-based):
+- \`page\` — page number (1-based)
+- \`page_size\` — items per page (max 1000 for some endpoints)
+- Response: \`page_info.total_page\` shows total pages
+
+## Available Tools Summary
+
+| Tool | Purpose | Batch? |
+|------|---------|--------|
+| \`tiktok_list_entities\` | List entities with filters | |
+| \`tiktok_get_entity\` | Get single entity | |
+| \`tiktok_create_entity\` | Create single entity | |
+| \`tiktok_update_entity\` | Update single entity | |
+| \`tiktok_delete_entity\` | Delete entities | ✓ |
+| \`tiktok_list_advertisers\` | List accessible advertisers | |
+| \`tiktok_get_report\` | Async report with polling | |
+| \`tiktok_get_report_breakdowns\` | Report with breakdown dimensions | |
+| \`tiktok_bulk_update_status\` | Batch status update | ✓ |
+| \`tiktok_bulk_create_entities\` | Batch entity creation | ✓ |
+| \`tiktok_bulk_update_entities\` | Batch entity updates | ✓ |
+| \`tiktok_adjust_bids\` | Batch bid adjustment | ✓ |
+| \`tiktok_search_targeting\` | Search targeting options | |
+| \`tiktok_get_targeting_options\` | Browse targeting categories | |
+| \`tiktok_duplicate_entity\` | Duplicate campaign/adGroup/ad | |
+| \`tiktok_get_audience_estimate\` | Audience size estimation | |
+| \`tiktok_get_ad_preview\` | Ad preview data | |
+| \`tiktok_validate_entity\` | Client-side payload validation | |
+
+## Budget Notes
+
+- Budget values are in the advertiser's account currency (no cents conversion)
+- \`budget_mode\`: BUDGET_MODE_DAY (daily) or BUDGET_MODE_TOTAL (lifetime)
+- Minimum budget varies by objective and market
+
+## Campaign Objectives
+
+| Objective | Use Case |
+|-----------|----------|
+| TRAFFIC | Drive website/app traffic |
+| APP_PROMOTION | Drive app installs or re-engagement |
+| WEB_CONVERSIONS | Optimize for website conversion events |
+| ENGAGEMENT | Community and engagement-focused delivery |
+| VIDEO_VIEWS | Maximize video plays |
+| LEAD_GENERATION | In-app lead forms |
+| PRODUCT_SALES | Dynamic product ads |
+`;
+}
+export const entityHierarchyResource = {
+    uri: "entity-hierarchy://tiktok/all",
+    name: "TikTok Entity Hierarchy",
+    description: "Parent-child relationships between TikTok Ads entities, API patterns, and creation ordering",
+    mimeType: "text/markdown",
+    getContent: () => {
+        cachedContent ??= formatEntityHierarchyMarkdown();
+        return cachedContent;
+    },
+};
+//# sourceMappingURL=entity-hierarchy.resource.js.map

package/dist/mcp-server/resources/definitions/entity-hierarchy.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-hierarchy.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-hierarchy.resource.ts"],"names":[],"mappings":"AAQA,IAAI,aAAiC,CAAC;AAEtC,SAAS,6BAA6B;IACpC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoIR,CAAC;AACF,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAa;IAC/C,GAAG,EAAE,+BAA+B;IACpC,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EACT,6FAA6F;IAC/F,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE;QACf,aAAa,KAAK,6BAA6B,EAAE,CAAC;QAClD,OAAO,aAAa,CAAC;IACvB,CAAC;CACF,CAAC"}

package/dist/mcp-server/resources/definitions/entity-schemas.resource.d.ts

@@ -0,0 +1,4 @@
+import type { Resource } from "../types.js";
+export declare const entitySchemaResources: Resource[];
+export declare const entitySchemaAllResource: Resource;
+//# sourceMappingURL=entity-schemas.resource.d.ts.map

package/dist/mcp-server/resources/definitions/entity-schemas.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-schemas.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-schemas.resource.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAqI5C,eAAO,MAAM,qBAAqB,EAAE,QAAQ,EAMzC,CAAC;AAEJ,eAAO,MAAM,uBAAuB,EAAE,QAMrC,CAAC"}

package/dist/mcp-server/resources/definitions/entity-schemas.resource.js

@@ -0,0 +1,135 @@
+import { getSupportedEntityTypes, } from "../../tools/utils/entity-mapping.js";
+const ENTITY_SCHEMA_CONTENT = {
+    campaign: `# TikTok Campaign Fields
+
+## Required Fields (create)
+| Field | Type | Description |
+|-------|------|-------------|
+| campaign_name | string | Campaign display name (max 512 chars) |
+| objective_type | string | Campaign objective such as TRAFFIC, APP_PROMOTION, WEB_CONVERSIONS, VIDEO_VIEWS, LEAD_GENERATION |
+
+## Optional Fields
+| Field | Type | Description |
+|-------|------|-------------|
+| operation_status | string | ENABLE or DISABLE |
+| budget_mode | string | BUDGET_MODE_DAY (daily) or BUDGET_MODE_TOTAL (lifetime) |
+| budget | number | Budget in account currency |
+| roas_bid | number | Target ROAS (for ROAS optimization) |
+| is_smart_performance_campaign | boolean | Enable smart performance campaign |
+| app_promotion_type | string | App-promotion mode for APP_PROMOTION campaigns |
+
+## Read-Only Fields
+campaign_id, create_time, modify_time, advertiser_id
+`,
+    adGroup: `# TikTok Ad Group Fields
+
+## Required Fields (create)
+| Field | Type | Description |
+|-------|------|-------------|
+| campaign_id | string | Parent campaign ID |
+| adgroup_name | string | Ad group display name |
+| placements | array | Placement enums such as PLACEMENT_TIKTOK |
+| schedule_type | string | Schedule mode when required by TikTok |
+| pacing | string | Pacing mode when required by TikTok |
+
+## Optional Fields
+| Field | Type | Description |
+|-------|------|-------------|
+| budget_mode | string | BUDGET_MODE_DAY or BUDGET_MODE_TOTAL |
+| budget | number | Budget in account currency |
+| schedule_start_time | string | Start time (YYYY-MM-DD HH:mm:ss) — required if schedule_type=SCHEDULE_START_END |
+| schedule_end_time | string | End time (YYYY-MM-DD HH:mm:ss) |
+| bid_price | number | Bid price in account currency |
+| optimization_goal | string | Optimization goal such as CLICK or APP_INSTALL |
+| billing_event | string | Billing event such as CPC, CPM, OCPM |
+| age | array | Age ranges: AGE_13_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45_54, AGE_55_100 |
+| gender | array | GENDER_UNLIMITED, GENDER_MALE, GENDER_FEMALE |
+| location_ids | array | Array of location IDs (country codes or region IDs) |
+| interest_category_ids | array | Interest category IDs |
+| languages | array | Language codes (e.g., ["en", "zh"]) |
+| placements | array | Specific placement IDs |
+| device_platforms | array | DESKTOP or MOBILE |
+| operating_systems | array | IOS or ANDROID |
+
+## Read-Only Fields
+ adgroup_id, campaign_id (inherited), create_time, modify_time
+`,
+    ad: `# TikTok Ad Fields
+
+## Required Fields (create)
+| Field | Type | Description |
+|-------|------|-------------|
+| adgroup_id | string | Parent ad group ID |
+| creatives | array | TikTok creatives array payload required by AdCreateBody |
+
+## Common Creative Fields
+| Field | Type | Description |
+|-------|------|-------------|
+| creatives[].ad_name | string | Ad display name |
+| creatives[].video_id | string | Video ID from TikTok Creative Library |
+| creatives[].image_ids | array | Array of image IDs (for image-based ads) |
+
+## Optional Creative Fields
+| Field | Type | Description |
+|-------|------|-------------|
+| ad_text | string | Ad copy text (max 100 chars) |
+| app_name | string | App name shown in the ad |
+| landing_page_url | string | Destination URL |
+| display_name | string | Display brand name |
+| profile_image_url | string | Brand profile image URL |
+| call_to_action | string | CTA text: LEARN_MORE, SHOP_NOW, DOWNLOAD, SIGN_UP, etc. |
+| patch_update | boolean | Optional partial-update behavior on update |
+
+## Read-Only Fields
+ad_id, adgroup_id (inherited), create_time, modify_time
+`,
+    creative: `# TikTok Creative Fields
+
+## Required Fields (create)
+| Field | Type | Description |
+|-------|------|-------------|
+| display_name | string | Creative display name |
+
+## Creative Asset Fields (provide at least one)
+| Field | Type | Description |
+|-------|------|-------------|
+| video_id | string | Video asset ID from Creative Library |
+| image_ids | array | Array of image asset IDs |
+
+## Optional Fields
+| Field | Type | Description |
+|-------|------|-------------|
+| ad_text | string | Ad copy text |
+| call_to_action | string | CTA: LEARN_MORE, SHOP_NOW, DOWNLOAD, etc. |
+| landing_page_url | string | Destination URL |
+| profile_image_url | string | Brand profile image |
+| app_name | string | App name for app install ads |
+
+## Read-Only Fields
+creative_id, advertiser_id, created_time
+`,
+};
+function buildEntitySchemaMarkdown(entityType) {
+    return (ENTITY_SCHEMA_CONTENT[entityType] ??
+        `# TikTok ${entityType}\n\nNo schema information available.\n`);
+}
+function buildAllSchemasMarkdown() {
+    return getSupportedEntityTypes()
+        .map((t) => ENTITY_SCHEMA_CONTENT[t])
+        .join("\n\n---\n\n");
+}
+export const entitySchemaResources = getSupportedEntityTypes().map((entityType) => ({
+    uri: `entity-schema://tiktok/${entityType}`,
+    name: `TikTok ${entityType} Schema`,
+    description: `Field reference for TikTok ${entityType} entity including required fields, optional fields, and read-only fields`,
+    mimeType: "text/markdown",
+    getContent: () => buildEntitySchemaMarkdown(entityType),
+}));
+export const entitySchemaAllResource = {
+    uri: "entity-schema://tiktok/all",
+    name: "TikTok All Entity Schemas",
+    description: "Combined field reference for all TikTok Ads entity types",
+    mimeType: "text/markdown",
+    getContent: buildAllSchemasMarkdown,
+};
+//# sourceMappingURL=entity-schemas.resource.js.map

package/dist/mcp-server/resources/definitions/entity-schemas.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-schemas.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity-schemas.resource.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,uBAAuB,GAExB,MAAM,qCAAqC,CAAC;AAE7C,MAAM,qBAAqB,GAAqC;IAC9D,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;CAoBX;IAEC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCV;IAEC,EAAE,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BL;IAEC,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;CAwBX;CACA,CAAC;AAEF,SAAS,yBAAyB,CAAC,UAA4B;IAC7D,OAAO,CACL,qBAAqB,CAAC,UAAU,CAAC;QACjC,YAAY,UAAU,wCAAwC,CAC/D,CAAC;AACJ,CAAC;AAED,SAAS,uBAAuB;IAC9B,OAAO,uBAAuB,EAAE;SAC7B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;SACpC,IAAI,CAAC,aAAa,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAe,uBAAuB,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC9F,GAAG,EAAE,0BAA0B,UAAU,EAAE;IAC3C,IAAI,EAAE,UAAU,UAAU,SAAS;IACnC,WAAW,EAAE,8BAA8B,UAAU,0EAA0E;IAC/H,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE,CAAC,yBAAyB,CAAC,UAAU,CAAC;CACxD,CAAC,CAAC,CAAC;AAEJ,MAAM,CAAC,MAAM,uBAAuB,GAAa;IAC/C,GAAG,EAAE,4BAA4B;IACjC,IAAI,EAAE,2BAA2B;IACjC,WAAW,EAAE,0DAA0D;IACvE,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,uBAAuB;CACpC,CAAC"}

package/dist/mcp-server/resources/definitions/index.d.ts

@@ -0,0 +1,8 @@
+export { entityHierarchyResource } from "./entity-hierarchy.resource.js";
+export { entitySchemaResources, entitySchemaAllResource } from "./entity-schemas.resource.js";
+export { entityExampleResources, entityExampleAllResource } from "./entity-examples.resource.js";
+export { reportingReferenceResource } from "./reporting-reference.resource.js";
+export { targetingReferenceResource } from "./targeting-reference.resource.js";
+import type { Resource } from "../types.js";
+export declare const allResources: Resource[];
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/resources/definitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC9F,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACjG,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAS/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA6D5C,eAAO,MAAM,YAAY,EAAE,QAAQ,EAUlC,CAAC"}