@contenthero/mcp 0.4.0 → 0.4.2

package/dist/server.js

@@ -37,8 +37,8 @@ import { z } from 'zod';
 import { GenerationTimeoutError, pendingOutputId, } from '@contenthero/sdk';
 import { getClient as defaultGetClient } from './client.js';
 import { resolveModelEnums, BOARD_TYPES, BOARD_TYPE_GUIDANCE, IMAGE_MODEL_GUIDANCE, VIDEO_MODEL_GUIDANCE, AUDIO_MODEL_GUIDANCE, EDIT_AUDIO_MODEL_GUIDANCE, UPSCALE_MODEL_GUIDANCE, LIP_SYNC_MODEL_GUIDANCE, } from './models.js';
-import { audioResult, avatarListResult, avatarResult, balanceResult, brandKitListResult, brandKitResult, brandKnowledgeListResult, brandKnowledgeDetailResult, brandKnowledgeSearchResult, brandKnowledgeItemResult, completedResult, connectedAccountListResult, connectedAccountResult, costResult, accountDetailResult, inspirationContentResult, mediaListResult, mediaSearchResult, folderListResult, folderContentsResult, mediaBatchResult, mediaUploadResult, uploadedMediaResult, tagListResult, tagResult, tagDeletedResult, modelListResult, modelResult, platformListResult, platformResult, elementListResult, elementResult, elementDeletedResult, errorResult, generationBatchResult, outlierListResult, enhanceClipsResult, pendingResult, stageListResult, spaceDeletedResult, spaceListResult, spaceResult, cardListResult, cardResult, postSummaryResult, publishResult, statusActionResult, editorOpsResult, text, projectDetailResult, liveContextResult, projectListResult, projectCreatedResult, projectDeletedResult, layerTypesResult, timelineTypesResult, editorTranscriptResult, exportJobResult, exportFormatsResult, trackedAccountListResult, transcriptResult, voiceListResult, voiceResult, } from './format.js';
-/** Platforms a post or destination may target. */
+import { audioResult, avatarListResult, avatarResult, balanceResult, brandKitListResult, brandKitResult, brandKnowledgeListResult, brandKnowledgeDetailResult, brandKnowledgeSearchResult, brandKnowledgeItemResult, completedResult, connectedAccountListResult, connectedAccountResult, costResult, accountDetailResult, inspirationContentResult, mediaListResult, mediaSearchResult, folderListResult, folderContentsResult, mediaBatchResult, mediaUploadResult, importedMediaResult, uploadedMediaResult, tagListResult, tagResult, tagDeletedResult, modelListResult, modelResult, platformListResult, platformResult, elementListResult, elementResult, elementDeletedResult, errorResult, generationBatchResult, outlierListResult, enhanceClipsResult, pendingResult, stageListResult, spaceDeletedResult, spaceListResult, spaceResult, cardListResult, cardResult, postSummaryResult, publishResult, statusActionResult, editorOpsResult, text, projectDetailResult, liveContextResult, projectListResult, projectCreatedResult, projectDeletedResult, layerTypesResult, timelineTypesResult, editorTranscriptResult, exportJobResult, exportFormatsResult, trackedAccountListResult, transcriptResult, voiceListResult, voiceResult, } from './format.js';
+/** Platforms a card or one of its posts may target. */
 const POST_PLATFORMS = [
     'youtube',
     'instagram',
@@ -247,11 +247,11 @@ export function registerTools(server, opts) {
             handleOrUrl: z.string().describe('A profile url, or a handle when platform is given.'),
         }),
     ]);
