@craftstory/mcp 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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)

package/README.md

@@ -81,6 +81,15 @@ 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

@@ -6,7 +6,7 @@ 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.2";
+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 {

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.2" });
+    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.",
@@ -90,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: {
@@ -107,6 +112,7 @@ 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, " +
@@ -148,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).",
@@ -188,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() },
@@ -201,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 }) => {
@@ -213,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: {
@@ -264,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.2",
+  "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": {