@craftstory/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 itSeez3D / CraftStory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# CraftStory MCP server
+
+Generate talking-avatar videos from Claude, Cursor, Claude Code or any other [MCP](https://modelcontextprotocol.io) client, using the [CraftStory](https://craftstory.com) API:
+
+- **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.
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add craftstory -e CRAFTSTORY_API_KEY=sk-cs-... -- npx -y @craftstory/mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings -> Developer -> Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "craftstory": {
+      "command": "npx",
+      "args": ["-y", "@craftstory/mcp"],
+      "env": { "CRAFTSTORY_API_KEY": "sk-cs-..." }
+    }
+  }
+}
+```
+
+### 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`.
+
+Environment variables: `CRAFTSTORY_API_KEY` (required), `CRAFTSTORY_API_BASE` (optional, default `https://api.craftstory.com/api/v1`).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_models` | Models, status (a paused model answers 503), limits and prices |
+| `list_voices` | Library voices; `include_cloned` adds your cloned voices |
+| `list_avatars` | Your custom avatars, or the scenes of one avatar |
+| `create_audio_clip` | Speech from text + voice, or upload a local recording |
+| `preview_cost` | Credit estimate for a CraftStory 2.0 video |
+| `create_craftstory2_video` | Start a CraftStory 2.0 job (photo or avatar scene + audio clips) |
+| `create_minimax_h3_video` | Start a MiniMax H3 job (basic or reference mode) |
+| `get_job_status` | Status, percentage, failure reason, refund flag |
+| `get_job_result` | Full record with the signed video URL (valid 7 days) |
+| `wait_for_job` | Bounded polling (default 45 s, max 55 s); call again while `state` is `running` |
+| `upscale_video` | New job with the upscaled result (CraftStory 2.0 720p -> 1080p, H3 2x) |
+
+Plus the prompt `talking_video_from_photo` (script + photo) that walks the model through the whole flow.
+
+## Example
+
+> Make a 15-second portrait video of the person in `~/photos/anna.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.
+
+## 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.
+
+## 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)
+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/.
+
+## License
+
+MIT

package/dist/client.js

