@starreel/mcp 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# @starreel/mcp
+
+StarReel 的 MCP 服务器 —— 把 AI 短剧**编排产线**暴露给 Claude Code / Cursor /
+任何 MCP 客户端:让 AI agent 一句话从**剧本跑到可下载的成片**。
+
+完整接入文档:https://api.shortreelai.com/docs/mcp
+
+## 接入
+
+1. 在 StarReel → 设置 → API Key 创建一把 `produce` scope 的 key(`srk_live_...`,只展示一次)。
+2. Claude Code:
+
+```bash
+claude mcp add starreel -e STARREEL_API_KEY=srk_live_xxx -- npx -y @starreel/mcp
+```
+
+其他 MCP 客户端(Cursor 等)照各自配置格式填 `npx -y @starreel/mcp` + 环境变量即可。
+
+## 产线工具(从剧本到成片)
+
+一集短剧的完整链路,每个花钱阶段先报价、你确认后才执行:
+
+| 阶段 | 工具 |
+|---|---|
+| 建剧 | `create_drama`(建剧壳+自动建集,返回 episode_id) |
+| 灌本 | `set_script` |
+| 拆镜 | `quote_storyboards` → `generate_storyboards` → `get_storyboards`(审阅) |
+| 出首帧 | `quote_frames` → `generate_frames` |
+| 出视频 | `quote_videos` → `generate_videos`(大额,报价与扣费同函数) |
+| 成片 | `compose_episode`(免费终拼) → `get_final_cut`(拿 COS 下载链接) |
+
+**批量报价确认**:每个 `quote_*` 返回预估点数,agent 应把点数告诉你、你同意后才用返回的
+`quote_id` 调 `generate_*`。整集一次执行,不逐图打扰。长任务后台异步,用 `get_storyboards`/
+`get_final_cut` 轮询到完成。
+
+## 计费与安全
+
+- 预付制:必须有余额才能生成,账户**永不为负**;成本在调厂商**之前**预授权,不够返回 402。
+- 视频报价 == 实际扣费(同一函数);终拼(成片)免费。
+- API key 只存哈希;换取的是 15 分钟短期令牌;泄露在设置页吊销即失效,不影响网页登录。
+
+## 环境变量
+
+| 变量 | 必填 | 默认 |
+|---|---|---|
+| `STARREEL_API_KEY` | ✅ | — |
+| `STARREEL_AUTH_BASE` | | `https://api.shortreelai.com` |

package/dist/client.js

