@craftstory/mcp 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.3 - 2026-09-12
+- tool annotations (readOnlyHint / destructiveHint) on every tool; Privacy Policy section in the README
+- MCPB bundle for Claude Desktop (manifest.json, icon) attached to GitHub releases
+- `mcpName` for the official MCP Registry; server.json
+
+## 0.1.2 - 2026-09-12
+- package metadata: public repository and issue tracker on GitHub (itseez3d/craftstory-mcp); CHANGELOG shipped
+- wait_for_job: every request inside the wait is capped by the time left, so the call really returns within timeout_s (+ a few seconds for the result fetch)
+- create_audio_clip rejects ambiguous input (both voice ids, or a file together with text)
+- image_path / file_path accept ~/ and are documented as absolute paths
+- CRAFTSTORY_API_BASE must be https unless CRAFTSTORY_ALLOW_HTTP=1
+- Node >= 20 (matches the dependency tree); prepack builds; SECURITY.md; GitHub Actions CI
+
+## 0.1.1 - 2026-09-12
+- wait_for_job: default 45 s, max 55 s, deadline-aware polling (stays under the 60 s tool-call limit of most MCP clients)
+- every API request has a 25 s HTTP timeout; network errors report their cause
+- removed an internal repository URL from package metadata (0.1.0 is deprecated for that reason)
+
+## 0.1.0 - 2026-09-12
+- first release: 11 tools over the CraftStory public API (models, voices, avatars, audio clips, cost preview,
+  CraftStory 2.0 and MiniMax H3 generation, status, result, bounded wait, upscale) and one prompt

package/README.md

