@cesteral/tiktok-mcp 1.0.0

package/dist/mcp-server/resources/definitions/index.js

@@ -0,0 +1,79 @@
+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 { entityHierarchyResource } from "./entity-hierarchy.resource.js";
+import { entitySchemaResources, entitySchemaAllResource } from "./entity-schemas.resource.js";
+import { entityExampleResources, entityExampleAllResource } from "./entity-examples.resource.js";
+import { reportingReferenceResource } from "./reporting-reference.resource.js";
+import { targetingReferenceResource } from "./targeting-reference.resource.js";
+import { allTools } from "../../tools/definitions/index.js";
+import { createToolExamplesResource, createServerCapabilitiesResource } from "@cesteral/shared";
+const toolExamplesResource = createToolExamplesResource(allTools, "tiktok-mcp");
+const serverCapabilitiesResource = createServerCapabilitiesResource({
+    serverName: "tiktok-mcp",
+    allTools,
+    toolGroups: {
+        account: ["tiktok_list_advertisers"],
+        crud: [
+            "tiktok_list_entities",
+            "tiktok_get_entity",
+            "tiktok_create_entity",
+            "tiktok_update_entity",
+            "tiktok_delete_entity",
+        ],
+        reporting: [
+            "tiktok_get_report",
+            "tiktok_get_report_breakdowns",
+            "tiktok_submit_report",
+            "tiktok_check_report_status",
+            "tiktok_download_report",
+        ],
+        bulk: [
+            "tiktok_bulk_update_status",
+            "tiktok_bulk_create_entities",
+            "tiktok_bulk_update_entities",
+            "tiktok_adjust_bids",
+        ],
+        targeting: ["tiktok_search_targeting", "tiktok_get_targeting_options"],
+        media: ["tiktok_upload_image", "tiktok_upload_video"],
+        specialized: [
+            "tiktok_duplicate_entity",
+            "tiktok_get_audience_estimate",
+            "tiktok_get_ad_preview",
+        ],
+        validation: ["tiktok_validate_entity"],
+        discovery: ["tiktok_search_tools"],
+    },
+    commonWorkflows: ["campaign_setup", "async_reporting", "audience_targeting"],
+    discoveryFlow: [
+        "Read server-capabilities://tiktok-mcp/overview to choose a capability group.",
+        "Call tiktok_list_advertisers to discover accessible advertiser IDs.",
+        "Read entity-hierarchy://all and entity-schema://{entityType} before entity writes.",
+        "Read reporting-reference://all before report tools.",
+        "Read targeting-reference://all before targeting search or audience estimation.",
+        "Use tool-examples://tiktok-mcp/all only when concrete payload examples are needed.",
+    ],
+    relatedResources: [
+        "entity-hierarchy://all",
+        "entity-schema://all",
+        "entity-examples://all",
+        "reporting-reference://all",
+        "targeting-reference://all",
+        "tool-examples://tiktok-mcp/all",
+    ],
+    startHere: "tiktok_list_advertisers",
+});
+export const allResources = [
+    entityHierarchyResource,
+    entitySchemaAllResource,
+    ...entitySchemaResources,
+    entityExampleAllResource,
+    ...entityExampleResources,
+    reportingReferenceResource,
+    targetingReferenceResource,
+    ...(toolExamplesResource ? [toolExamplesResource] : []),
+    serverCapabilitiesResource,
+];
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/resources/definitions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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;AAE/E,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;AAC/E,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAC5D,OAAO,EAAE,0BAA0B,EAAE,gCAAgC,EAAE,MAAM,kBAAkB,CAAC;AAGhG,MAAM,oBAAoB,GAAG,0BAA0B,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;AAChF,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;IAClE,UAAU,EAAE,YAAY;IACxB,QAAQ;IACR,UAAU,EAAE;QACV,OAAO,EAAE,CAAC,yBAAyB,CAAC;QACpC,IAAI,EAAE;YACJ,sBAAsB;YACtB,mBAAmB;YACnB,sBAAsB;YACtB,sBAAsB;YACtB,sBAAsB;SACvB;QACD,SAAS,EAAE;YACT,mBAAmB;YACnB,8BAA8B;YAC9B,sBAAsB;YACtB,4BAA4B;YAC5B,wBAAwB;SACzB;QACD,IAAI,EAAE;YACJ,2BAA2B;YAC3B,6BAA6B;YAC7B,6BAA6B;YAC7B,oBAAoB;SACrB;QACD,SAAS,EAAE,CAAC,yBAAyB,EAAE,8BAA8B,CAAC;QACtE,KAAK,EAAE,CAAC,qBAAqB,EAAE,qBAAqB,CAAC;QACrD,WAAW,EAAE;YACX,yBAAyB;YACzB,8BAA8B;YAC9B,uBAAuB;SACxB;QACD,UAAU,EAAE,CAAC,wBAAwB,CAAC;QACtC,SAAS,EAAE,CAAC,qBAAqB,CAAC;KACnC;IACD,eAAe,EAAE,CAAC,gBAAgB,EAAE,iBAAiB,EAAE,oBAAoB,CAAC;IAC5E,aAAa,EAAE;QACb,8EAA8E;QAC9E,qEAAqE;QACrE,oFAAoF;QACpF,qDAAqD;QACrD,gFAAgF;QAChF,oFAAoF;KACrF;IACD,gBAAgB,EAAE;QAChB,wBAAwB;QACxB,qBAAqB;QACrB,uBAAuB;QACvB,2BAA2B;QAC3B,2BAA2B;QAC3B,gCAAgC;KACjC;IACD,SAAS,EAAE,yBAAyB;CACrC,CAAC,CAAC;AAKH,MAAM,CAAC,MAAM,YAAY,GAAe;IACtC,uBAAuB;IACvB,uBAAuB;IACvB,GAAG,qBAAqB;IACxB,wBAAwB;IACxB,GAAG,sBAAsB;IACzB,0BAA0B;IAC1B,0BAA0B;IAC1B,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,oBAA2C,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,0BAAiD;CAClD,CAAC"}

