@contenthero/mcp 0.4.2 → 0.4.4

package/dist/server.js

@@ -37,7 +37,7 @@ 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';
+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, stageResult, stageDeletedResult, 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',
@@ -207,6 +207,36 @@ function buildReferences(parts) {
  */
 export function registerTools(server, opts) {
     const { getClient, models } = opts;
+    /**
+     * 🚨🚨 **EVERY TOOL'S INPUT IS STRICT. AN UNDECLARED PARAMETER IS A 400, NEVER A SILENT DROP.**
+     *
+     * Zod object schemas STRIP unknown keys by default, and the SDK builds one from each `inputSchema` shape.
+     * So before this wrapper, all 85 tools accepted any parameter they did not declare, discarded it, and ran
+     * on whatever survived. The failure is invisible by construction: the caller gets a success.
+     *
+     * ⚠️ **THE MEASURED CASE, 2026-09-08.** `update_card` does not declare `ops`. A call passing `ops` had it
+     * stripped, leaving only `cardId`, and returned **"Updated: 01.3 Design Your Character"** having written
+     * nothing. A second call passing the nonsense op `__probe__` did the same. An agent running a batch of
+     * partial edits would collect a full set of success messages and zero writes.
+     *
+     * ⭐⭐ **WRAPPED HERE RATHER THAN AT 85 CALL SITES, AND THAT IS THE POINT.** A rule every registration must
+     * remember is a rule that holds until someone adds the 86th tool. Same move as `withSpineRegistration`
+     * wrapping the Supabase client instead of asking 73 upload sites to declare an owner.
+     *
+     * ⚠️ **NESTED `.passthrough()` SURVIVES, DELIBERATELY.** `update_timeline` and `update_canvas` declare
+     * `ops: z.array(z.object({ op: z.string() }).passthrough())` because a timeline op carries a different
+     * shape per op type. Strictness here applies to the TOP-LEVEL argument object only, so those keep taking
+     * varied op payloads while still rejecting an undeclared top-level parameter.
+     */
+    const rawRegisterTool = server.registerTool.bind(server);
+    server.registerTool = ((name, config, cb) => {
+        const shape = config.inputSchema;
+        // A tool with no inputs, or one that already passed a built schema, is left exactly as it was.
+        const strict = shape && typeof shape === 'object' && !(shape instanceof z.ZodType)
+            ? z.object(shape).strict()
+            : shape;
+        return rawRegisterTool(name, { ...config, inputSchema: strict }, cb);
+    });
     /**
      * ⚠️ THESE SHAPES ARE DECLARED, NOT LEFT AS `z.unknown()`. An array of unknown serialises to
      * `{"type":"array","items":{}}`, which tells a client NOTHING about what may go inside it. The server
@@ -286,6 +316,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 +336,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 +379,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 +394,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 +775,119 @@ 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.'),
+                    name: z
+                        .string()
+                        .optional()
+                        .describe("What to call the look. Applied to every image in this op. Omit and it stays unnamed, displaying by its source label ('from_media'), which is rarely what you want for a look you will pick from a list later."),
+                }),
+                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 +1310,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 +1329,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 +1341,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 +1376,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 +1402,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);
@@ -1462,11 +1615,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 +1658,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 +1666,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 +1677,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);
@@ -1585,12 +1738,19 @@ export function registerTools(server, opts) {
     server.registerTool('list_cards', {
         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 (posts + 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: {
-            status: z.enum(['draft', 'active', 'completed', 'archived']).optional().describe('Filter by lifecycle status.'),
+            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."),
+            archived: z
+                .boolean()
+                .optional()
+                .describe('Only ARCHIVED cards. Archived cards are excluded by default, matching the board.'),
             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,7 +1758,8 @@ export function registerTools(server, opts) {
         try {
             const client = await getClient(extra);
             return cardListResult(await client.listCards({
-                status: args.status,
+                spaceId: args.spaceId,
+                archived: args.archived,
                 platform: args.platform,
                 stage: args.stage,
                 search: args.search,
@@ -1733,11 +1894,115 @@ 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({ spaceId: args.spaceId }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // -- create_stage ---------------------------------------------------------
+    server.registerTool('create_stage', {
+        title: 'Create Stage',
+        annotations: WRITE,
+        description: "Create a stage (a column on one board). ⚠️ STAGES ARE PER-SPACE: without spaceId this creates on the account's DEFAULT board, which is rarely what you want once more than one space exists, so call list_spaces first. The slug is DERIVED from the name and is not settable; a board cannot hold two columns whose names produce the same slug and the server refuses the second rather than renaming it for you. Place the column with afterId/beforeId, or omit both to put it at the end. Requires the planner:write scope.",
+        inputSchema: {
+            name: z.string().describe('The column name, for example "In Review". Must contain a letter or number.'),
+            spaceId: z
+                .string()
+                .optional()
+                .describe("Which board, from list_spaces. Omit only when you mean the account's default space."),
+            color: z.string().optional().describe('A hex color such as "#3B82F6".'),
+            afterId: z.string().optional().describe('Put the new column immediately after this stage id.'),
+            beforeId: z.string().optional().describe('Put the new column immediately before this stage id.'),
+        },
+    }, async (args, extra) => {
+        try {
+            const client = await getClient(extra);
+            return stageResult(await client.createStage({
+                name: args.name,
+                spaceId: args.spaceId,
+                color: args.color,
+                afterId: args.afterId,
+                beforeId: args.beforeId,
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // -- update_stage ---------------------------------------------------------
+    server.registerTool('update_stage', {
+        title: 'Update Stage',
+        annotations: WRITE,
+        description: "Rename, recolor or move one stage. This is a PATCH: a field you omit is left alone. ⚠️ spaceId is REQUIRED, because a stage id alone does not tell the server which board you mean and guessing the wrong one silently changes nothing. Renaming re-derives the slug, so renaming a column away from 'Published' also stops publishing auto-moving cards into it; a rename that collides with another column on the same board is refused. Moving names NEIGHBORS, not a position: pass afterId or beforeId. Requires the planner:write scope.",
+        inputSchema: {
+            stageId: z.string().describe('The stage id to update, from list_stages.'),
+            spaceId: z.string().describe('The board this stage is on, from list_stages or list_spaces.'),
+            name: z.string().optional().describe('A new name. The slug follows it automatically.'),
+            color: z.string().optional().describe('A new hex color such as "#3B82F6".'),
+            afterId: z
+                .string()
+                .optional()
+                .describe('Move it immediately after this stage id. Use the empty string to move it to the far left.'),
+            beforeId: z
+                .string()
+                .optional()
+                .describe('Move it immediately before this stage id. Use the empty string to move it to the far right.'),
+        },
+    }, async (args, extra) => {
         try {
             const client = await getClient(extra);
-            return stageListResult(await client.listStages());
+            /*
+              An empty string is how a tool caller says "the edge": JSON Schema cannot distinguish an
+              omitted string from an explicit null in a plain string field, and the two mean opposite
+              things here. Omitted means "do not move it"; null means "move it to the end of the board".
+              `update_space` resolves the same ambiguity the same way for coverUrl.
+            */
+            const edge = (v) => (v === undefined ? undefined : v === '' ? null : v);
+            const { stage, respaced } = await client.updateStage(args.stageId, {
+                spaceId: args.spaceId,
+                name: args.name,
+                color: args.color,
+                afterId: edge(args.afterId),
+                beforeId: edge(args.beforeId),
+            });
+            return stageResult(stage, respaced);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // -- delete_stage ---------------------------------------------------------
+    server.registerTool('delete_stage', {
+        title: 'Delete Stage',
+        annotations: WRITE,
+        description: 'Delete a stage and move its cards to another column. The server REFUSES a column that still holds cards when you name no targetStageId, and tells you how many there are: cards are never destroyed by deleting a column, and the delete and the reassignment happen in one transaction. Returns the board that is left. Requires the planner:write scope.',
+        inputSchema: {
+            stageId: z.string().describe('The stage id to delete, from list_stages.'),
+            spaceId: z.string().describe('The board this stage is on.'),
+            targetStageId: z
+                .string()
+                .optional()
+                .describe('Where this column\'s cards should go. Required unless the column is empty.'),
+        },
+    }, async (args, extra) => {
+        try {
+            const client = await getClient(extra);
+            const result = await client.deleteStage(args.stageId, {
+                spaceId: args.spaceId,
+                targetStageId: args.targetStageId ?? null,
+            });
+            return stageDeletedResult(result.id, result.movedCards, result.stages);
         }
         catch (err) {
             return errorResult(err);
@@ -1782,12 +2047,11 @@ export function registerTools(server, opts) {
     server.registerTool('update_card', {
         title: 'Update Card',
         annotations: WRITE,
-        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.",
+        description: "Update a card: its fields (title, description, script, notes, 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: {
             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()
@@ -1833,7 +2097,7 @@ export function registerTools(server, opts) {
                 ...(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 : [cardId];
             if (targets.length > 1) {
@@ -2126,7 +2390,7 @@ export function registerTools(server, opts) {
     server.registerTool('archive', {
         title: 'Archive',
         annotations: WRITE,
-        description: "Archive or UNarchive an asset: pass archived:false to restore it (default true). ContentHero never hard-deletes, so this is always reversible. For a top-level asset, pass assetType + id (card, brand_kit, brand_kit_section, project, space). To archive a single studio media variation, pass the output id + variationIndex (1-based) and omit assetType. Archiving a card sets its status to 'archived'; restoring returns it to 'draft'. Requires the favorites:write scope. Idempotent in both directions.",
+        description: "Archive or UNarchive an asset: pass archived:false to restore it (default true). ContentHero never hard-deletes, so this is always reversible. For a top-level asset, pass assetType + id (card, brand_kit, brand_kit_section, project, space). To archive a single studio media variation, pass the output id + variationIndex (1-based) and omit assetType. Archiving is a timestamp and nothing else is touched, so a scheduled card restores as scheduled. Requires the favorites:write scope. Idempotent in both directions.",
         inputSchema: {
             assetType: z
                 .enum(['card', 'brand_kit', 'brand_kit_section', 'project', 'space'])
@@ -2388,12 +2652,12 @@ export function registerTools(server, opts) {
     server.registerTool('export_project', {
         title: 'Export Project',
         annotations: WRITE,
-        description: "Export (render) a project's saved composition to a downloadable file the user KEEPS: a permanent deliverable that counts against the user's storage. To preview or verify a frame or slide while editing, do NOT export; use get_context with render (ephemeral, stored nowhere). format 'mp4' works for both editor and canvas (a video render; may take a while). 'png' / 'jpg' work for both surfaces too: a canvas project renders one image per slide (multiple slides come back as a zip), while an editor project renders a single composited frame of the timeline (pick which frame with `frame`; defaults to frame 0). Canvas projects additionally support 'pdf' and 'pptx'. For mp4, resolution ('720p' default; 1080p/2k/4k are plan-gated) and watermark (default on; removing it is plan-gated) apply. Returns the download URL when the render finishes in time, otherwise an exportId to poll with get_export. Requires the editor:write scope.",
+        description: "Export (render) a project's saved composition to a downloadable file the user KEEPS: a permanent deliverable that counts against the user's storage. To preview or verify a frame or slide while editing, do NOT export; use get_context with render (ephemeral, stored nowhere). format 'mp4' works for both editor and canvas (a video render; may take a while). 'png' / 'jpg' work for both surfaces too: a canvas project renders one image per slide (multiple slides come back as a zip), while an editor project renders a single composited frame of the timeline (pick which frame with `frame`; defaults to frame 0). Canvas projects additionally support 'pdf' and 'pptx'. Resolution and watermark apply to EVERY format, not just mp4: a free account never exports above 720p and never removes the watermark, on any format or surface. `quality` is mp4 only. Returns the download URL when the render finishes in time, otherwise an exportId to poll with get_export. Requires the editor:write scope.",
         inputSchema: {
             projectId: z.string().describe('The project to export.'),
             format: z.enum(['mp4', 'png', 'jpg', 'pdf', 'pptx']).optional().describe("Output format. Defaults to 'mp4'. mp4/png/jpg work for both surfaces (png/jpg on an editor project render one timeline frame); pdf/pptx are canvas-only."),
-            resolution: z.enum(['480p', '720p', '1080p', '2k', '4k']).optional().describe("mp4 video resolution. Defaults '720p'. 1080p+ is plan-gated."),
-            quality: z.enum(['low', 'recommended', 'high']).optional().describe('mp4 video quality. Defaults recommended.'),
+            resolution: z.enum(['480p', '720p', '1080p', '2k', '4k']).optional().describe("Output resolution, for EVERY format including stills. Defaults '720p' for an editor mp4 and the project's NATIVE size for a still or canvas mp4, in both cases clamped to your plan. 1080p and above are plan-gated: NAMING one above your plan is a 403, omitting one clamps instead."),
+            quality: z.enum(['low', 'recommended', 'high']).optional().describe('mp4 ONLY: video bitrate. Meaningless for a still, which has no duration to spread bits over. Defaults recommended.'),
             watermark: z.boolean().optional().describe('Keep the watermark. Defaults true; removing it is plan-gated.'),
             frame: z.number().int().min(0).optional().describe('Editor still (png/jpg) only: which timeline frame to render. Clamped to the composition length. Defaults 0. Use the playhead frame from get_context to render exactly the frame the user is viewing.'),
         },