@@ -0,0 +1,199 @@
+/**
+ * Thin HTTP client for the CraftStory public API (https://api.craftstory.com/api/v1/docs/public/).
+ * Every method maps 1:1 onto a documented endpoint; no business logic lives here.
+ */
+import { readFile } from "node:fs/promises";
+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 class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}
+/** A file-or-URL input as the API accepts it: a URL string, or a local path that is uploaded. */
+export async function fileOrUrl(input, field) {
+    if (input.url && input.path)
+        throw new Error(`${field}: pass either a URL or a local path, not both`);
+    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) };
+    }
+    throw new Error(`${field}: a URL or a local file path is required`);
+}
+export class CraftStoryClient {
+    opts;
+    base;
+    fetchImpl;
+    constructor(opts) {
+        this.opts = opts;
+        this.base = (opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    async request(method, path, body) {
+        const headers = { Authorization: `Bearer ${this.opts.apiKey}`, "User-Agent": USER_AGENT, Accept: "application/json" };
+        let payload;
+        if (body instanceof FormData)
+            payload = body;
+        else if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            payload = JSON.stringify(body);
+        }
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.base}${path}`, { method, headers, body: payload });
+        }
+        catch (e) {
+            // Node's fetch hides the reason behind "fetch failed"; surface the cause (DNS, TLS, reset...).
+            const cause = e.cause;
+            throw new Error(`Network error calling ${method} ${path}: ${cause?.code ?? ""} ${cause?.message ?? e.message}`.trim());
+        }
+        const text = await res.text();
+        let data = text;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            /* non-JSON body (e.g. 502 page) stays as text */
+        }
+        if (!res.ok)
+            throw new ApiError(res.status, data, describeError(res.status, data));
+        return data;
+    }
+    get(path) {
+        return this.request("GET", path);
+    }
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    // ---- catalogue -------------------------------------------------------
+    listModels() {
+        return this.get("/models/");
+    }
+    listVoices() {
+        return this.get("/craftstory-2/voices/");
+    }
+    listUserVoices() {
+        return this.get("/craftstory-2/user-voices/");
+    }
+    listAvatars() {
+        return this.get("/craftstory-2/avatars/");
+    }
+    listAvatarScenes(avatarId) {
+        return this.get(`/craftstory-2/avatars/${avatarId}/scenes/`);
+    }
+    // ---- audio clips -----------------------------------------------------
+    createAudioClipFromText(text, voice) {
+        return this.post("/audio/clips/", { text, ...voice });
+    }
+    async createAudioClipFromFile(path) {
+        const fd = new FormData();
+        const { blob, name } = await fileOrUrl({ path }, "file");
+        fd.append("file", blob, name);
+        return this.post("/audio/clips/", fd);
+    }
+    // ---- CraftStory 2.0 --------------------------------------------------
+    previewCost(body) {
+        return this.post("/craftstory-2/preview-cost/", body);
+    }
+    async createCraftStory2(args) {
+        const fd = new FormData();
+        if (args.image?.url || args.image?.path) {
+            const img = await fileOrUrl(args.image, "image");
+            if (img.url)
+                fd.append("image", img.url);
+            else
+                fd.append("image", img.blob, img.name);
+        }
+        for (const a of args.audios)
+            fd.append("audios", a);
+        fd.append("resolution", args.resolution);
+        for (const k of ["scene_id", "avatar_id", "gestures", "lipsync_mode", "user_prompt", "name"]) {
+            const v = args[k];
+            if (v !== undefined && v !== "")
+                fd.append(k, String(v));
+        }
+        if (args.faceswap !== undefined)
+            fd.append("faceswap", args.faceswap ? "true" : "false");
+        return this.post("/craftstory-2/", fd);
+    }
+    upscaleCraftStory2(id, resolution) {
+        return this.post(`/craftstory-2/${id}/upscale/`, { resolution });
+    }
+    // ---- MiniMax H3 ------------------------------------------------------
+    async createMiniMaxH3(args) {
+        const fd = new FormData();
+        const img = await fileOrUrl(args.image, "image");
+        if (img.url)
+            fd.append("image", img.url);
+        else
+            fd.append("image", img.blob, img.name);
+        if (args.user_prompt)
+            fd.append("user_prompt", args.user_prompt);
+        if (args.name)
+            fd.append("name", args.name);
+        if (args.mode === "basic") {
+            fd.append("requested_duration_s", String(args.requested_duration_s ?? 8));
+            return this.post("/minimax-h3/", fd);
+        }
+        for (const a of args.audios ?? [])
+            fd.append("audios", a);
+        const captions = args.reference_captions ?? [];
+        for (const [i, p] of (args.reference_files ?? []).entries()) {
+            const f = await fileOrUrl({ path: p }, "reference_files");
+            fd.append("reference_files", f.blob, f.name);
+            fd.append("reference_captions", captions[i] ?? "");
+        }
+        return this.post("/minimax-h3/reference/", fd);
+    }
+    upscaleMiniMaxH3(id) {
+        return this.post(`/minimax-h3/${id}/upscale/`);
+    }
+    // ---- generic job access ---------------------------------------------
+    jobPath(kind, id) {
+        return kind === "audio-clip" ? `/audio/clips/${id}/` : `/${kind}/${id}/`;
+    }
+    getStatus(kind, id) {
+        return this.get(`${this.jobPath(kind, id)}status/`);
+    }
+    getResult(kind, id) {
+        return this.get(this.jobPath(kind, id));
+    }
+}
+/** Terminal-state classification shared by wait_for_job and the tool descriptions. */
+export function classify(status) {
+    if (status === "done")
+        return "done";
+    if (status.startsWith("failed") || status.startsWith("rejected_") || status === "not_pass_moderation")
+        return "failed";
+    return "running";
+}
+function describeError(status, body) {
+    if (status === 401)
+        return `401 Unauthorized: ${flatten(body)} (check CRAFTSTORY_API_KEY and that the plan includes API access)`;
+    if (status === 402 || (status === 400 && JSON.stringify(body).includes("Low credits")))
+        return `Low credits: ${flatten(body)}`;
+    if (status === 503)
+        return `503: the model is paused right now (see list_models); retry later`;
+    return `HTTP ${status}: ${flatten(body)}`;
+}
+function flatten(body) {
+    if (body == null)
+        return "";
+    if (typeof body === "string")
+        return body.slice(0, 300);
+    if (Array.isArray(body))
+        return body.map(flatten).join("; ");
+    if (typeof body === "object") {
+        return Object.entries(body)
+            .map(([k, v]) => `${k}: ${flatten(v)}`)
+            .join("; ");
+    }
+    return String(body);
+}

package/dist/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/** CraftStory MCP server over stdio. Configuration comes from the environment:
+ *  CRAFTSTORY_API_KEY  - required, an sk-cs-... key from Account -> API Access
+ *  CRAFTSTORY_API_BASE - optional, defaults to https://api.craftstory.com/api/v1
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CraftStoryClient, DEFAULT_BASE } from "./client.js";
+import { buildServer } from "./server.js";
+const apiKey = process.env.CRAFTSTORY_API_KEY;
+if (!apiKey) {
+    console.error("craftstory-mcp: set CRAFTSTORY_API_KEY (create a key in the CraftStory app: Account -> API Access)");
+    process.exit(1);
+}
+const client = new CraftStoryClient({ apiKey, baseUrl: process.env.CRAFTSTORY_API_BASE ?? DEFAULT_BASE });
+const server = buildServer(client);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/server.js

@@ -0,0 +1,289 @@
+/**
+ * MCP server definition: every tool is a thin, documented wrapper over one
+ * CraftStory public API call. Long generations (CraftStory 2.0: 8-15 min,
+ * MiniMax H3: 1-3 min) return a job id immediately; `wait_for_job` polls in
+ * bounded slices so agent runtimes never hang on a single call.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { classify } from "./client.js";
+const RESOLUTIONS = ["480_832", "832_480", "720_1280", "1280_720"];
+const GESTURES = ["normal", "calm", "expressive"];
+const LIPSYNC = ["craftstory", "sync_so", "empty"];
+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" });
+    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. " +
+            "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). " +
+            "Call this first when unsure which model fits, or to check that a model is not paused.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            return text(await client.listModels());
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("list_voices", {
+        title: "List voices for text-to-speech",
+        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)") },
+    }, async ({ include_cloned }) => {
+        try {
+            const library = await client.listVoices();
+            const cloned = include_cloned ? await client.listUserVoices() : undefined;
+            return text(cloned ? { library, cloned } : { library });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("list_avatars", {
+        title: "List custom avatars (and their scenes)",
+        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.",
+        inputSchema: { avatar_id: z.string().uuid().optional().describe("Return the scenes of this avatar instead of the avatar list") },
+    }, async ({ avatar_id }) => {
+        try {
+            return text(avatar_id ? await client.listAvatarScenes(avatar_id) : await client.listAvatars());
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("create_audio_clip", {
+        title: "Create an audio clip (speech from text, or upload a recording)",
+        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.",
+        inputSchema: {
+            text: z.string().max(2000).optional().describe("Script to synthesize (<= 2000 chars)"),
+            voice_id: z.string().uuid().optional().describe("Library voice id (from list_voices)"),
+            voice_user_id: z.string().uuid().optional().describe("Cloned voice id (from list_voices with include_cloned)"),
+            file_path: z.string().optional().describe("Local path of a recording to upload instead of text"),
+        },
+    }, async ({ text: script, voice_id, voice_user_id, file_path }) => {
+        try {
+            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 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 }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("preview_cost", {
+        title: "Estimate the credit cost of a CraftStory 2.0 video",
+        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: {
+            audio_clip_ids: z.array(z.string().uuid()).min(1),
+            resolution: z.enum(RESOLUTIONS),
+            lipsync_mode: z.enum(LIPSYNC).optional(),
+        },
+    }, async ({ audio_clip_ids, resolution, lipsync_mode }) => {
+        try {
+            return text(await client.previewCost({ audios: audio_clip_ids, resolution, lipsync_mode }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("create_craftstory2_video", {
+        title: "Create a CraftStory 2.0 talking video (photo + audio)",
+        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)"),
+            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"),
+            resolution: z.enum(RESOLUTIONS),
+            gestures: z.enum(GESTURES).optional().describe("How much the avatar moves (default normal)"),
+            lipsync_mode: z.enum(LIPSYNC).optional().describe("craftstory (default) / sync_so (alternative engine) / empty (no lip-sync)"),
+            user_prompt: z.string().max(1000).optional().describe("Optional motion / scene hint"),
+            faceswap: z.boolean().optional().describe("Identity pass on the result (default true; off for custom avatars)"),
+            name: z.string().optional().describe("Label, used as the download file name"),
+        },
+    }, async (a) => {
+        try {
+            if (!a.image_url && !a.image_path && !a.scene_id)
+                throw new Error("Pass image_url, image_path or scene_id");
+            const r = await client.createCraftStory2({
+                image: { url: a.image_url, path: a.image_path },
+                scene_id: a.scene_id,
+                avatar_id: a.avatar_id,
+                audios: a.audio_clip_ids,
+                resolution: a.resolution,
+                gestures: a.gestures,
+                lipsync_mode: a.lipsync_mode,
+                user_prompt: a.user_prompt,
+                faceswap: a.faceswap,
+                name: a.name,
+            });
+            return text({ id: r.id, status: r.status, credits: r.credits, next: "wait_for_job(model='craftstory-2', id=...) until done (8-15 min), then get_job_result" });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("create_minimax_h3_video", {
+        title: "Create a MiniMax H3 clip (up to 15 s)",
+        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).",
+        inputSchema: {
+            mode: z.enum(["basic", "reference"]),
+            image_url: z.string().url().optional(),
+            image_path: z.string().optional(),
+            user_prompt: z.string().optional().describe("Scene / motion description (required in basic mode)"),
+            requested_duration_s: z.number().int().min(5).max(15).optional().describe("Clip length in basic mode (default 8)"),
+            audio_clip_id: z.string().uuid().optional().describe("Reference mode: the clip that drives the video"),
+            reference_files: z.array(z.string()).optional().describe("Reference mode: local paths of extra reference images/videos/audio"),
+            reference_captions: z.array(z.string()).optional().describe("One caption per reference file, same order"),
+            name: z.string().optional(),
+        },
+    }, async (a) => {
+        try {
+            if (!a.image_url && !a.image_path)
+                throw new Error("Pass image_url or image_path");
+            if (a.mode === "basic" && !a.user_prompt)
+                throw new Error("basic mode needs user_prompt");
+            if (a.mode === "reference" && !a.audio_clip_id)
+                throw new Error("reference mode needs audio_clip_id");
+            const r = await client.createMiniMaxH3({
+                mode: a.mode,
+                image: { url: a.image_url, path: a.image_path },
+                user_prompt: a.user_prompt,
+                requested_duration_s: a.requested_duration_s,
+                audios: a.audio_clip_id ? [a.audio_clip_id] : undefined,
+                reference_files: a.reference_files,
+                reference_captions: a.reference_captions,
+                name: a.name,
+            });
+            return text({ id: r.id, status: r.status, credits: r.credits, next: "wait_for_job(model='minimax-h3', id=...) until done (1-3 min), then get_job_result" });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_job_status", {
+        title: "Get a job's status",
+        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() },
+    }, async ({ model, id }) => {
+        try {
+            return text(await client.getStatus(model, id));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_job_result", {
+        title: "Get a finished job (video URL and details)",
+        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 }) => {
+        try {
+            return text(await client.getResult(model, id));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("wait_for_job", {
+        title: "Wait for a job (bounded polling)",
+        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: {
+            model: z.enum(JOB_KINDS),
+            id: z.string().uuid(),
+            timeout_s: z.number().int().min(5).max(55).optional().describe("How long this call may wait (default 45, max 55)"),
+        },
+    }, async ({ model, id, timeout_s }, extra) => {
+        const deadline = Date.now() + (timeout_s ?? 45) * 1000;
+        const token = extra._meta?.progressToken;
+        let last;
+        try {
+            while (true) {
+                last = await client.getStatus(model, id);
+                const state = classify(last.status);
+                if (token !== undefined) {
+                    await extra.sendNotification({
+                        method: "notifications/progress",
+                        params: { progressToken: token, progress: last.status_percentage ?? 0, total: 100, message: last.status },
+                    });
+                }
+                if (state !== "running") {
+                    const result = state === "done" ? await client.getResult(model, id) : undefined;
+                    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));
+            }
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("upscale_video", {
+        title: "Upscale a finished video (new job)",
+        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: {
+            model: z.enum(["craftstory-2", "minimax-h3"]),
+            id: z.string().uuid(),
+            resolution: z.enum(["1080_1920", "1920_1080"]).optional().describe("craftstory-2 only"),
+        },
+    }, async ({ model, id, resolution }) => {
+        try {
+            if (model === "craftstory-2") {
+                if (!resolution)
+                    throw new Error("craftstory-2 upscale needs resolution 1080_1920 or 1920_1080");
+                const r = await client.upscaleCraftStory2(id, resolution);
+                return text({ id: r.id, status: r.status, credits: r.credits });
+            }
+            const r = await client.upscaleMiniMaxH3(id);
+            return text({ id: r.id, status: r.status, credits: r.credits });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerPrompt("talking_video_from_photo", {
+        title: "Talking video from a photo",
+        description: "Step-by-step recipe: script -> voice -> audio clip -> CraftStory 2.0 video -> download.",
+        argsSchema: { script: z.string().describe("What the person should say"), photo: z.string().describe("Photo URL or local path") },
+    }, ({ script, photo }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Make a talking video of the person in ${photo} saying: "${script}".\n` +
+                        "1) list_voices and pick a fitting voice. 2) create_audio_clip with the script and that voice; wait_for_job(model='audio-clip') until done. " +
+                        "3) preview_cost, then create_craftstory2_video with the clip id, the photo and resolution 720_1280 (portrait) or 1280_720 (landscape). " +
+                        "4) wait_for_job(model='craftstory-2') repeatedly until done (8-15 minutes). 5) get_job_result and give me the video URL.",
+                },
+            },
+        ],
+    }));
+    return server;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@craftstory/mcp",
+  "version": "0.1.0",
+  "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" },
+  "main": "dist/index.js",
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "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"
+  },
+  "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",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}