package/dist/mcp-server/resources/definitions/reporting-reference.resource.d.ts

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

package/dist/mcp-server/resources/definitions/reporting-reference.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporting-reference.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/reporting-reference.resource.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA8J5C,eAAO,MAAM,0BAA0B,EAAE,QAUxC,CAAC"}

package/dist/mcp-server/resources/definitions/reporting-reference.resource.js

@@ -0,0 +1,165 @@
+let cachedContent;
+function formatReportingReferenceMarkdown() {
+    return `# TikTok Ads Reporting Reference
+
+## Report Types
+
+| Report Type | Description |
+|-------------|-------------|
+| BASIC | Standard delivery and performance metrics |
+| AUDIENCE | Audience breakdown metrics (requires audience dimensions) |
+| PLAYABLE_MATERIAL | Playable ad performance metrics |
+
+## Async Reporting Flow
+
+1. **Submit**: POST \`/open_api/v1.3/report/task/create/\` → get \`task_id\`
+2. **Poll**: GET \`/open_api/v1.3/report/task/check/?task_id={id}\` → check \`status\`
+3. **Download**: GET the \`download_url\` when status = "DONE"
+
+Status values: PENDING → RUNNING → DONE | FAILED
+
+Use \`tiktok_get_report\` or \`tiktok_get_report_breakdowns\` — these tools handle the full flow automatically.
+
+## Common Dimensions
+
+### Time Dimensions
+| Dimension | Description |
+|-----------|-------------|
+| stat_time_day | Daily breakdown (YYYY-MM-DD) |
+| stat_time_hour | Hourly breakdown |
+
+### Entity Dimensions
+| Dimension | Description |
+|-----------|-------------|
+| advertiser_id | Advertiser ID |
+| campaign_id | Campaign ID |
+| adgroup_id | Ad group ID |
+| ad_id | Ad ID |
+
+### Audience Dimensions (AUDIENCE report type)
+| Dimension | Description |
+|-----------|-------------|
+| gender | User gender breakdown |
+| age | User age group breakdown |
+| country_code | Country (ISO 2-letter code) |
+| province_id | Province/region ID |
+| platform | Operating system platform |
+| device_brand_id | Device brand |
+| interest_category | Interest category |
+| placement | Ad placement |
+| language | User language |
+
+## Common Metrics
+
+### Delivery Metrics
+| Metric | Description |
+|--------|-------------|
+| impressions | Total impressions |
+| reach | Unique users reached |
+| frequency | Average impressions per user |
+| clicks | Total clicks |
+| ctr | Click-through rate (%) |
+| cpm | Cost per mille (per 1000 impressions) |
+| cpc | Cost per click |
+| spend | Total amount spent |
+
+### Video Metrics
+| Metric | Description |
+|--------|-------------|
+| video_play_actions | Total video plays |
+| video_watched_2s | 2-second video views |
+| video_watched_6s | 6-second video views |
+| video_views_p25 | 25% video completion |
+| video_views_p50 | 50% video completion |
+| video_views_p75 | 75% video completion |
+| video_views_p100 | 100% completion (full views) |
+| average_video_play | Average play duration (seconds) |
+
+### Conversion Metrics
+| Metric | Description |
+|--------|-------------|
+| conversions | Total conversion events |
+| conversion_rate | Conversions / clicks (%) |
+| cost_per_conversion | Spend / conversions |
+| real_time_conversions | Real-time tracked conversions |
+| total_purchase_value | Total purchase value |
+| total_sales | Total sales count |
+| cost_per_1000_reached | CPM by unique reach |
+
+### Engagement Metrics
+| Metric | Description |
+|--------|-------------|
+| profile_visits | Profile page visits |
+| follows | New followers gained |
+| likes | Likes on ads |
+| comments | Comments on ads |
+| shares | Shares of ads |
+| engaged_view | Engaged views (6s+ or interaction) |
+
+## Report Type Details
+
+| Report Type | Required Dimensions | Valid Metrics | Notes |
+|-------------|-------------------|---------------|-------|
+| BASIC | Any entity + time dims | All delivery, video, conversion, engagement | Default; most flexible |
+| AUDIENCE | Must include audience dim (age, gender, country_code, etc.) | Delivery + basic engagement | Cannot combine with video completion metrics |
+| PLAYABLE_MATERIAL | Must include ad_id | Playable-specific + delivery | Only for playable ad formats |
+
+## Dimension/Metric Compatibility
+
+- **Time dimensions** (stat_time_day, stat_time_hour) are compatible with all metric types
+- **Entity dimensions** (campaign_id, adgroup_id, ad_id) are compatible with all metric types
+- **Audience dimensions** (gender, age, country_code, etc.) require report_type = "AUDIENCE"
+- **Playable dimensions** require report_type = "PLAYABLE_MATERIAL"
+- Mixing audience dimensions with non-audience report type returns an error
+- Maximum 3 dimensions per report (TikTok API limit)
+
+## Example Report Configurations
+
+### Campaign Daily Delivery Report
+\`\`\`json
+{
+  "advertiserId": "1234567890",
+  "reportType": "BASIC",
+  "dimensions": ["campaign_id", "stat_time_day"],
+  "metrics": ["impressions", "clicks", "spend", "ctr", "cpc"],
+  "startDate": "2026-03-01",
+  "endDate": "2026-03-07"
+}
+\`\`\`
+
+### Ad Performance with Video Metrics
+\`\`\`json
+{
+  "advertiserId": "1234567890",
+  "reportType": "BASIC",
+  "dimensions": ["ad_id"],
+  "metrics": ["impressions", "spend", "video_play_actions", "video_views_p100", "average_video_play"],
+  "startDate": "2026-03-01",
+  "endDate": "2026-03-07"
+}
+\`\`\`
+
+### Country Breakdown Report
+\`\`\`json
+{
+  "advertiserId": "1234567890",
+  "dimensions": ["campaign_id", "stat_time_day"],
+  "breakdowns": ["country_code"],
+  "metrics": ["impressions", "clicks", "spend", "conversions"],
+  "startDate": "2026-03-01",
+  "endDate": "2026-03-07"
+}
+\`\`\`
+`;
+}
+export const reportingReferenceResource = {
+    uri: "reporting-reference://tiktok",
+    name: "TikTok Reporting Reference",
+    description: "Available dimensions, metrics, report types, and example configurations for TikTok Ads reporting",
+    mimeType: "text/markdown",
+    getContent: () => {
+        cachedContent ??= formatReportingReferenceMarkdown();
+        return cachedContent;
+    },
+};
+//# sourceMappingURL=reporting-reference.resource.js.map