@@ -5,19 +5,21 @@ Generate talking-avatar videos from Claude, Cursor, Claude Code or any other [MC
 - **CraftStory 2.0** - a talking video of any length from one photo plus an audio clip (script + voice, your own recording, or a custom avatar). 8-15 minutes per video.
 - **MiniMax H3** - a clip of up to 15 s from one photo: description-driven with generated sound, or audio-driven with lip-sync. 1-3 minutes.
 
-You need a CraftStory account on a plan with API access and an API key (app: **Account -> API Access**, keys look like `sk-cs-...`). Generations are billed in credits exactly like in the app; failed jobs are refunded.
+You need Node.js 20 or newer, a CraftStory account on a plan with API access, and an API key (app: **Account -> API Access**, keys look like `sk-cs-...`). Generations are billed in credits exactly like in the app; failed jobs are refunded.
 
 ## Install
 
 ### Claude Code
 
 ```bash
-claude mcp add craftstory -e CRAFTSTORY_API_KEY=sk-cs-... -- npx -y @craftstory/mcp
+claude mcp add --scope user craftstory -e CRAFTSTORY_API_KEY=sk-cs-... -- npx -y @craftstory/mcp
 ```
 
+(`--scope user` makes it available in every project; drop it to install for the current project only.)
+
 ### Claude Desktop
 
-Add to `claude_desktop_config.json` (Settings -> Developer -> Edit Config):
+Add to `claude_desktop_config.json` (Settings -> Developer -> Edit Config), then restart Claude Desktop; the server shows up under the tools icon:
 
 ```json
 {
@@ -33,9 +35,9 @@ Add to `claude_desktop_config.json` (Settings -> Developer -> Edit Config):
 
 ### Cursor / other clients
 
-Same shape in `.cursor/mcp.json` (or the client's MCP config): command `npx`, args `["-y", "@craftstory/mcp"]`, env `CRAFTSTORY_API_KEY`.
+Same shape in `~/.cursor/mcp.json` (user-level, so the key never lands in a repository): command `npx`, args `["-y", "@craftstory/mcp"]`, env `CRAFTSTORY_API_KEY`. In a project-level `.cursor/mcp.json` prefer `"CRAFTSTORY_API_KEY": "${env:CRAFTSTORY_API_KEY}"` and keep the real key in your shell environment.
 
-Environment variables: `CRAFTSTORY_API_KEY` (required), `CRAFTSTORY_API_BASE` (optional, default `https://api.craftstory.com/api/v1`).
+Environment variables: `CRAFTSTORY_API_KEY` (required), `CRAFTSTORY_API_BASE` (optional, default `https://api.craftstory.com/api/v1`; must be https unless `CRAFTSTORY_ALLOW_HTTP=1`).
 
 ## Tools
 
@@ -57,27 +59,37 @@ Plus the prompt `talking_video_from_photo` (script + photo) that walks the model
 
 ## Example
 
-> Make a 15-second portrait video of the person in `~/photos/anna.jpg` saying "Welcome to our spring collection", calm gestures.
+> Make a portrait video of the person in `/Users/me/photos/portrait.jpg` saying "Welcome to our spring collection", calm gestures.
 
 The assistant will: `list_voices` -> `create_audio_clip` -> `wait_for_job(audio-clip)` -> `preview_cost` -> `create_craftstory2_video` (resolution `720_1280`, gestures `calm`) -> `wait_for_job(craftstory-2)` a few times -> `get_job_result` -> the video URL.
 
-Long jobs: `wait_for_job` returns after at most `timeout_s` (max 55 s) plus one in-flight status request (25 s HTTP timeout), which keeps it under the 60 s tool-call limit of most clients in normal conditions. A CraftStory 2.0 video needs several calls; that is by design so agent runtimes do not time out.
+Long jobs: `wait_for_job` returns within `timeout_s` (default 45 s, max 55 s) plus a few seconds for the final result fetch; every request inside it is capped by the time left, so it stays under the 60 s tool-call limit of most clients. A CraftStory 2.0 video needs several calls; that is by design so agent runtimes do not time out. A CraftStory 2.0 video needs several calls; that is by design so agent runtimes do not time out.
 
 ## Local files vs URLs
 
-Photos accept `image_url` or `image_path`; recordings and extra references are local paths (uploaded as multipart). Photos up to 20 MB (JPG/PNG/HEIC), audio WAV/MP3/M4A.
+Photos accept `image_url` (JPG/PNG) or `image_path` (absolute path or `~/...`; JPG/PNG/HEIC, up to 20 MB, uploaded as multipart). Recordings and extra references are local paths too. Anything you pass as a path is uploaded to the CraftStory API, so keep your client's tool-approval prompts on (see SECURITY.md).
 
 ## Development
 
 ```bash
 npm install
 npm run build
-CRAFTSTORY_API_KEY=sk-cs-... npm run smoke       # live check over stdio (add -- --h3 to also render a 5 s H3 clip)
+CRAFTSTORY_API_KEY=sk-cs-... npm run smoke       # live check over stdio: lists tools, makes an audio clip, previews cost
+# add "-- --h3" and SMOKE_IMAGE=/path/to/photo.jpg to also render a 5 s MiniMax H3 clip (costs 17 credits)
 npm test
 ```
 
 Full API reference: https://api.craftstory.com/api/v1/docs/public/ and the curl walkthrough at https://api.craftstory.com/api/v1/docs/samples/curl/.
 
+## Privacy Policy
+
+This server runs on your machine and keeps no data of its own. It sends your API key and the inputs you pass to tools
+(text, photos, audio, reference files) only to the CraftStory API at `CRAFTSTORY_API_BASE` (default
+`https://api.craftstory.com`), where they are processed under the CraftStory privacy policy:
+https://craftstory.com/privacy/. Generated videos and uploaded files are stored in your CraftStory account and can be
+deleted there or via the API; nothing is retained locally by the server. No analytics or third-party services are
+called by the server itself. Questions: support via https://craftstory.com/contacts/.
+
 ## License
 
 MIT

package/dist/client.js

@@ -3,9 +3,10 @@
  * Every method maps 1:1 onto a documented endpoint; no business logic lives here.
  */
 import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { basename } from "node:path";
 export const DEFAULT_BASE = "https://api.craftstory.com/api/v1";
-export const USER_AGENT = "craftstory-mcp/0.1.1";
+export const USER_AGENT = "craftstory-mcp/0.1.3";
 /** Per-request HTTP timeout; keeps every tool call well under MCP clients' ~60 s limit. */
 export const REQUEST_TIMEOUT_MS = 25_000;
 export class ApiError extends Error {
@@ -24,8 +25,9 @@ export async function fileOrUrl(input, field) {
     if (input.url)
         return { url: input.url };
     if (input.path) {
-        const bytes = await readFile(input.path);
-        return { blob: new Blob([bytes]), name: basename(input.path) };
+        const path = input.path.startsWith("~/") ? homedir() + input.path.slice(1) : input.path;
+        const bytes = await readFile(path);
+        return { blob: new Blob([bytes]), name: basename(path) };
     }
     throw new Error(`${field}: a URL or a local file path is required`);
 }
@@ -36,9 +38,14 @@ export class CraftStoryClient {
     constructor(opts) {
         this.opts = opts;
         this.base = (opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
+        // The bearer key and uploads travel to this host: plaintext HTTP only on explicit request.
+        if (!this.base.startsWith("https://") && process.env.CRAFTSTORY_ALLOW_HTTP !== "1") {
+            throw new Error(`CRAFTSTORY_API_BASE must use https:// (got ${this.base}); set CRAFTSTORY_ALLOW_HTTP=1 to override for local testing`);
+        }
         this.fetchImpl = opts.fetchImpl ?? fetch;
     }
-    async request(method, path, body) {
+    /** timeoutMs caps this one request (default REQUEST_TIMEOUT_MS); wait_for_job passes its remaining budget. */
+    async request(method, path, body, timeoutMs = REQUEST_TIMEOUT_MS) {
         const headers = { Authorization: `Bearer ${this.opts.apiKey}`, "User-Agent": USER_AGENT, Accept: "application/json" };
         let payload;
         if (body instanceof FormData)
@@ -49,12 +56,12 @@ export class CraftStoryClient {
         }
         let res;
         try {
-            res = await this.fetchImpl(`${this.base}${path}`, { method, headers, body: payload, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+            res = await this.fetchImpl(`${this.base}${path}`, { method, headers, body: payload, signal: AbortSignal.timeout(Math.max(1000, timeoutMs)) });
         }
         catch (e) {
             // Node's fetch hides the reason behind "fetch failed"; surface the cause (DNS, TLS, reset...).
             if (e.name === "TimeoutError")
-                throw new Error(`Timeout after ${REQUEST_TIMEOUT_MS / 1000}s calling ${method} ${path}`);
+                throw new Error(`Timeout after ${Math.round(Math.max(1000, timeoutMs) / 1000)}s calling ${method} ${path}`);
             const cause = e.cause;
             throw new Error(`Network error calling ${method} ${path}: ${cause?.code ?? ""} ${cause?.message ?? e.message}`.trim());
         }
@@ -70,8 +77,8 @@ export class CraftStoryClient {
             throw new ApiError(res.status, data, describeError(res.status, data));
         return data;
     }
-    get(path) {
-        return this.request("GET", path);
+    get(path, timeoutMs) {
+        return this.request("GET", path, undefined, timeoutMs);
     }
     post(path, body) {
         return this.request("POST", path, body);
@@ -163,11 +170,11 @@ export class CraftStoryClient {
     jobPath(kind, id) {
         return kind === "audio-clip" ? `/audio/clips/${id}/` : `/${kind}/${id}/`;
     }
-    getStatus(kind, id) {
-        return this.get(`${this.jobPath(kind, id)}status/`);
+    getStatus(kind, id, timeoutMs) {
+        return this.get(`${this.jobPath(kind, id)}status/`, timeoutMs);
     }
-    getResult(kind, id) {
-        return this.get(this.jobPath(kind, id));
+    getResult(kind, id, timeoutMs) {
+        return this.get(this.jobPath(kind, id), timeoutMs);
     }
 }
 /** Terminal-state classification shared by wait_for_job and the tool descriptions. */

package/dist/server.js

@@ -14,9 +14,10 @@ const JOB_KINDS = ["craftstory-2", "minimax-h3", "audio-clip"];
 const text = (data) => ({ content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }] });
 const fail = (err) => ({ isError: true, content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }] });
 export function buildServer(client) {
-    const server = new McpServer({ name: "craftstory", version: "0.1.1" });
+    const server = new McpServer({ name: "craftstory", version: "0.1.3" });
     server.registerTool("list_models", {
         title: "List CraftStory video models",
+        annotations: { readOnlyHint: true, openWorldHint: true },
         description: "Catalogue of the video models behind this server with their status, modes, limits and credit prices. " +
             "Two models today: craftstory-2 (a talking video of any length from one photo plus an audio clip; 8-15 min) " +
             "and minimax-h3 (a clip of up to 15 s from one photo, either description-driven with generated sound or audio-driven with lip-sync; 1-3 min). " +
@@ -32,6 +33,7 @@ export function buildServer(client) {
     });
     server.registerTool("list_voices", {
         title: "List voices for text-to-speech",
+        annotations: { readOnlyHint: true, openWorldHint: true },
         description: "Library voices (id, name, language, gender) usable as voice_id in create_audio_clip. " +
             "With include_cloned=true also returns the account's own cloned voices, usable as voice_user_id. Voices are cloned in the CraftStory app, not via the API.",
         inputSchema: { include_cloned: z.boolean().optional().describe("Also return the account's cloned voices (default false)") },
@@ -47,6 +49,7 @@ export function buildServer(client) {
     });
     server.registerTool("list_avatars", {
         title: "List custom avatars (and their scenes)",
+        annotations: { readOnlyHint: true, openWorldHint: true },
         description: "Custom avatars trained in the CraftStory app that craftstory-2 can generate with (pass an id as avatar_id). " +
             "Each avatar may carry a default voice {id, voice_kind}: voice_kind 'user' means send it as voice_user_id, 'library' as voice_id in create_audio_clip. " +
             "Pass avatar_id to list that avatar's scenes; a scene id can replace the photo (scene_id) in create_craftstory2_video.",
@@ -61,6 +64,7 @@ export function buildServer(client) {
     });
     server.registerTool("create_audio_clip", {
         title: "Create an audio clip (speech from text, or upload a recording)",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         description: "The soundtrack every video model takes as input. Either text (up to 2000 characters) plus exactly one voice (voice_id from list_voices, or voice_user_id for a cloned voice), " +
             "or file_path to upload a local WAV/MP3/M4A recording. Returns the clip id; it is ready when wait_for_job(model='audio-clip') reports done (usually seconds). " +
             "Longer scripts: create several clips and pass all ids to create_craftstory2_video in order.",
@@ -72,10 +76,14 @@ export function buildServer(client) {
         },
     }, async ({ text: script, voice_id, voice_user_id, file_path }) => {
         try {
+            if (file_path && (script || voice_id || voice_user_id))
+                throw new Error("Pass either file_path or text + one voice, not both");
             if (file_path)
                 return text(await client.createAudioClipFromFile(file_path));
             if (!script)
                 throw new Error("Pass text (with a voice) or file_path");
+            if (voice_id && voice_user_id)
+                throw new Error("Pass exactly one of voice_id or voice_user_id");
             if (!voice_id && !voice_user_id)
                 throw new Error("Pass voice_id (library voice) or voice_user_id (cloned voice) with text");
             return text(await client.createAudioClipFromText(script, voice_id ? { voice_id } : { voice_user_id }));
@@ -86,6 +94,7 @@ export function buildServer(client) {
     });
     server.registerTool("preview_cost", {
         title: "Estimate the credit cost of a CraftStory 2.0 video",
+        annotations: { readOnlyHint: true, openWorldHint: true },
         description: "Credits a craftstory-2 job would cost for the given audio clips and settings, without creating anything. " +
             "Rate per second of audio: 480p 2.2 (2 with lipsync_mode=empty), 720p 3.3 (3 with empty); rounded up per job. MiniMax H3 is a flat 3.3 credits per billed second.",
         inputSchema: {
@@ -103,13 +112,14 @@ export function buildServer(client) {
     });
     server.registerTool("create_craftstory2_video", {
         title: "Create a CraftStory 2.0 talking video (photo + audio)",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         description: "Start a craftstory-2 generation: a photo of a person (image_url or image_path, or a custom avatar scene via scene_id) speaks the given audio clips with lip-sync, gestures and natural motion; any length. " +
             "resolution is WIDTH_HEIGHT (480_832 / 720_1280 portrait, 832_480 / 1280_720 landscape); 1080p is available afterwards via upscale_video. " +
             "Credits are charged on create (see preview_cost) and refunded if the job fails. Returns the job id and initial status; generation takes 8-15 minutes, " +
             "so call wait_for_job(model='craftstory-2') repeatedly until it reports done, then get_job_result for the video URL.",
         inputSchema: {
             image_url: z.string().url().optional().describe("Public URL of the photo (JPG/PNG)"),
-            image_path: z.string().optional().describe("Local path of the photo to upload (<= 20 MB)"),
+            image_path: z.string().optional().describe("Absolute local path of the photo to upload (JPG/PNG/HEIC, <= 20 MB); ~/ is expanded"),
             scene_id: z.string().uuid().optional().describe("Custom avatar scene id (from list_avatars) used instead of a photo"),
             avatar_id: z.string().uuid().optional().describe("Custom avatar id (from list_avatars); its trained model drives identity"),
             audio_clip_ids: z.array(z.string().uuid()).min(1).describe("Audio clip ids (from create_audio_clip), played in order"),
@@ -144,6 +154,7 @@ export function buildServer(client) {
     });
     server.registerTool("create_minimax_h3_video", {
         title: "Create a MiniMax H3 clip (up to 15 s)",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         description: "Start a minimax-h3 generation from one photo. mode='basic': user_prompt (scene description) + requested_duration_s (5-15); the model animates the photo and generates the soundtrack itself. " +
             "mode='reference': one audio_clip_id drives the clip with lip-sync (first 15 s billed); user_prompt is optional; up to 8 extra image / 3 video / 2 audio reference_files with reference_captions keep a product or background consistent. " +
             "Output is 768 px on the short side, orientation follows the photo. Cost 3.3 credits per billed second, charged on create. Returns the job id; call wait_for_job(model='minimax-h3') until done (1-3 min).",
@@ -184,6 +195,7 @@ export function buildServer(client) {
     });
     server.registerTool("get_job_status", {
         title: "Get a job's status",
+        annotations: { readOnlyHint: true, openWorldHint: true },
         description: "Status of a video job or audio clip: status, status_percentage, status_failed, credits_refunded. Terminal states: done; failed*, rejected_* and not_pass_moderation (audio) are failures. " +
             "Prefer wait_for_job, which polls for you.",
         inputSchema: { model: z.enum(JOB_KINDS), id: z.string().uuid() },
@@ -197,6 +209,7 @@ export function buildServer(client) {
     });
     server.registerTool("get_job_result", {
         title: "Get a finished job (video URL and details)",
+        annotations: { readOnlyHint: true, openWorldHint: true },
         description: "Full record of a job. For craftstory-2 the video is in `video`, for minimax-h3 in `video_url`, for audio clips in `file`; all are signed URLs valid for 7 days (call again for a fresh link). Also returns the parameters used and the credits charged.",
         inputSchema: { model: z.enum(JOB_KINDS), id: z.string().uuid() },
     }, async ({ model, id }) => {
@@ -209,6 +222,7 @@ export function buildServer(client) {
     });
     server.registerTool("wait_for_job", {
         title: "Wait for a job (bounded polling)",
+        annotations: { readOnlyHint: true, openWorldHint: true },
         description: "Polls a job's status every few seconds for up to timeout_s (default 45, max 55 - most MCP clients cut a tool call at 60 s) and returns as soon as it is terminal. " +
             "If it returns state='running', call it again - craftstory-2 jobs take 8-15 minutes, minimax-h3 1-3 minutes, audio clips seconds. Reports progress notifications when the client supports them.",
         inputSchema: {
@@ -220,11 +234,15 @@ export function buildServer(client) {
         const deadline = Date.now() + (timeout_s ?? 45) * 1000;
         const token = extra._meta?.progressToken;
         let last;
+        const running = () => text({ state: "running", ...last, hint: "still running - call wait_for_job again" });
         try {
             while (true) {
-                if (Date.now() >= deadline && last)
-                    return text({ state: "running", ...last, hint: "still running - call wait_for_job again" });
-                last = await client.getStatus(model, id);
+                // Every request is capped by the time left, so the call returns within timeout_s
+                // (plus at most a few seconds for the final result fetch).
+                const budget = deadline - Date.now();
+                if (budget <= 0 && last)
+                    return running();
+                last = await client.getStatus(model, id, Math.min(25_000, Math.max(3_000, budget)));
                 const state = classify(last.status);
                 if (token !== undefined) {
                     await extra.sendNotification({
@@ -233,12 +251,20 @@ export function buildServer(client) {
                     });
                 }
                 if (state !== "running") {
-                    const result = state === "done" ? await client.getResult(model, id) : undefined;
+                    let result;
+                    if (state === "done") {
+                        try {
+                            result = await client.getResult(model, id, Math.min(10_000, Math.max(3_000, deadline - Date.now())));
+                        }
+                        catch {
+                            return text({ state, ...last, hint: "finished - call get_job_result for the video URL" });
+                        }
+                    }
                     return text({ state, ...last, ...(result ? { result } : {}) });
                 }
                 const remaining = deadline - Date.now();
                 if (remaining <= 0)
-                    return text({ state: "running", ...last, hint: "still running - call wait_for_job again" });
+                    return running();
                 await new Promise((r) => setTimeout(r, Math.min(model === "audio-clip" ? 2000 : 5000, remaining)));
             }
         }
@@ -248,6 +274,7 @@ export function buildServer(client) {
     });
     server.registerTool("upscale_video", {
         title: "Upscale a finished video (new job)",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         description: "Creates a NEW job with the upscaled result; the original stays. craftstory-2: only 720p sources, resolution 1080_1920 (from 720_1280) or 1920_1080 (from 1280_720). minimax-h3: always 2x, no resolution needed. " +
             "Costs 0.2 credits per second. Poll the returned id with wait_for_job.",
         inputSchema: {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@craftstory/mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
+  "mcpName": "io.github.itseez3d/craftstory-mcp",
   "description": "MCP server for the CraftStory API: talking-avatar videos from a photo (CraftStory 2.0) and short clips with generated sound (MiniMax H3), from Claude, Cursor and other MCP clients.",
   "type": "module",
   "bin": {
@@ -10,16 +11,18 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
     "start": "node dist/index.js",
     "test": "node --import tsx --test test/*.test.ts",
-    "smoke": "tsx test/smoke.ts"
+    "smoke": "tsx test/smoke.ts",
+    "prepack": "npm run build"
   },
   "keywords": [
     "mcp",
@@ -32,7 +35,7 @@
     "minimax"
   ],
   "license": "MIT",
-  "homepage": "https://craftstory.com",
+  "homepage": "https://github.com/itseez3d/craftstory-mcp#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.24.0"
@@ -43,6 +46,10 @@
     "typescript": "^5.6.0"
   },
   "bugs": {
-    "url": "https://api.craftstory.com/api/v1/docs/public/"
+    "url": "https://github.com/itseez3d/craftstory-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itseez3d/craftstory-mcp.git"
   }
 }