@@ -0,0 +1,145 @@
+/**
+ * StarReel API 客户端 —— MCP 工具层与后端之间唯一的 HTTP 通道。
+ *
+ * 鉴权模型:长期 API Key(环境变量,绝不出现在工具参数/返回里)→ 换 15min
+ * 短期 JWT(POST {auth}/v1/agent/token)→ 带 Bearer 调业务 API。token 过期
+ * 或 401 时自动重换一次再重放;重放仍失败则原样抛错(不无限循环)。
+ *
+ * 安全边界:
+ *   - key/token 永不写 stdout(stdio 传输的 JSON-RPC 通道)也不进工具返回值。
+ *   - 返回给模型的下载链接只能是我方 COS 预签名 URL(服务端已保证,这里不转发
+ *     任何厂商直链字段)。
+ */
+import { createReadStream, statSync } from 'node:fs';
+import { Readable } from 'node:stream';
+const AUTH_BASE = process.env.STARREEL_AUTH_BASE ?? 'https://api.shortreelai.com';
+const LOC_BASE = process.env.STARREEL_LOC_BASE ?? 'https://translator.starreel.ai';
+export class StarReelClient {
+    apiKey;
+    token = null;
+    tokenExpiresAt = 0; // epoch ms
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+        if (!apiKey?.startsWith('srk_')) {
+            throw new Error('STARREEL_API_KEY missing or malformed (expected srk_live_...)');
+        }
+    }
+    /** API key → 短期 access token(提前 60s 视为过期,避免边界竞态)。 */
+    async ensureToken() {
+        if (this.token && Date.now() < this.tokenExpiresAt - 60_000)
+            return this.token;
+        const res = await fetch(`${AUTH_BASE}/v1/agent/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ api_key: this.apiKey }),
+        });
+        if (!res.ok) {
+            throw new Error(res.status === 401
+                ? 'API key rejected (revoked or invalid) — create a new key in StarReel settings'
+                : `token exchange failed: HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        this.token = body.data.access_token;
+        this.tokenExpiresAt = Date.now() + body.data.expires_in * 1000;
+        return this.token;
+    }
+    /** 带 Bearer 的 fetch;401 时强制重换 token 重放一次。 */
+    async authedFetch(url, init = {}) {
+        const attempt = async () => {
+            const token = await this.ensureToken();
+            return fetch(url, { ...init, headers: { ...(init.headers ?? {}), authorization: `Bearer ${token}` } });
+        };
+        let res = await attempt();
+        if (res.status === 401) {
+            this.token = null; // 服务端时钟/吊销边界:强制重换一次
+            res = await attempt();
+        }
+        return res;
+    }
+    /** 本地化服务(translator.starreel.ai)的 JSON 调用。 */
+    async loc(path, init = {}) {
+        // 网络层失败(DNS/TLS/超时)与业务 4xx/5xx 分开报——agent 拿到 "fetch failed"
+        // 无从行动;点名服务与建议,它才能正确转述/重试/放弃。
+        let res;
+        try {
+            res = await this.authedFetch(`${LOC_BASE}${path}`, init);
+        }
+        catch (e) {
+            throw new Error(`StarReel localization service unreachable (${LOC_BASE}): ${e?.cause?.code ?? e?.message ?? e}. ` +
+                'The service may be down or your network blocks it — retry later or check with StarReel.');
+        }
+        const text = await res.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = { raw: text.slice(0, 300) };
+        }
+        if (!res.ok)
+            throw new Error(body?.error ?? `HTTP ${res.status} on ${path}`);
+        return body;
+    }
+    locPost(path, body) {
+        return this.loc(path, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    /** 短剧编排产线(网关 /v1/produce/*)。返回 huobao 信封里的 data。 */
+    async produce(path, init = {}) {
+        let res;
+        try {
+            res = await this.authedFetch(`${AUTH_BASE}/v1/produce${path}`, init);
+        }
+        catch (e) {
+            throw new Error(`StarReel production pipeline unreachable (${AUTH_BASE}): ${e?.cause?.code ?? e?.message ?? e}. ` +
+                'Retry later or check with StarReel.');
+        }
+        const text = await res.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = { raw: text.slice(0, 300) };
+        }
+        if (!res.ok)
+            throw new Error(body?.message ?? body?.error ?? `HTTP ${res.status} on ${path}`);
+        return (body?.data ?? body); // huobao 信封 {code,data,message}
+    }
+    produceGet(path) {
+        return this.produce(path, { method: 'GET' });
+    }
+    producePost(path, body) {
+        return this.produce(path, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    producePut(path, body) {
+        return this.produce(path, {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    /**
+     * 把本地文件流式 PUT 到 COS 预签名 URL(字节不经我们任何服务器)。
+     * Content-Length 必带 —— 预签名 PUT 对 chunked 编码不友好。
+     */
+    async uploadFile(uploadUrl, filePath) {
+        const size = statSync(filePath).size;
+        const res = await fetch(uploadUrl, {
+            method: 'PUT',
+            headers: { 'content-length': String(size) },
+            body: Readable.toWeb(createReadStream(filePath)),
+            // Node fetch(undici) 流式请求体必须显式声明半双工
+            duplex: 'half',
+        });
+        if (!res.ok)
+            throw new Error(`upload failed: HTTP ${res.status} (${(await res.text()).slice(0, 200)})`);
+    }
+}

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * StarReel MCP 服务器(stdio 形态)。
+ *
+ * 接入(Claude Code):
+ *   claude mcp add starreel -e STARREEL_API_KEY=srk_live_... -- npx -y @starreel/mcp
+ *
+ * ⚠️ stdio 传输下 stdout 是 JSON-RPC 通道 —— 任何诊断输出只许走 stderr
+ * (console.error),console.log 一次就会把整条会话打坏。
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StarReelClient } from './client.js';
+import { registerProduceTools } from './tools/produce.js';
+const apiKey = process.env.STARREEL_API_KEY;
+if (!apiKey) {
+    console.error('STARREEL_API_KEY is not set.\n' +
+        'Create one in StarReel → Settings → API Keys, then:\n' +
+        '  claude mcp add starreel -e STARREEL_API_KEY=srk_live_... -- npx -y @starreel/mcp');
+    process.exit(1);
+}
+const server = new McpServer({ name: 'starreel', version: '0.1.0' });
+const client = new StarReelClient(apiKey);
+registerProduceTools(server, client); // 短剧编排产线(需 produce scope)——从剧本到成片
+// 出海本地化工具:translator worker 暂时离线(2026-08),发布版先不注册,免得客户拿到只会
+// 报错的工具。worker 重建后取消下一行注释即可(工具代码保留在 tools/localize.ts)。
+// registerLocalizeTools(server, client)
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[starreel-mcp] ready (drama production toolset, stdio)');

package/dist/tools/localize.js

@@ -0,0 +1,91 @@
+/**
+ * 本地化产线三件套工具(v1)。对接 translator.starreel.ai 既有端点,服务端零改动:
+ *   presign(直传 COS)→ 登记 job → batch-process 提交处理 → 轮询状态。
+ *
+ * 工具设计铁律:
+ *   - 卖"结果"不搬 REST:localize_video 一次调用替用户串完 4 个端点。
+ *   - 会扣费的动作在 description 里写明单价来源,让 agent 能向用户转述;
+ *     余额不足时服务端预扣模式会快速失败并退款,这里如实转发错误。
+ *   - 返回结构化 JSON 文本;下载链接是我方 COS 预签名 URL(短时效,过期重查)。
+ */
+import { basename, extname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { z } from 'zod';
+const DEFAULT_SERIES = 'MCP Uploads';
+function jsonResult(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+export function registerLocalizeTools(server, client) {
+    server.tool('localize_video', '把一个中文短剧视频(mp4/mov)做出海本地化:去除中文硬字幕并压制目标语言字幕。' +
+        '上传→登记→提交处理一步完成,返回 job_id;用 get_localization_job 轮询进度' +
+        '(1080p 约 1.25× 实时)。会消耗账户积分(约 65 点/分钟,处理前预扣、失败自动退款)。', {
+        file_path: z.string().describe('本地视频文件绝对路径(.mp4/.mov)'),
+        target_lang: z
+            .enum(['en', 'ja', 'ko', 'es', 'fr', 'vi', 'th', 'id', 'ar'])
+            .describe('目标语言(en=英语 ja=日语 ko=韩语 es=西语 fr=法语 vi=越南语 th=泰语 id=印尼语 ar=阿拉伯语)'),
+        series_name: z.string().max(100).optional()
+            .describe(`归属剧集名(同名复用,默认 "${DEFAULT_SERIES}")`),
+    }, async ({ file_path, target_lang, series_name }) => {
+        if (!existsSync(file_path))
+            throw new Error(`file not found: ${file_path}`);
+        const ext = extname(file_path).toLowerCase();
+        if (ext !== '.mp4' && ext !== '.mov')
+            throw new Error(`unsupported format ${ext} (mp4/mov only)`);
+        // 1) 找/建剧集(batch-process 以剧集为提交单元)
+        const wanted = (series_name ?? DEFAULT_SERIES).trim();
+        const { series } = await client.loc('/api/series');
+        let sid = series.find((s) => s.name === wanted)?.id;
+        if (!sid) {
+            const created = await client.locPost('/api/series', { name: wanted });
+            sid = created.id;
+        }
+        // 2) 预签名 → 浏览器同款直传 COS(字节不经任何 StarReel 服务器)
+        const filename = basename(file_path);
+        const presign = await client.locPost('/api/uploads/presign', { filename });
+        await client.uploadFile(presign.uploadUrl, file_path);
+        // 3) 登记任务 → 4) 提交处理(设语言、转 pending,worker 立即可领)
+        const job = await client.locPost('/api/jobs', {
+            key: presign.key,
+            name: filename,
+            seriesId: sid,
+        });
+        const submitted = await client.locPost(`/api/series/${sid}/batch-process`, { jobIds: [job.id], targetLang: target_lang });
+        if (submitted.submitted !== 1) {
+            throw new Error(`job ${job.id} registered but not submitted — check series ${sid} state`);
+        }
+        return jsonResult({
+            job_id: job.id,
+            series_id: sid,
+            status: 'pending',
+            target_lang,
+            note: 'poll with get_localization_job; processing ≈1.25× realtime',
+        });
+    });
+    server.tool('get_localization_job', '查询一个本地化任务的状态。status=done 时返回成片下载链接(短时效预签名 URL,过期就再查一次拿新链接)。', { job_id: z.number().int().positive().describe('localize_video 返回的 job_id') }, async ({ job_id }) => {
+        const row = await client.loc(`/api/jobs/${job_id}`);
+        if (!row?.id)
+            throw new Error(`job ${job_id} not found`);
+        return jsonResult({
+            job_id: row.id,
+            name: row.name,
+            status: row.status, // uploaded|pending|processing|done|failed
+            stage: row.stage,
+            target_lang: row.target_lang,
+            duration_sec: row.duration_sec,
+            points_charged: row.points,
+            download_url: row.output_url, // 我方 COS 预签名,非厂商直链
+            error: row.error,
+        });
+    });
+    server.tool('list_localization_jobs', '列出我的本地化任务(最近 200 条,可按剧集过滤)。', { series_id: z.number().int().positive().optional() }, async ({ series_id }) => {
+        const q = series_id ? `?seriesId=${series_id}` : '';
+        const { jobs } = await client.loc(`/api/jobs${q}`);
+        return jsonResult({
+            count: jobs.length,
+            jobs: jobs.map((r) => ({
+                job_id: r.id, name: r.name, status: r.status, stage: r.stage,
+                target_lang: r.target_lang, points: r.points, created_at: r.created_at,
+            })),
+        });
+    });
+}

package/dist/tools/produce.js

@@ -0,0 +1,51 @@
+/**
+ * 短剧编排产线工具集(P2)。对接网关 /v1/produce/*(门面),把
+ * 「建剧 → 灌本 → 拆镜 → 出帧 → 出视频 → 成片」整条产线包成 agent 可调的工具。
+ *
+ * 设计铁律 —— 批量报价确认(人在环):
+ *   每个花钱阶段拆成 quote_* + generate_*。agent **必须**先调 quote_*,把预估点数
+ *   原样告诉用户,等用户确认后才调 generate_*(带 quote_id)。绝不擅自确认——报价可能
+ *   是上万点的视频。generate_* 是**批量**执行(整集一次),不是一图一图,别循环逐条确认。
+ *
+ * 长任务(拆镜/出帧/出视频/成片)都是后台异步:generate_* 立即返回 status:'generating',
+ * 用 get_storyboards / get_episode_status 轮询到完成。下载链接只发我方 COS 链接。
+ */
+import { z } from 'zod';
+function jsonResult(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+const CONFIRM_HINT = '⚠️ 批量报价确认流程:先调对应的 quote_* 工具,把返回的 estimated_points 原样告诉用户,' +
+    '用户明确同意后,才用返回的 quote_id 调本工具。不要擅自确认。';
+export function registerProduceTools(server, client) {
+    // ---------- 建剧 ----------
+    server.tool('create_drama', '新建一部短剧(剧壳)。按 total_episodes 自动建对应数量的空集,返回 drama_id 与各集 episode_id。免费。', {
+        title: z.string().describe('剧名'),
+        total_episodes: z.number().int().min(1).max(200).optional().describe('集数(默认 1),自动建 N 个空集'),
+        genre: z.string().optional().describe('题材,如 都市/悬疑/古装'),
+        style: z.string().optional().describe('风格描述'),
+        description: z.string().optional(),
+    }, async (args) => jsonResult(await client.producePost('/dramas', args)));
+    // ---------- 灌本 ----------
+    server.tool('set_script', '给某一集设置可拍剧本文本(拆镜的输入)。免费。', {
+        episode_id: z.number().int().positive(),
+        script: z.string().min(1).describe('该集的完整剧本文本'),
+    }, async ({ episode_id, script }) => jsonResult(await client.producePut(`/episodes/${episode_id}/script`, { script_content: script })));
+    // ---------- 拆镜(storyboards) ----------
+    server.tool('quote_storyboards', '报价:把某一集的剧本拆成分镜(storyboards)要多少点。返回 estimated_points 与 quote_id。零扣费。' +
+        '拿到后把点数告诉用户征求同意,再用 quote_id 调 generate_storyboards。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/quote`)));
+    server.tool('generate_storyboards', '确认后拆镜:后台跑(分钟级),立即返回 status:generating。用 get_storyboards 轮询,分镜出现即在生成、数量稳定即完成。' + CONFIRM_HINT, { episode_id: z.number().int().positive(), quote_id: z.string().describe('来自 quote_storyboards') }, async ({ episode_id, quote_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/storyboards/generate`, { quote_id })));
+    server.tool('get_storyboards', '读某一集的分镜列表(供审阅/查进度)。含每镜首帧(first_frame_image)与视频(video_url)是否就绪。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/storyboards`)));
+    // ---------- 出首帧(frames) ----------
+    server.tool('quote_frames', '报价:给某一集缺首帧的分镜批量出首帧要多少点。返回 frames_to_generate、estimated_points、quote_id。零扣费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/frames/quote`)));
+    server.tool('generate_frames', '确认后批量出首帧:后台异步。用 get_storyboards 轮询,first_frame_image 逐镜填充即完成。' +
+        '出视频前必须先出帧,否则视频会退化成无一致性锚点的画面。' + CONFIRM_HINT, { episode_id: z.number().int().positive(), quote_id: z.string().describe('来自 quote_frames') }, async ({ episode_id, quote_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/frames/generate`, { quote_id })));
+    // ---------- 出视频(videos,大额) ----------
+    server.tool('quote_videos', '报价:给某一集所有分镜批量出视频要多少点(与实际扣费同函数,较准)。返回 estimated_points、quote_id。零扣费。' +
+        '⚠️ 视频是大额花费,务必把点数清楚告诉用户并等其确认。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/videos/quote`)));
+    server.tool('generate_videos', '确认后批量出视频:一条后台链跑完整集,余额不足会自动中止整链(防重复扣)。' +
+        '要求本集已出首帧(未出会被拒)。用 get_storyboards 轮询 video_url 逐镜填充即完成。' + CONFIRM_HINT, { episode_id: z.number().int().positive(), quote_id: z.string().describe('来自 quote_videos') }, async ({ episode_id, quote_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/videos/generate`, { quote_id })));
+    // ---------- 成片(compose/终拼) ----------
+    server.tool('compose_episode', '把某一集所有镜头视频拼成一条成片(终拼)。**免费**(纯拼接,无需报价确认),后台异步。' +
+        '要求本集至少有一个镜有视频;部分就绪会拼出部分成片并在返回里标 partial。发起后用 get_final_cut 轮询。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/compose`)));
+    server.tool('get_final_cut', '查某一集成片状态与下载链接。status=completed 时返回 download_url(我方 COS 直链,可直接下载)。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/final-cut`)));
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@starreel/mcp",
+  "version": "0.1.0",
+  "description": "StarReel MCP server — AI short-drama production & localization tools for Claude, Cursor, and any MCP client",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "starreel-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "starreel",
+    "video",
+    "localization",
+    "short-drama"
+  ]
+}

package/server.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+  "name": "ai.starreel/starreel",
+  "description": "AI short-drama production pipeline: turn a script into a finished, downloadable episode — create drama, break into storyboards, generate frames and videos, and compose the final cut, all with batch quote/confirm billing.",
+  "version": "0.1.0",
+  "websiteUrl": "https://starreel.ai",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@starreel/mcp",
+      "version": "0.1.0",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        {
+          "name": "STARREEL_API_KEY",
+          "description": "StarReel API key (create in Settings → API Keys)",
+          "isRequired": true,
+          "isSecret": true
+        }
+      ]
+    }
+  ]
+}