package/dist/mcp-server/resources/definitions/reporting-reference.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporting-reference.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/reporting-reference.resource.ts"],"names":[],"mappings":"AAQA,IAAI,aAAiC,CAAC;AAEtC,SAAS,gCAAgC;IACvC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsJR,CAAC;AACF,CAAC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAa;IAClD,GAAG,EAAE,8BAA8B;IACnC,IAAI,EAAE,4BAA4B;IAClC,WAAW,EACT,kGAAkG;IACpG,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE;QACf,aAAa,KAAK,gCAAgC,EAAE,CAAC;QACrD,OAAO,aAAa,CAAC;IACvB,CAAC;CACF,CAAC"}

package/dist/mcp-server/resources/definitions/targeting-reference.resource.d.ts

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

package/dist/mcp-server/resources/definitions/targeting-reference.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targeting-reference.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/targeting-reference.resource.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA+H5C,eAAO,MAAM,0BAA0B,EAAE,QAUxC,CAAC"}

package/dist/mcp-server/resources/definitions/targeting-reference.resource.js

@@ -0,0 +1,134 @@
+let cachedContent;
+function formatTargetingReferenceMarkdown() {
+    return `# TikTok Ads Targeting Reference
+
+## Targeting Structure
+
+TikTok ad groups accept targeting via the \`targeting\` object in create/update payloads.
+Use \`tiktok_search_targeting\` to find valid IDs and \`tiktok_get_targeting_options\` to browse available options.
+
+## Objective Types
+
+| Objective | Description |
+|-----------|-------------|
+| REACH | Maximize ad impressions |
+| TRAFFIC | Drive website visits |
+| VIDEO_VIEWS | Maximize video views |
+| LEAD_GENERATION | Collect leads via forms |
+| COMMUNITY_INTERACTION | Drive followers and profile visits |
+| APP_PROMOTION | Drive app installs or re-engagement |
+| WEBSITE_CONVERSIONS | Drive website conversion events |
+| PRODUCT_SALES | Drive product sales (catalog) |
+
+## Age Groups
+
+| Value | Range |
+|-------|-------|
+| AGE_13_17 | 13-17 years |
+| AGE_18_24 | 18-24 years |
+| AGE_25_34 | 25-34 years |
+| AGE_35_44 | 35-44 years |
+| AGE_45_54 | 45-54 years |
+| AGE_55_100 | 55+ years |
+
+## Gender Values
+
+| Value | Description |
+|-------|-------------|
+| GENDER_UNLIMITED | All genders (default) |
+| GENDER_MALE | Male only |
+| GENDER_FEMALE | Female only |
+
+## Placement Types
+
+| Placement | Description |
+|-----------|-------------|
+| PLACEMENT_TIKTOK | TikTok feed |
+| PLACEMENT_PANGLE | Pangle (audience network) |
+| PLACEMENT_GLOBAL_APP_BUNDLE | Global App Bundle |
+
+## Targeting Types for Search
+
+Use these values with \`tiktok_search_targeting\`:
+
+| Type | Description | Supports Keyword Search |
+|------|-------------|------------------------|
+| INTEREST_CATEGORY | Interest categories | No (browse only) |
+| INTEREST_KEYWORD | Interest keywords | Yes |
+| ACTION_CATEGORY | Behavioral categories | No (browse only) |
+| LOCATION | Geographic locations | Yes |
+| LANGUAGE | Languages | Yes |
+| DEVICE_MODEL | Device models | Yes |
+| CARRIER | Mobile carriers | Yes |
+| OS_VERSION | Operating system versions | No |
+| ISP | Internet service providers | Yes |
+| ZIPCODE | ZIP/postal codes | Yes |
+| CONTEXTUAL_TAG | Contextual targeting tags | Yes |
+
+## Targeting Spec Example
+
+\`\`\`json
+{
+  "targeting": {
+    "age_groups": ["AGE_18_24", "AGE_25_34"],
+    "gender": "GENDER_UNLIMITED",
+    "location_ids": ["6252001"],
+    "languages": ["en"],
+    "interest_category_ids": ["100001"],
+    "interest_keyword_ids": ["200001"],
+    "operating_systems": ["ANDROID", "IOS"],
+    "placements": ["PLACEMENT_TIKTOK"],
+    "placements": ["PLACEMENT_TIKTOK"]
+  }
+}
+\`\`\`
+
+## Optimize Goals
+
+| Goal | Description |
+|------|-------------|
+| CLICK | Optimize for clicks |
+| CONVERT | Optimize for conversions |
+| INSTALL | Optimize for app installs |
+| SHOW | Optimize for impressions |
+| REACH | Optimize for unique reach |
+| VIDEO_VIEW | Optimize for video views |
+| LEAD_GENERATION | Optimize for lead form submissions |
+| VALUE | Optimize for value (ROAS) |
+
+## Bid Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| BID_TYPE_NO_BID | Lowest cost (automated) |
+| BID_TYPE_CUSTOM | Cost cap (manual bid) |
+| BID_TYPE_MAX | Maximum delivery |
+
+## Budget Modes
+
+| Mode | Description |
+|------|-------------|
+| BUDGET_MODE_DAY | Daily budget |
+| BUDGET_MODE_TOTAL | Lifetime budget |
+| BUDGET_MODE_DYNAMIC | Dynamic daily budget |
+
+## Key Notes
+
+- \`targeting\` on ad group **replaces entirely** -- always include all targeting fields
+- Location IDs are TikTok-specific; use \`tiktok_search_targeting\` with type \`LOCATION\` to find them
+- Interest category/keyword IDs must be valid TikTok IDs from the search/browse APIs
+- Minimum audience size varies by market; use \`tiktok_get_audience_estimate\` to check
+- Some targeting options are only available for specific objective types
+`;
+}
+export const targetingReferenceResource = {
+    uri: "targeting-reference://tiktok",
+    name: "TikTok Targeting Reference",
+    description: "Targeting types, age groups, genders, placements, objectives, bid strategies, and patterns for TikTok Ads",
+    mimeType: "text/markdown",
+    getContent: () => {
+        cachedContent ??= formatTargetingReferenceMarkdown();
+        return cachedContent;
+    },
+};
+//# sourceMappingURL=targeting-reference.resource.js.map

