@contenthero/mcp 0.4.1 → 0.4.3

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, 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 post or destination may target. */
+import { audioResult, avatarListResult, avatarResult, avatarPendingResult, 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(),
     });
@@ -286,6 +286,10 @@ export function registerTools(server, opts) {
                 .array(z.string())
                 .optional()
                 .describe('References for image-to-image / editing. Each may be a URL or a previous output id (e.g. "<id>" or "<id>-2") to chain from an earlier generation.'),
+            avatarId: z
+                .string()
+                .optional()
+                .describe('Optional avatar id from list_avatars. File the result onto that avatar as a new LOOK (one appearance of a reusable character: same person, different outfit, setting or framing) instead of saving a standalone library output. Combine with a referenceImage of the avatar to keep the subject on-model.'),
             ...PLACEMENT_INPUT_FIELDS,
             getCost: z.boolean().optional().describe('Return the credit cost estimate instead of generating (nothing runs, nothing is charged).'),
         },
@@ -302,6 +306,7 @@ export function registerTools(server, opts) {
                 seed: args.seed,
                 references: buildReferences({ images: args.referenceImages }),
                 parameters: args.mode ? { mode: args.mode } : undefined,
+                avatarId: args.avatarId,
                 projectId: args.projectId,
                 placement: args.placement,
                 playheadFrame: args.playheadFrame,
@@ -344,6 +349,10 @@ export function registerTools(server, opts) {
                 .optional()
                 .describe('Number of board variations (1-4). Defaults to 1.'),
             boardName: z.string().optional().describe('Optional name for the board.'),
+            avatarId: z
+                .string()
+                .optional()
+                .describe('Optional avatar id from list_avatars. Associate the board with that avatar, so a character sheet built for an avatar stays filed against it.'),
             getCost: z.boolean().optional().describe('Return the credit cost estimate instead of generating (nothing runs, nothing is charged).'),
         },
     }, async (args, extra) => {
@@ -355,6 +364,7 @@ export function registerTools(server, opts) {
                 referenceImages: args.referenceImages,
                 numImages: args.numImages,
                 boardName: args.boardName,
+                avatarId: args.avatarId,
             });
             if (args.getCost)
                 return costResult(await client.estimateBoardCost(request));
@@ -735,6 +745,115 @@ export function registerTools(server, opts) {
             return errorResult(err);
         }
     });