-    const postDestinationSchema = z.object({
-        platform: z.enum(POST_PLATFORMS).describe('The platform. This is the KEY: one destination per platform.'),
+    const cardPostSchema = z.object({
+        platform: z.enum(POST_PLATFORMS).describe('The platform. This is the KEY: one post per platform.'),
         format: z.string().optional(),
         connectedAccountId: z.string().nullable().optional(),
-        scheduledAt: z.string().nullable().optional().describe("Per-destination override of the post's schedule."),
+        scheduledAt: z.string().nullable().optional().describe("Per-post override of the card's schedule."),
         platformSpecificData: z.record(z.string(), z.unknown()).optional().describe('The publish payload for this platform.'),
         status: z.string().optional(),
     });
@@ -1357,7 +1357,7 @@ export function registerTools(server, opts) {
     }, async (args, extra) => {
         try {
             const client = await getClient(extra);
-            return uploadedMediaResult(await client.importMedia({
+            return importedMediaResult(await client.importMedia({
                 url: args.url,
                 contentType: args.contentType,
                 fileName: args.fileName,
@@ -1423,7 +1423,7 @@ export function registerTools(server, opts) {
     server.registerTool('get_platform', {
         title: 'Get Platform',
         annotations: READ,
-        description: "Get one platform's full publishing shape: the fields, options (enums), and character limits a post requires per format (post, reel, short, story, thread). Ground a destination's platformSettings against this instead of guessing the fields. Optionally pass a format to narrow the result.",
+        description: "Get one platform's full publishing shape: the fields, options (enums), and character limits a post requires per format (post, reel, short, story, thread). Ground a post's platformSettings against this instead of guessing the fields. Optionally pass a format to narrow the result.",
         inputSchema: {
             platform: z
                 .enum(POST_PLATFORMS)
@@ -1583,13 +1583,13 @@ export function registerTools(server, opts) {
     });
     // -- list_cards -----------------------------------------------------------
     server.registerTool('list_cards', {
-        title: 'List Posts',
+        title: 'List Cards',
         annotations: READ,
-        description: "List the account's content-pipeline posts (newest-updated first). Filter by status, platform, pipeline_stage (id/slug/name), folder, favorite, or a title search. Call get_card for one post's full detail (destinations + assets).",
+        description: "List the account's content-pipeline posts (newest-updated first). Filter by status, platform, stage (id/slug/name), folder, favorite, or a title search. Call get_card for one post's full detail (posts + assets).",
         inputSchema: {
             status: z.enum(['draft', 'active', 'completed', 'archived']).optional().describe('Filter by lifecycle status.'),
             platform: z.enum(POST_PLATFORMS).optional().describe('Filter by the post platform.'),
-            pipelineStage: z.string().optional().describe('Filter by a pipeline stage id, slug, or name.'),
+            stage: z.string().optional().describe('Filter by a stage id, slug, or name.'),
             search: z.string().optional().describe('Case-insensitive title search.'),
             limit: z.number().int().min(1).max(100).optional().describe('How many to return (default 50).'),
             offset: z.number().int().min(0).optional().describe('Pagination offset.'),
@@ -1600,7 +1600,7 @@ export function registerTools(server, opts) {
             return cardListResult(await client.listCards({
                 status: args.status,
                 platform: args.platform,
-                pipelineStage: args.pipelineStage,
+                stage: args.stage,
                 search: args.search,
                 limit: args.limit,
                 offset: args.offset,
@@ -1612,16 +1612,16 @@ export function registerTools(server, opts) {
     });
     // -- get_card -------------------------------------------------------------
     server.registerTool('get_card', {
-        title: 'Get Post',
+        title: 'Get Card',
         annotations: READ,
-        description: "Get one post in full: its fields (title, description, script, notes, status, stage, schedule), plus its publish destinations and attached assets.",
+        description: "Get one post in full: its fields (title, description, script, notes, status, stage, schedule), plus its publish posts and attached assets.",
         inputSchema: {
-            postId: z.string().describe('The post id from list_cards.'),
+            cardId: z.string().describe('The card id from list_cards.'),
         },
     }, async (args, extra) => {
         try {
             const client = await getClient(extra);
-            return cardResult(await client.getCard(args.postId));
+            return cardResult(await client.getCard(args.cardId));
         }
         catch (err) {
             return errorResult(err);
@@ -1666,7 +1666,7 @@ export function registerTools(server, opts) {
     server.registerTool('create_space', {
         title: 'Create Space',
         annotations: WRITE,
-        description: "Create a space: a new planner board with its own stages. duplicateFrom copies another space's STAGES, never its cards, so the new board arrives with the columns and none of the work. Requires the pipeline:write scope.",
+        description: "Create a space: a new planner board with its own stages. duplicateFrom copies another space's STAGES, never its cards, so the new board arrives with the columns and none of the work. Requires the planner:write scope.",
         inputSchema: {
             name: z.string().describe('The space name.'),
             coverUrl: z.string().optional().describe('A cover image URL for the space tile.'),
@@ -1692,7 +1692,7 @@ export function registerTools(server, opts) {
     server.registerTool('update_space', {
         title: 'Update Space',
         annotations: WRITE,
-        description: "Rename a space or change its cover. This is a PATCH: a field you omit is left alone, so renaming does not disturb the cover. Pass coverUrl as an empty string to REMOVE the cover. To favorite or archive a space, use the `favorite` and `archive` tools with assetType 'space' instead. Requires the pipeline:write scope.",
+        description: "Rename a space or change its cover. This is a PATCH: a field you omit is left alone, so renaming does not disturb the cover. Pass coverUrl as an empty string to REMOVE the cover. To favorite or archive a space, use the `favorite` and `archive` tools with assetType 'space' instead. Requires the planner:write scope.",
         inputSchema: {
             spaceId: z.string().describe('The space id to update.'),
             name: z.string().optional().describe('A new name.'),
@@ -1717,7 +1717,7 @@ export function registerTools(server, opts) {
     server.registerTool('delete_space', {
         title: 'Delete Space',
         annotations: WRITE,
-        description: 'Delete a space. The server REFUSES a space that still holds cards and names the count, because the delete cascades to every card in it along with their covers, captions, destinations and schedules. Archive the space instead if you want it out of the way. Requires the pipeline:write scope.',
+        description: 'Delete a space. The server REFUSES a space that still holds cards and names the count, because the delete cascades to every card in it along with their covers, captions, posts and schedules. Archive the space instead if you want it out of the way. Requires the planner:write scope.',
         inputSchema: { spaceId: z.string().describe('The space id to delete.') },
     }, async (args, extra) => {
         try {
@@ -1733,7 +1733,7 @@ export function registerTools(server, opts) {
     server.registerTool('list_stages', {
         title: 'List Pipeline Stages',
         annotations: READ,
-        description: "List the account's pipeline stages, in order. Stages are user-customizable (renamed, reordered, added, removed), so call this to discover the real stages before placing a post; pass a stage's id (most stable), slug, or name to create_card / update_card.",
+        description: "List the account's stages, in order. Stages are user-customizable (renamed, reordered, added, removed), so call this to discover the real stages before placing a post; pass a stage's id (most stable), slug, or name to create_card / update_card.",
     }, async (extra) => {
         try {
             const client = await getClient(extra);
@@ -1745,9 +1745,9 @@ export function registerTools(server, opts) {
     });
     // -- create_card ----------------------------------------------------------
     server.registerTool('create_card', {
-        title: 'Create Post',
+        title: 'Create Card',
         annotations: WRITE,
-        description: "Create a content-pipeline post. The post is the container; attach platforms with add_post_destination and media with add_post_asset, then schedule_post or publish_card. `stage` accepts a stage id/slug/name (defaults to the first stage). Requires a key with the pipeline:write scope.",
+        description: "Create a card, the container in the content pipeline. A card holds the work (title, script, notes, cover) and the posts that publish it. Attach posts and media by passing `posts` and `assets` to update_card, then publish with publish_post. `stage` accepts a stage id/slug/name (defaults to the first stage). Requires a key with the planner:write scope.",
         inputSchema: {
             title: z.string().describe('Post title (required).'),
             platform: z.enum(POST_PLATFORMS).describe('Primary platform for the post.'),
@@ -1780,15 +1780,23 @@ export function registerTools(server, opts) {
     });
     // -- update_card ----------------------------------------------------------
     server.registerTool('update_card', {
-        title: 'Update Post',
+        title: 'Update Card',
         annotations: WRITE,
-        description: "Update a post: its fields (title, description, script, notes, status, platform, cover, pipeline stage), its DESTINATIONS (which platforms it publishes to), its ASSETS (the media on it, in order), and its SCHEDULE. destinations and assets are DECLARATIVE: pass the WHOLE set, because anything you leave out is removed. Destinations key on platform. Assets key on id, and THE ARRAY ORDER IS THE carousel ORDER, so reordering is just sending the same ids in a different order; keep an existing asset by id, add a new one by assetUrl or outputId. scheduledAt sets the time on the post AND every destination (pass null to clear); give a destination its own scheduledAt to override it for that platform. To publish NOW, use publish_card. Requires the pipeline:write scope.",
+        description: "Update a card: its fields (title, description, script, notes, status, platform, cover, stage), its POSTS (one per platform, which is how it publishes), its ASSETS (the media on it, in order), and its SCHEDULE. posts and assets are DECLARATIVE: pass the WHOLE set, because anything you leave out is removed. Posts key on platform. Assets key on id, and THE ARRAY ORDER IS THE carousel ORDER, so reordering is just sending the same ids in a different order; keep an existing asset by id, add a new one by assetUrl or outputId. scheduledAt sets the time on the card AND every post (pass null to clear); give a post its own scheduledAt to override it for that platform. To publish NOW, use publish_post. Pass spaceId to MOVE the card to another space; without a stage it lands in the target space's stage whose slug matches its current one, or that space's first stage. Pass cardIds to update several cards at once, which crossed with spaceId is how a selection moves in one call; fields that describe ONE card (title, notes, script, cover) still need exactly one. Requires the planner:write scope.",
         inputSchema: {
-            postId: z.string().describe('The post id.'),
+            cardId: z.string().describe('The card id.'),
             title: z.string().optional(),
             platform: z.enum(POST_PLATFORMS).optional(),
             status: z.enum(['draft', 'active', 'completed', 'archived']).optional(),
             stage: z.string().optional().describe('Move the post to this stage (id, slug, or name).'),
+            spaceId: z
+                .string()
+                .optional()
+                .describe("Move the card to a different space (id or slug). Without a stage, it lands in that space's stage whose slug matches its current one, or that space's first stage."),
+            cardIds: z
+                .array(z.string())
+                .optional()
+                .describe('Update several cards at once. Fields that describe ONE card (title, notes, script, cover) still require exactly one.'),
             script: z.string().optional(),
             notes: z.string().optional(),
             coverUrl: z.string().optional().describe('Public URL for the post cover.'),
@@ -1804,11 +1812,11 @@ export function registerTools(server, opts) {
                 .string()
                 .nullable()
                 .optional()
-                .describe('ISO time to publish. Sets the post AND every destination. null clears the schedule.'),
-            destinations: z
-                .array(postDestinationSchema)
+                .describe('ISO time to publish. Sets the card AND every post. null clears the schedule.'),
+            posts: z
+                .array(cardPostSchema)
                 .optional()
-                .describe("The post's destinations, each { platform, format?, connectedAccountId?, platformSpecificData?, scheduledAt?, status? }. REPLACES the set, keyed by platform; [] detaches all."),
+                .describe("The card's posts, each { platform, format?, connectedAccountId?, platformSpecificData?, scheduledAt?, status? }. REPLACES the set, keyed by platform; [] detaches all."),
             assets: z
                 .array(postAssetSchema)
                 .optional()
@@ -1817,14 +1825,22 @@ export function registerTools(server, opts) {
     }, async (args, extra) => {
         try {
             const client = await getClient(extra);
-            const { postId, destinations, assets, ...input } = args;
+            const { cardId, cardIds, posts, assets, ...input } = args;
             // The two declarative arrays are `unknown[]` in the schema (their entries are free-form objects the
             // server validates), so they are cast at this one boundary rather than duplicating the shape in zod.
-            return postSummaryResult(await client.updateCard(postId, {
+            const patch = {
                 ...input,
-                ...(destinations !== undefined ? { destinations: destinations } : {}),
+                ...(posts !== undefined ? { posts: posts } : {}),
                 ...(assets !== undefined ? { assets: assets } : {}),
-            }), 'Updated');
+            };
+            // `cardIds` widens the path id, matching update_folder's folder_id / folder_ids. One card still
+            // goes through updateCard so the single-card response shape is unchanged for every caller.
+            const targets = cardIds?.length ? cardIds : [cardId];
+            if (targets.length > 1) {
+                const cards = await client.updateCards(targets, patch);
+                return text(`Updated ${cards.length} cards.`);
+            }
+            return postSummaryResult(await client.updateCard(targets[0], patch), 'Updated');
         }
         catch (err) {
             return errorResult(err);
@@ -1849,7 +1865,7 @@ export function registerTools(server, opts) {
     server.registerTool('create_tag', {
         title: 'Create Tag',
         annotations: WRITE,
-        description: "Create a tag in the account's tag library (the name is lowercased). Tags organize posts; apply them with the `tags` field on create_card / update_card. Requires the pipeline:write scope.",
+        description: "Create a tag in the account's tag library (the name is lowercased). Tags organize posts; apply them with the `tags` field on create_card / update_card. Requires the planner:write scope.",
         inputSchema: {
             name: z.string().describe('The tag name (lowercased on save).'),
         },
@@ -1866,7 +1882,7 @@ export function registerTools(server, opts) {
     server.registerTool('update_tag', {
         title: 'Update Tag',
         annotations: WRITE,
-        description: 'Rename a tag (preserves its assignments on all posts). To detach a tag from one post, set that post\'s `tags` without it via update_card. Requires the pipeline:write scope.',
+        description: 'Rename a tag (preserves its assignments on all posts). To detach a tag from one post, set that post\'s `tags` without it via update_card. Requires the planner:write scope.',
         inputSchema: {
             tagId: z.string().describe('The tag id (from list_tags).'),
             name: z.string().describe('The new tag name (lowercased on save).'),
@@ -1884,7 +1900,7 @@ export function registerTools(server, opts) {
     server.registerTool('delete_tag', {
         title: 'Delete Tag',
         annotations: WRITE,
-        description: "Delete a tag from the account's library. This DESTROYS the tag and removes it from every post it was on. To just detach a tag from one post, set that post's `tags` without it via update_card instead. Requires the pipeline:write scope.",
+        description: "Delete a tag from the account's library. This DESTROYS the tag and removes it from every post it was on. To just detach a tag from one post, set that post's `tags` without it via update_card instead. Requires the planner:write scope.",
         inputSchema: {
             tagId: z.string().describe('The tag id (from list_tags).'),
         },
@@ -1897,19 +1913,19 @@ export function registerTools(server, opts) {
             return errorResult(err);
         }
     });
-    // -- publish_card ---------------------------------------------------------
-    server.registerTool('publish_card', {
+    // -- publish_post ---------------------------------------------------------
+    server.registerTool('publish_post', {
         title: 'Publish Post',
         annotations: PUBLISH,
-        description: "Publish a post NOW to its destinations (a single platform when `platform` is given, otherwise all). Each destination must have a connected account. Requires a key with the publish:write scope; holding that scope is the account owner's consent to autonomous publishing. Returns per-destination results.",
+        description: "Publish a card's posts NOW: every post on the card, or only the named platform's post when `platform` is given. Each post must have a connected account. Requires a key with the publish:write scope; holding that scope is the account owner's consent to autonomous publishing. Returns one result per post.",
         inputSchema: {
-            postId: z.string().describe('The post id to publish.'),
-            platform: z.enum(POST_PLATFORMS).optional().describe('Publish only this platform. Omit to publish all destinations.'),
+            cardId: z.string().describe('The card id to publish.'),
+            platform: z.enum(POST_PLATFORMS).optional().describe('Publish only this platform. Omit to publish all posts.'),
         },
     }, async (args, extra) => {
         try {
             const client = await getClient(extra);
-            return publishResult(await client.publishCard(args.postId, { platform: args.platform }));
+            return publishResult(await client.publishPost(args.cardId, { platform: args.platform }));
         }
         catch (err) {
             return errorResult(err);
@@ -2031,7 +2047,7 @@ export function registerTools(server, opts) {
     server.registerTool('list_connected_accounts', {
         title: 'List Connected Accounts',
         annotations: READ,
-        description: "List the social accounts the owner has connected (the publish targets), default first. Use an account's id as connectedAccountId on add_post_destination, then publish_card. Read-only: connecting an account is done in the ContentHero app.",
+        description: "List the social accounts the owner has connected (the publish targets), default first. Use an account's id as connectedAccountId on a post in update_card, then publish_post. Read-only: connecting an account is done in the ContentHero app.",
     }, async (extra) => {
         try {
             const client = await getClient(extra);