@craftstory/mcp 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 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,22 +59,23 @@ 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` never blocks longer than `timeout_s` (max 55 s, 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.
+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
 ```
 

package/dist/client.js

@@ -3,9 +3,12 @@
  * 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.0";
+export const USER_AGENT = "craftstory-mcp/0.1.2";
+/** 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 {
     status;
     body;
@@ -22,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`);
 }
@@ -34,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)
@@ -47,10 +56,12 @@ export class CraftStoryClient {
         }
         let res;
         try {
-            res = await this.fetchImpl(`${this.base}${path}`, { method, headers, body: payload });
+            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 ${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());
         }
@@ -66,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);
@@ -159,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,7 +14,7 @@ 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.0" });
+    const server = new McpServer({ name: "craftstory", version: "0.1.2" });
     server.registerTool("list_models", {
         title: "List CraftStory video models",
         description: "Catalogue of the video models behind this server with their status, modes, limits and credit prices. " +
@@ -72,10 +72,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 }));
@@ -109,7 +113,7 @@ export function buildServer(client) {
             "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"),
@@ -220,9 +224,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) {
-                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({
@@ -231,12 +241,21 @@ 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 } : {}) });
                 }
-                if (Date.now() >= deadline)
-                    return text({ state: "running", ...last, hint: "still running - call wait_for_job again" });
-                await new Promise((r) => setTimeout(r, model === "audio-clip" ? 2000 : 5000));
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    return running();
+                await new Promise((r) => setTimeout(r, Math.min(model === "audio-clip" ? 2000 : 5000, remaining)));
             }
         }
         catch (e) {

package/package.json

@@ -1,22 +1,40 @@
 {
   "name": "@craftstory/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": { "craftstory-mcp": "dist/index.js" },
+  "bin": {
+    "craftstory-mcp": "dist/index.js"
+  },
   "main": "dist/index.js",
-  "files": ["dist", "README.md", "LICENSE"],
-  "engines": { "node": ">=18" },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "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", "model-context-protocol", "craftstory", "ai-video", "talking-avatar", "lip-sync", "text-to-video", "minimax"],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "craftstory",
+    "ai-video",
+    "talking-avatar",
+    "lip-sync",
+    "text-to-video",
+    "minimax"
+  ],
   "license": "MIT",
-  "repository": { "type": "git", "url": "https://gitlab.itseez3d.com/craftstory/craftstory-mcp" },
-  "homepage": "https://craftstory.com",
+  "homepage": "https://github.com/itseez3d/craftstory-mcp#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.24.0"
@@ -25,5 +43,12 @@
     "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0"
+  },
+  "bugs": {
+    "url": "https://github.com/itseez3d/craftstory-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itseez3d/craftstory-mcp.git"
   }
 }