+    // -- create_avatar --------------------------------------------------------
+    server.registerTool('create_avatar', {
+        title: 'Create Avatar',
+        annotations: WRITE,
+        description: "Create a reusable character and start generating its first look. SPENDS CREDITS (pass getCost to preview the price without creating anything). Returns as soon as the record exists: the avatar is NOT usable yet, it sits at status 'processing' with no image until its first look finishes, so poll get_avatar until status is 'completed'. Supply referenceImageUrls to make the avatar a likeness of a real person from their photos; omit them to invent a character from the description and traits.",
+        inputSchema: {
+            name: z.string().describe('Avatar name, at least 3 characters.'),
+            age: z.string().describe("Apparent age, e.g. '20s', '35', 'middle-aged'. Required: the prompt writer describes the character from these traits."),
+            gender: z.string().describe('Gender presentation. Required, same reason as age.'),
+            ethnicity: z.string().optional().describe('Optional ethnicity, for a more specific likeness.'),
+            niche: z.array(z.string()).optional().describe('Content niches this character is for, e.g. ["fitness","nutrition"].'),
+            style: z.string().optional().describe('Visual style hint for the portrait, e.g. "editorial", "cinematic". Not stored on the avatar.'),
+            description: z
+                .string()
+                .optional()
+                .describe('Free-text description of the character. The strongest single input when no reference photos are given.'),
+            defaultVoiceId: z.string().optional().describe('A voiceId from list_voices, used as this avatar the default voice.'),
+            referenceImageUrls: z
+                .array(z.string())
+                .optional()
+                .describe('Photos of a REAL PERSON to anchor identity to: each a URL or a previous output id. Only use photos of someone who has agreed to being cloned.'),
+            getCost: z.boolean().optional().describe('Return the credit cost estimate instead of creating (nothing runs, nothing is charged).'),
+        },
+    }, async (args, extra) => {
+        try {
+            const client = await getClient(extra);
+            if (args.getCost) {
+                const creditsEstimate = await client.estimateAvatarCost();
+                // `modelId` is the first thing `costResult` names in its sentence, and `contentType` only
+                // admits image/video/audio. An avatar is none of those: the price is the fixed
+                // avatar-creation fee, not the cost of the portrait model, so say that rather than pick a
+                // media kind that would misdescribe it.
+                return costResult({ getCost: true, creditsEstimate, modelId: 'avatar creation' });
+            }
+            const created = await client.createAvatar({
+                name: args.name,
+                age: args.age,
+                gender: args.gender,
+                ethnicity: args.ethnicity,
+                niche: args.niche,
+                style: args.style,
+                description: args.description,
+                defaultVoiceId: args.defaultVoiceId,
+                referenceImageUrls: args.referenceImageUrls,
+            });
+            return avatarPendingResult(created);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // -- update_avatar --------------------------------------------------------
+    server.registerTool('update_avatar', {
+        title: 'Update Avatar',
+        annotations: WRITE,
+        description: "Update an avatar and/or change its looks. Fields: name, defaultLookId (also becomes the avatar's profile photo), defaultVoiceId. Looks are changed through ops, the same shape update_timeline and update_canvas use: add_look files images the account ALREADY OWNS onto the avatar, remove_look trashes one (recoverable for 30 days). Ops run before the fields, so one call can add a look and make it the default. To GENERATE a new look instead of filing an existing image, call generate_image with avatarId.",
+        inputSchema: {
+            avatarId: z.string().describe('The avatar id from list_avatars.'),
+            name: z.string().optional().describe('New name, at least 3 characters.'),
+            defaultLookId: z
+                .string()
+                .optional()
+                .describe("A look id from get_avatar. Becomes the avatar's default look AND its profile photo."),
+            defaultVoiceId: z.string().nullable().optional().describe('A voiceId from list_voices, or null to clear it.'),
+            ops: z
+                .array(z.union([
+                z.object({
+                    op: z.literal('add_look'),
+                    imageUrls: z
+                        .array(z.string())
+                        .describe('Images the account already owns, as URLs: an upload, a creation, an editor export, or another avatar look. Anything not owned by this account is skipped rather than failing the call.'),
+                }),
+                z.object({
+                    op: z.literal('remove_look'),
+                    lookId: z.string().describe('A look id from get_avatar.'),
+                }),
+            ]))
+                .optional()
+                .describe('Look changes, applied in order before the field updates. NOT a transaction: a failure part-way leaves earlier ops applied.'),
+        },
+    }, async (args, extra) => {
+        try {
+            const client = await getClient(extra);
+            const { avatarId, ...request } = args;
+            const updated = await client.updateAvatar(avatarId, request);
+            return avatarResult(updated.avatar);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // -- delete_avatar --------------------------------------------------------
+    server.registerTool('delete_avatar', {
+        title: 'Delete Avatar',
+        annotations: WRITE,
+        description: "Delete an avatar. Soft: the avatar stops appearing, but ITS LOOKS SURVIVE as library images and can be filed onto another avatar with update_avatar's add_look. Use this to retire a duplicate or an abandoned character, after moving any looks worth keeping.",
+        inputSchema: {
+            avatarId: z.string().describe('The avatar id from list_avatars.'),
+        },
+    }, async (args, extra) => {
+        try {
+            const client = await getClient(extra);
+            await client.deleteAvatar(args.avatarId);
+            return text(`Avatar ${args.avatarId} deleted. Its looks are retained and can be filed onto another avatar with update_avatar add_look.`);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
     // -- list_voices ----------------------------------------------------------
     server.registerTool('list_voices', {
         title: 'List Voices',
@@ -1157,11 +1276,11 @@ export function registerTools(server, opts) {
         annotations: READ,
         description: "Return the contents of one folder. The folder id is either one of the account's own folder ids or a built-in derived-folder key. A manual folder returns exactly the items filed in it; a smart folder computes its members live from its saved query; a derived folder returns its built-in set. Items are media (with kind and a description) and, in manual folders, entities such as projects or posts.",
         inputSchema: {
-            folder_id: z.string().describe('A folder id, or a derived-folder key (recents, favorites, edits, canvas, cards).'),
+            folderId: z.string().describe('A folder id, or a derived-folder key (recents, favorites, edits, canvas, cards).'),
         },
     }, async (args, extra) => {
         try {
-            const r = await (await getClient(extra)).getFolder(args.folder_id);
+            const r = await (await getClient(extra)).getFolder(args.folderId);
             return folderContentsResult(r.folder, r.items);
         }
         catch (err) {
@@ -1176,11 +1295,11 @@ export function registerTools(server, opts) {
             name: z.string().describe('The folder name.'),
             type: z.enum(['manual', 'smart']).optional().describe("'manual' (a collection you file items into) or 'smart' (a saved live query). Defaults to manual."),
             query: smartQuerySchema,
-            parent_id: z.string().optional().describe('Nest the new folder under this parent folder id.'),
+            parentId: z.string().optional().describe('Nest the new folder under this parent folder id.'),
         },
     }, async (args, extra) => {
         try {
-            const f = await (await getClient(extra)).createFolder({ name: args.name, type: args.type, query: args.query, parentId: args.parent_id });
+            const f = await (await getClient(extra)).createFolder({ name: args.name, type: args.type, query: args.query, parentId: args.parentId });
             return text(`Created ${f.type} folder "${f.name}" (id ${f.id}).`);
         }
         catch (err) {
@@ -1188,32 +1307,32 @@ export function registerTools(server, opts) {
         }
     });
     /**
-     * One item's universal identity. NO folder_id: the folder is named by the tool's own folder_id /
-     * folder_ids now, which is what lets one call file many items into many folders.
+     * One item's universal identity. NO folderId: the folder is named by the tool's own folderId /
+     * folderIds now, which is what lets one call file many items into many folders.
      */
     const itemRefBodySchema = z.object({
-        source_table: z.string().describe("The item's source table (e.g. as returned by search_media)."),
-        source_record_id: z.string().describe("The item's source record id."),
+        sourceTable: z.string().describe("The item's source table (e.g. as returned by list_media / get_media)."),
+        sourceRecordId: z.string().describe("The item's source record id."),
         variant: z.number().int().optional().describe('The variation index (default 0 for single-asset items).'),
     });
     server.registerTool('update_folder', {
         title: 'Update Folder',
         annotations: WRITE,
-        description: "Update the account's own folders: rename one, MOVE folders under a different parent (or to the top level with a null parent), change a smart folder's saved query, and FILE or UNFILE items. addItems/removeItems are DELTAS of { source_table, source_record_id, variant? }, not a list to replace, because an item can sit in several folders at once and a replace would silently unfile it from the others. Filing never moves or copies anything: it adds a pointer, and only manual folders accept items (a smart folder computes its own membership). Pass folderIds to patch several folders at once, which crossed with addItems files the same items into all of them; renaming and re-querying still need exactly one folder. NOTE the asymmetry: nesting a FOLDER via parentId is a MOVE (a folder has one parent), while filing an ITEM is a pointer that leaves its other folders alone.",
+        description: "Update the account's own folders: rename one, MOVE folders under a different parent (or to the top level with a null parent), change a smart folder's saved query, and FILE or UNFILE items. addItems/removeItems are DELTAS of { sourceTable, sourceRecordId, variant? }, not a list to replace, because an item can sit in several folders at once and a replace would silently unfile it from the others. Filing never moves or copies anything: it adds a pointer, and only manual folders accept items (a smart folder computes its own membership). Pass folderIds to patch several folders at once, which crossed with addItems files the same items into all of them; renaming and re-querying still need exactly one folder. NOTE the asymmetry: nesting a FOLDER via parentId is a MOVE (a folder has one parent), while filing an ITEM is a pointer that leaves its other folders alone.",
         inputSchema: {
-            folder_id: z.string().describe('The folder id to update.'),
-            folder_ids: z
+            folderId: z.string().describe('The folder id to update.'),
+            folderIds: z
                 .array(z.string())
                 .optional()
                 .describe('Patch several folders at once. Attribute fields (name, query) still need exactly one.'),
             name: z.string().optional().describe('A new name.'),
-            parent_id: z.string().nullable().optional().describe('A new parent folder id, or null to move to the top level. MOVES the folder.'),
+            parentId: z.string().nullable().optional().describe('A new parent folder id, or null to move to the top level. MOVES the folder.'),
             query: smartQuerySchema,
-            add_items: z
+            addItems: z
                 .array(itemRefBodySchema)
                 .optional()
                 .describe('File these items into the folder(s). A delta: their other folders are untouched.'),
-            remove_items: z
+            removeItems: z
                 .array(itemRefBodySchema)
                 .optional()
                 .describe('Unfile these items. Only the pointer goes; the asset is never deleted.'),
@@ -1223,17 +1342,17 @@ export function registerTools(server, opts) {
             const client = await getClient(extra);
             const patch = {
                 name: args.name,
-                parentId: args.parent_id,
+                parentId: args.parentId,
                 query: args.query,
-                addItems: args.add_items?.map((r) => ({ sourceTable: r.source_table, sourceRecordId: r.source_record_id, variant: r.variant })),
-                removeItems: args.remove_items?.map((r) => ({ sourceTable: r.source_table, sourceRecordId: r.source_record_id, variant: r.variant })),
+                addItems: args.addItems,
+                removeItems: args.removeItems,
             };
-            const targets = args.folder_ids?.length ? args.folder_ids : [args.folder_id];
+            const targets = args.folderIds?.length ? args.folderIds : [args.folderId];
             const folders = targets.length > 1
                 ? await client.updateFolders(targets, patch)
                 : [await client.updateFolder(targets[0], patch)];
-            const filed = args.add_items?.length ?? 0;
-            const unfiled = args.remove_items?.length ?? 0;
+            const filed = args.addItems?.length ?? 0;
+            const unfiled = args.removeItems?.length ?? 0;
             const what = [
                 filed ? `filed ${filed} item(s)` : null,
                 unfiled ? `unfiled ${unfiled} item(s)` : null,
@@ -1249,11 +1368,11 @@ export function registerTools(server, opts) {
         title: 'Delete Folder',
         annotations: WRITE,
         description: "Delete one of the account's own folders and everything nested under it. This removes the folder structure only; the media and entities inside are pointers, so the underlying assets are never deleted. Confirm intent before deleting a folder that contains items.",
-        inputSchema: { folder_id: z.string().describe('The folder id to delete.') },
+        inputSchema: { folderId: z.string().describe('The folder id to delete.') },
     }, async (args, extra) => {
         try {
-            await (await getClient(extra)).deleteFolder(args.folder_id);
-            return text(`Deleted folder ${args.folder_id}.`);
+            await (await getClient(extra)).deleteFolder(args.folderId);
+            return text(`Deleted folder ${args.folderId}.`);
         }
         catch (err) {
             return errorResult(err);
@@ -1423,7 +1542,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)
@@ -1462,11 +1581,11 @@ export function registerTools(server, opts) {
         title: 'Get Element',
         annotations: READ,
         description: "Get one saved reference element by id: its name, category, description, and images.",
-        inputSchema: { id: z.string().describe('The element id.') },
+        inputSchema: { elementId: z.string().describe('The element id.') },
     }, async (args, extra) => {
         try {
             const client = await getClient(extra);
-            return elementResult(await client.getElement(args.id));
+            return elementResult(await client.getElement(args.elementId));
         }
         catch (err) {
             return errorResult(err);
@@ -1505,7 +1624,7 @@ export function registerTools(server, opts) {
         annotations: WRITE,
         description: "Update a saved element's name, description, or category.",
         inputSchema: {
-            id: z.string().describe('The element id.'),
+            elementId: z.string().describe('The element id.'),
             name: z.string().optional(),
             description: z.string().optional(),
             category: z.enum(['auto', 'character', 'location', 'prop']).optional(),
@@ -1513,7 +1632,7 @@ export function registerTools(server, opts) {
     }, async (args, extra) => {
         try {
             const client = await getClient(extra);
-            return elementResult(await client.updateElement(args.id, { name: args.name, description: args.description, category: args.category }), 'Updated');
+            return elementResult(await client.updateElement(args.elementId, { name: args.name, description: args.description, category: args.category }), 'Updated');
         }
         catch (err) {
             return errorResult(err);
@@ -1524,12 +1643,12 @@ export function registerTools(server, opts) {
         title: 'Delete Element',
         annotations: WRITE,
         description: 'Delete a saved reference element.',
-        inputSchema: { id: z.string().describe('The element id.') },
+        inputSchema: { elementId: z.string().describe('The element id.') },
     }, async (args, extra) => {
         try {
             const client = await getClient(extra);
-            await client.deleteElement(args.id);
-            return elementDeletedResult(args.id);
+            await client.deleteElement(args.elementId);
+            return elementDeletedResult(args.elementId);
         }
         catch (err) {
             return errorResult(err);
@@ -1583,14 +1702,18 @@ 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, stage (id/slug/name), folder, favorite, or a title search. Call get_card for one post's full detail (destinations + assets).",
+        description: "List one SPACE's cards (newest-updated first). ⚠️ SCOPED, NOT COMPLETE: without spaceId this lists the account's DEFAULT space only, and cards on any other board are absent with nothing in the response saying so (search misses them too). Call list_spaces FIRST and pass spaceId unless you specifically mean the default board. Filter by status, platform, stage (id/slug/name), favorite, or a title search. Call get_card for one card's full detail (posts + assets).",
         inputSchema: {
+            spaceId: z
+                .string()
+                .optional()
+                .describe("Which space's board to list, from list_spaces. Omit ONLY when you mean the account's default space; omitting it does not search every board."),
             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.'),
-            stage: z.string().optional().describe('Filter by a stage id, slug, or name.'),
-            search: z.string().optional().describe('Case-insensitive title search.'),
+            stage: z.string().optional().describe('Filter by a stage id, slug, or name. Resolved within the chosen space.'),
+            search: z.string().optional().describe('Case-insensitive title search, scoped to the chosen space.'),
             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.'),
         },
@@ -1598,6 +1721,7 @@ export function registerTools(server, opts) {
         try {
             const client = await getClient(extra);
             return cardListResult(await client.listCards({
+                spaceId: args.spaceId,
                 status: args.status,
                 platform: args.platform,
                 stage: args.stage,
@@ -1612,16 +1736,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);
@@ -1717,7 +1841,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 planner: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,11 +1857,17 @@ export function registerTools(server, opts) {
     server.registerTool('list_stages', {
         title: 'List Pipeline Stages',
         annotations: READ,
-        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) => {
+        description: "List one SPACE's stages, in order. ⚠️ STAGES ARE PER-SPACE: without spaceId this is the account's DEFAULT space, and two spaces can each hold a stage named 'Published' with different ids, so a stage name resolved against the wrong space is a different column. Stages are user-customizable (renamed, reordered, added, removed), so call this to discover the real stages before placing a card; pass a stage's id (most stable), slug, or name to create_card / update_card.",
+        inputSchema: {
+            spaceId: z
+                .string()
+                .optional()
+                .describe("Which space's stages, from list_spaces. Omit only when you mean the account's default space."),
+        },
+    }, async (args, extra) => {
         try {
             const client = await getClient(extra);
-            return stageListResult(await client.listStages());
+            return stageListResult(await client.listStages({ spaceId: args.spaceId }));
         }
         catch (err) {
             return errorResult(err);
@@ -1745,9 +1875,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 planner: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,11 +1910,11 @@ 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, 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. 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.",
+        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(),
@@ -1812,11 +1942,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()
@@ -1825,17 +1955,17 @@ export function registerTools(server, opts) {
     }, async (args, extra) => {
         try {
             const client = await getClient(extra);
-            const { postId, cardIds, 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.
             const patch = {
                 ...input,
-                ...(destinations !== undefined ? { destinations: destinations } : {}),
+                ...(posts !== undefined ? { posts: posts } : {}),
                 ...(assets !== undefined ? { assets: assets } : {}),
             };
-            // `cardIds` widens the path id, matching update_folder's folder_id / folder_ids. One card still
+            // `cardIds` widens the path id, matching update_folder's folderId / folderIds. One card still
             // goes through updateCard so the single-card response shape is unchanged for every caller.
-            const targets = cardIds?.length ? cardIds : [postId];
+            const targets = cardIds?.length ? cardIds : [cardId];
             if (targets.length > 1) {
                 const cards = await client.updateCards(targets, patch);
                 return text(`Updated ${cards.length} cards.`);
@@ -1913,19 +2043,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);
@@ -2047,7 +2177,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);