@contenthero/mcp 0.4.3 → 0.4.5

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, 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';
+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
@@ -816,6 +846,10 @@ export function registerTools(server, opts) {
                     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'),
@@ -1710,7 +1744,10 @@ export function registerTools(server, opts) {
                 .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.'),
+            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. Resolved within the chosen space.'),
             search: z.string().optional().describe('Case-insensitive title search, scoped to the chosen space.'),
@@ -1722,7 +1759,7 @@ export function registerTools(server, opts) {
             const client = await getClient(extra);
             return cardListResult(await client.listCards({
                 spaceId: args.spaceId,
-                status: args.status,
+                archived: args.archived,
                 platform: args.platform,
                 stage: args.stage,
                 search: args.search,
@@ -1873,14 +1910,116 @@ export function registerTools(server, opts) {
             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);
+            /*
+              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);
+        }
+    });
     // -- create_card ----------------------------------------------------------
     server.registerTool('create_card', {
         title: 'Create Card',
         annotations: WRITE,
-        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.",
+        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. ⚠️ WITHOUT spaceId THIS LANDS ON THE ACCOUNT'S DEFAULT BOARD, which is rarely what you want once more than one space exists, so call list_spaces first. `stage` accepts a stage id/slug/name and DECIDES the space when it is an id; a spaceId that disagrees with it is rejected rather than guessed. 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.'),
+            spaceId: z
+                .string()
+                .optional()
+                .describe("Which board to create the card on, from list_spaces. Omit only when you mean the account's default space."),
             stage: z.string().optional().describe('Pipeline stage id, slug, or name. Defaults to the first stage.'),
             coverUrl: z.string().optional().describe('Public URL for the post cover (the card thumbnail).'),
             coverOutputId: z
@@ -1898,6 +2037,7 @@ export function registerTools(server, opts) {
             return postSummaryResult(await client.createCard({
                 title: args.title,
                 platform: args.platform,
+                spaceId: args.spaceId,
                 stage: args.stage,
                 coverUrl: args.coverUrl,
                 coverOutputId: args.coverOutputId,
@@ -1912,12 +2052,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()
@@ -2256,7 +2395,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'])
@@ -2518,12 +2657,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.'),
         },