package/dist/mcp-server/resources/definitions/targeting-reference.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targeting-reference.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/targeting-reference.resource.ts"],"names":[],"mappings":"AAQA,IAAI,aAAiC,CAAC;AAEtC,SAAS,gCAAgC;IACvC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuHR,CAAC;AACF,CAAC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAa;IAClD,GAAG,EAAE,8BAA8B;IACnC,IAAI,EAAE,4BAA4B;IAClC,WAAW,EACT,2GAA2G;IAC7G,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,GAAG,EAAE;QACf,aAAa,KAAK,gCAAgC,EAAE,CAAC;QACrD,OAAO,aAAa,CAAC;IACvB,CAAC;CACF,CAAC"}

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

@@ -0,0 +1,3 @@
+export type { Resource } from "./types.js";
+export { allResources } from "./definitions/index.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/resources/index.ts"],"names":[],"mappings":"AAOA,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}

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

@@ -0,0 +1,2 @@
+export { allResources } from "./definitions/index.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp-server/resources/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/mcp-server/resources/types.d.ts

@@ -0,0 +1,8 @@
+export interface Resource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    getContent: () => string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp-server/resources/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/resources/types.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,QAAQ;IAEvB,GAAG,EAAE,MAAM,CAAC;IAEZ,IAAI,EAAE,MAAM,CAAC;IAEb,WAAW,EAAE,MAAM,CAAC;IAEpB,QAAQ,EAAE,MAAM,CAAC;IAEjB,UAAU,EAAE,MAAM,MAAM,CAAC;CAC1B"}

