@contenthero/mcp 0.4.2 → 0.4.3

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, 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',
@@ -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);
@@ -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);
@@ -1585,12 +1704,16 @@ 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: {
+            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,
@@ -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);
@@ -1833,7 +1963,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) {