@starreel/mcp 0.1.36 → 0.1.38

package/dist/client.js

@@ -13,6 +13,7 @@
 import { createReadStream, statSync } from 'node:fs';
 import { basename } from 'node:path';
 import { Readable } from 'node:stream';
+import { assertSafeLocalMediaPath } from './path-guard.js'; // v0.1.37 — P0③ 路径安全闸
 /** 扩展名 → MIME(presign 需要 content_type)。 */
 const MIME_BY_EXT = {
     '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.webp': 'image/webp',
@@ -159,6 +160,9 @@ export class StarReelClient {
      * 字节不经我们的业务服务器,只走 COS。kind: image(默认)/video/audio。
      */
     async uploadLocalFile(filePath, kind = 'image') {
+        // v0.1.37 — P0③:媒体扩展名白名单 + 隐藏/系统目录拒绝(realpath 后判,防符号链接绕过)。
+        const safePath = assertSafeLocalMediaPath(filePath, kind);
+        filePath = safePath;
         const size = statSync(filePath).size;
         const filename = basename(filePath);
         const ext = (filename.match(/\.[a-z0-9]+$/i)?.[0] || '').toLowerCase();

package/dist/path-guard.js

@@ -0,0 +1,45 @@
+/**
+ * v0.1.37 — 本地文件上传的路径安全闸（安全评估 P0③）。
+ *
+ * uploadLocalFile 此前接受任意绝对路径：一个被注入的第三方 agent 可以把
+ * ~/.ssh/id_rsa、.env、浏览器资料库当"素材"上传到 COS（公共可读 URL）。
+ * 本闸不引入 workspace 概念（MCP 进程不知道调用方的工作目录语义），
+ * 而是用两条与"上传媒体素材"这一合法用途严格对齐的规则：
+ *   ① 扩展名必须是对应 kind 的媒体白名单（.env/.pem/id_rsa 天然出局）；
+ *   ② realpath 后的路径中不得含任何以 '.' 开头的路径段（~/.ssh、~/.codex、
+ *      ~/.aws、.git 等敏感目录全部命中），也不得落在系统配置区（/etc、/private/etc）。
+ * 符号链接先解析再判（防 media.jpg -> ~/.ssh/id_rsa 绕过）。
+ */
+import { realpathSync } from 'node:fs';
+import { sep } from 'node:path';
+export const MEDIA_EXT_BY_KIND = {
+    image: new Set(['.jpg', '.jpeg', '.png', '.webp', '.gif']),
+    video: new Set(['.mp4', '.mov', '.webm', '.m4v']),
+    audio: new Set(['.mp3', '.wav', '.m4a', '.aac', '.flac', '.ogg']),
+};
+const SYSTEM_PREFIXES = ['/etc/', '/private/etc/', '/proc/', '/sys/'];
+/** 校验通过返回解析后的真实路径；不通过抛 Error（消息面向第三方 agent，说清正路）。 */
+export function assertSafeLocalMediaPath(filePath, kind, resolve = realpathSync) {
+    const ext = (filePath.match(/\.[a-z0-9]+$/i)?.[0] || '').toLowerCase();
+    if (!MEDIA_EXT_BY_KIND[kind].has(ext)) {
+        throw new Error(`file_path 只接受${kind === 'image' ? '图片' : kind === 'video' ? '视频' : '音频'}媒体文件`
+            + `(${[...MEDIA_EXT_BY_KIND[kind]].join('/')});收到 "${ext || '无扩展名'}"。`
+            + '不要用本工具上传配置/密钥/文档类文件。');
+    }
+    let real;
+    try {
+        real = resolve(filePath);
+    }
+    catch {
+        throw new Error(`file_path 不存在或不可读:${filePath}`);
+    }
+    const segments = real.split(sep);
+    if (segments.some(s => s.startsWith('.') && s.length > 1)) {
+        throw new Error(`file_path 位于隐藏目录(${real}),已拒绝——敏感目录(如 ~/.ssh、~/.aws、.git)不允许作为上传源。`
+            + '把素材放到普通目录再上传。');
+    }
+    if (SYSTEM_PREFIXES.some(p => real.startsWith(p))) {
+        throw new Error(`file_path 位于系统目录(${real}),已拒绝。`);
+    }
+    return real;
+}

package/dist/tools/produce.js

@@ -189,7 +189,9 @@ export function registerProduceTools(server, client) {
     // ---------- 设定图(镜头一致性根锚·批量 / 一键) ----------
     server.tool('generate_character_sheets', '★批量给全剧角色出设定图(多视角 turnaround)。设定图是镜头帧/视频引用的**一致性根锚**——只出定妆图不出设定图,' +
         '镜头人物换角度/换光/服装会漂移(2.5 更直接用设定图切片做骨相锚)。只对缺设定图的角色出(不重复扣费)。' +
-        '前置:角色须已有定妆图(缺则拦并提示先出定妆图)。图片步,按用量后付不欠费。轮询 get_characters 看 sheet_url 就绪。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/character-sheets`)));
+        '前置:角色须已有定妆图(缺则拦并提示先出定妆图)。图片步,按用量后付不欠费。轮询 get_characters 看 sheet_status:' +
+        'pending=生成/审计中(设定图约 2~4 分钟,别重复点);ready=入库;**rejected=图已出但被一致性闸拒收**,' +
+        '读 sheet_fail_hint 拒收判词——可重掷一次,连拒理由相同则是锚字段与人物档案冲突,先 run_precheck 再重掷。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/character-sheets`)));
     server.tool('generate_portraits_and_sheets', '★一键:定妆图 + 设定图(推荐,产线标配)。设定图强依赖定妆图,故智能两阶段——有角色缺定妆图就先派定妆图并提示,' +
         '定妆图齐了再调一次即批量出设定图。避免只出定妆图导致镜头漂移。图片步,按用量后付不欠费。' +
         '轮询 get_characters 看 image/sheet_url 就绪;每调一次推进一步。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/portraits-and-sheets`)));
@@ -488,7 +490,12 @@ export function registerProduceTools(server, client) {
     // ========== P1 · 读取层(闭环必需:能读回自己建的东西)==========
     server.tool('list_dramas', '列出我名下的所有短剧(drama_id/剧名/类型/集数/进度)。免费。', {}, async () => jsonResult(await client.produceGet('/dramas')));
     server.tool('get_drama', '读一部剧的详情(设定/角色数/场景数/资产统计等)。免费。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}`)));
-    server.tool('get_characters', '读某一集的角色列表(名字/外貌/定妆图/身份锚是否就绪)。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/characters`)));
+    server.tool('get_characters', '读某一集的角色列表(名字/定妆图/设定图就绪状态)。免费。每角色带结构化状态:' +
+        'portrait_status/sheet_status(ready=已入库/pending=生成或审计中·别重复点/rejected=图已生成但被' +
+        '一致性闸拒收未入库/failed/none)+ 拒收时的 sheet_fail_reason·sheet_retryable·sheet_fail_hint(拒收判词)。' +
+        '★sheet_status=rejected 时照 retryable 判:consistency_rejected 可重掷一次(generate_character_sheet);' +
+        '**连拒且 fail_hint 理由几乎相同 = 锚字段与人物档案冲突(结构性必拒),重掷纯白花钱**——' +
+        '先 run_precheck 看 anchor-conflict 警告,把 visual_lock/art_bible 里钉死的角色外观移除或对齐档案再重掷。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/characters`)));
     server.tool('get_scenes', '读某一集的场景列表(名字/描述/场景图是否就绪)。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/scenes`)));
     server.tool('get_assets', '读一部剧的全部资产聚合(角色/场景/道具/图片)。免费。', { drama_id: z.number().int().positive() }, async ({ drama_id }) => jsonResult(await client.produceGet(`/dramas/${drama_id}/assets`)));
     // ========== P1 · 任务进度 + 成本/预算 ==========

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "mcpName": "ai.starreel/starreel",
   "description": "StarReel MCP server — drive the AI short-drama production pipeline (script → storyboards → frames → video → final cut) from Claude, Cursor, or any MCP client",
   "license": "MIT",

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "ai.starreel/starreel",
   "description": "Turn a script into a finished, downloadable short-drama episode — via MCP or REST.",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.36",
+      "version": "0.1.38",
       "transport": { "type": "stdio" },
       "environmentVariables": [
         {