package/dist/mcp-server/resources/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp-server/resources/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/mcp-server/resources/types.ts"],"names":[],"mappings":""}

package/dist/mcp-server/server.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Logger } from "pino";
+export declare function createMcpServer(logger: Logger, sessionId?: string, gcsBucket?: string): Promise<McpServer>;
+export declare function runStdioServer(server: McpServer, logger: Logger): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp-server/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp-server/server.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AAmBtF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAoCnC,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,SAAS,CAAC,CAiIpB;AAKD,wBAAsB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrF"}

package/dist/mcp-server/server.js

@@ -0,0 +1,134 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { allTools } from "./tools/index.js";
+import { allResources } from "./resources/index.js";
+import { promptRegistry } from "./prompts/index.js";
+import { createOperationContext } from "@cesteral/shared";
+import { reportCsvStore, sessionServiceStore } from "../services/session-services.js";
+import { extractZodShape, registerReportCsvResource, registerToolsFromDefinitions, registerPromptsFromDefinitions, registerStaticResourcesFromDefinitions, InteractionLogger, isConformanceFixturesEnabled, } from "@cesteral/shared";
+import packageJson from "../../package.json" with { type: "json" };
+const TIKTOK_PACKAGE_NAME = "tiktok-mcp";
+const TIKTOK_PLATFORM = "tiktok";
+const tiktokWorkflowIdByToolName = {
+    tiktok_list_entities: "mcp.execute.tiktok_entity_read",
+    tiktok_get_entity: "mcp.execute.tiktok_entity_read",
+    tiktok_list_advertisers: "mcp.execute.tiktok_entity_read",
+    tiktok_create_entity: "mcp.execute.tiktok_entity_update",
+    tiktok_update_entity: "mcp.execute.tiktok_entity_update",
+    tiktok_delete_entity: "mcp.execute.tiktok_entity_update",
+    tiktok_get_report: "mcp.execute.tiktok_reporting",
+    tiktok_get_report_breakdowns: "mcp.execute.tiktok_reporting",
+    tiktok_bulk_update_status: "mcp.execute.tiktok_bulk_operations",
+    tiktok_bulk_create_entities: "mcp.execute.tiktok_bulk_operations",
+    tiktok_bulk_update_entities: "mcp.execute.tiktok_bulk_operations",
+    tiktok_adjust_bids: "mcp.execute.tiktok_bulk_operations",
+    tiktok_search_targeting: "mcp.execute.tiktok_entity_read",
+    tiktok_get_targeting_options: "mcp.execute.tiktok_entity_read",
+    tiktok_duplicate_entity: "mcp.execute.tiktok_entity_update",
+    tiktok_get_audience_estimate: "mcp.execute.tiktok_entity_read",
+    tiktok_get_ad_preview: "mcp.execute.tiktok_entity_read",
+    tiktok_validate_entity: "mcp.execute.tiktok_entity_read",
+};
+export async function createMcpServer(logger, sessionId, gcsBucket) {
+    const server = new McpServer({
+        name: "tiktok-mcp",
+        version: packageJson.version,
+        description: "TikTok Ads campaign management and reporting via TikTok Marketing API v1.3. Supports 4 entity types (campaign, adGroup, ad, creative), async reporting with breakdowns, bulk operations, targeting search, audience estimation, and ad previews.",
+    }, {
+        capabilities: {
+            logging: {},
+        },
+        instructions: "TikTok Ads campaign management and reporting server. Supports 4 entity types (campaign, adGroup, ad, creative), async reporting, targeting, and bulk operations via TikTok Marketing API v1.3. " +
+            "Use tiktok_list_advertisers to discover accounts, tiktok_list_entities to browse entities. " +
+            "See MCP Resources for entity schemas and MCP Prompts for workflow guidance.",
+    });
+    const interactionLogger = new InteractionLogger({
+        serverName: TIKTOK_PACKAGE_NAME,
+        logger,
+        gcsBucket,
+    });
+    registerToolsFromDefinitions({
+        server,
+        tools: allTools,
+        logger,
+        sessionId,
+        transformSchema: (schema) => extractZodShape(schema),
+        createRequestContext: (params) => createOperationContext({
+            operation: params.operation,
+            additionalContext: params.additionalContext,
+        }),
+        defaultTextFormat: "compact",
+        packageName: TIKTOK_PACKAGE_NAME,
+        platform: TIKTOK_PLATFORM,
+        workflowIdByToolName: tiktokWorkflowIdByToolName,
+        interactionLogger,
+        authContextResolver: sessionId
+            ? () => sessionServiceStore.getAuthContext(sessionId)
+            : undefined,
+    });
+    registerStaticResourcesFromDefinitions({
+        server,
+        resources: allResources,
+        logger,
+    });
+    registerReportCsvResource({
+        server,
+        ResourceTemplate,
+        store: reportCsvStore,
+        platform: "TikTok",
+        downloadToolName: "tiktok_download_report",
+        logger,
+    });
+    if (isConformanceFixturesEnabled()) {
+        const { conformanceResources, conformanceResourceTemplate, conformancePrompts } = await import("@cesteral/shared");
+        const { ResourceTemplate: McpResourceTemplate } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+        registerStaticResourcesFromDefinitions({
+            server,
+            resources: conformanceResources,
+            logger,
+        });
+        const template = new McpResourceTemplate(conformanceResourceTemplate.uriTemplate, {
+            list: undefined,
+        });
+        server.registerResource("conformance_template", template, {
+            description: conformanceResourceTemplate.description,
+            mimeType: conformanceResourceTemplate.mimeType,
+        }, async (uri, variables) => {
+            const id = variables.id || "unknown";
+            const content = conformanceResourceTemplate.getContent(id);
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: conformanceResourceTemplate.mimeType,
+                        text: content,
+                    },
+                ],
+            };
+        });
+        registerPromptsFromDefinitions({
+            server: server,
+            prompts: conformancePrompts,
+            logger,
+        });
+    }
+    const allPrompts = Array.from(promptRegistry.values()).map((def) => ({
+        name: def.prompt.name,
+        description: def.prompt.description ?? "",
+        arguments: def.prompt.arguments,
+        generateMessage: def.generateMessage,
+    }));
+    registerPromptsFromDefinitions({
+        server: server,
+        prompts: allPrompts,
+        logger,
+    });
+    return server;
+}
+export async function runStdioServer(server, logger) {
+    logger.info("Starting MCP server with stdio transport");
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("MCP server connected via stdio");
+}
+//# sourceMappingURL=server.js.map

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

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