yingjing-mcp

影境（yingjing；产品代码 videohub / VisionFlow，编号 4700）MCP stdio 服务，供 Cursor / AI Agent 创建与管理视频项目（含脚本与画风设定）。

本服务通过 stdio 与 MCP 客户端通信，将工具调用转发至 videohub-core-server 的内网 MCP API（/internal/mcp/v1/*）。仓库目录仍为 videohub-mcp，对外 npm 包名与 Cursor 服务名为 yingjing-mcp / yingjing。

前置条件

1. 已启动 videohub-core-server（本地 dev profile，端口 4702）
2. Node.js 18+（需支持原生 fetch）
3. gonline 工作空间签发的 Agent API Key（bigapp_...）；本地也可用开发兜底 Token（见后端 application-dev.yml）

安装与构建

cd videohub-mcp
npm install
npm run build              # 本地开发，写入 http://127.0.0.1:4702
npm run build:test         # 测试环境
npm run build:production   # 生产环境

构建时会按命令读取对应 .env.* 文件，将 BIGAPP_API_BASE 写入产物（用户 MCP 配置一般无需再填该地址）。

构建产物位于 dist/index.js。

环境文件

| 文件 | 构建命令 | 说明 | |------|----------|------| | .env.development | npm run build | 本地 dev，后端 4702 | | .env.test | npm run build:test | 测试环境 | | .env.production | npm run build:production | 生产环境 |

各文件中的 BIGAPP_API_BASE 为影境 MCP 内网 API 根地址（不含 /internal/mcp/v1 后缀）：

| 环境 | 示例值 | 说明 | |------|--------|------| | 本地 dev | http://127.0.0.1:4702 | 直连后端，无 /api 前缀 | | 测试 / 生产 | https://yingjing.*.atbigapp.com/api | 经 nginx 同域代理，须带 /api |

代码会在公网域名未写 /api 时自动补全；直连 4702/4712/4722 端口不会追加。

运行时环境变量（Cursor MCP 配置）

与智忆 / 智测 MCP 命名一致：

| 变量 | 说明 | 是否必填 | |------|------|----------| | BIGAPP_API_KEY | 工作空间签发的 Agent 密钥 | 必填 | | BIGAPP_API_BASE | 覆盖构建时写入的后端地址 | 一般不需要 |

本地联调示例（指向本仓库 dist）：

{
  "mcpServers": {
    "yingjing": {
      "command": "node",
      "args": ["/绝对路径/videohub/videohub-mcp/dist/index.js"],
      "env": {
        "BIGAPP_API_KEY": "bigapp_xxx 或 videohub-mcp-dev-token"
      }
    }
  }
}

也可参考 cursor-mcp.example.json。

能力清单

| MCP Tool | 说明 | |----------|------| | whoami | 校验 Key，返回签发者与工作空间摘要 | | createProject | 创建视频项目 | | listProjects | 分页列出当前签发者的项目 | | getProject | 项目详情（含 scriptContent + scriptDocument） | | updateProject | 更新名称/描述/标签与/或脚本（优先 scriptDocument） | | deleteProject | 逻辑删除项目 | | getStyleSetting | 查询画风设定（风格卡文案 + 色调/负向词/比例/Seed） | | generateStyleSetting | AI 生成/重新生成画风设定（自动落库，不出主图） | | updateStyleSetting | 手动修改画风设定（按字段增量更新） |

首期不开放分镜 / 时间轴 JSON 写入，也不开放风格主图生成与风格卡锁定。写入脚本请优先使用 updateProject.scriptDocument（结构化 JSON），服务端会渲染为平台约定的「分镜N (X秒)」纯文本再入库；scriptContent 纯文本仅作兼容。

scriptDocument 示例

{
  "title": "智测 AI TestOps 宣传短片",
  "shots": [
    {
      "index": 1,
      "durationSeconds": 10,
      "visual": "暗色开发界面中，Cursor 快速生成代码与 PR",
      "narration": "AI 已经能写代码、提 PR。可多数测试平台，仍把 AI 挡在门外。",
      "subtitle": "AI 写了代码，测试还在等谁？"
    }
  ]
}

字段约束：shots 至少 1 条；每镜 index >= 1，且 visual / narration / subtitle 至少填一项；durationSeconds 为单镜秒数（勿写时间轴区间）。

推荐调用顺序

1. whoami — 确认身份
2. createProject — 创建项目，记下返回的 id
3. updateProject — 写入 scriptDocument（推荐）
4. generateStyleSetting — 按脚本/描述生成画风设定；或用 updateStyleSetting 手写修改
5. getStyleSetting / getProject — 核对结果

项目归属完全由 BIGAPP_API_KEY 签发者（creatorId）决定，勿在 Cursor env 写死业务用户 ID。

画风设定示例

AI 生成（覆盖已有设定时加 regenerate: true）：

{
  "projectId": "项目ID",
  "regenerate": true,
  "extraRequirement": "更偏赛博朋克，冷色主调"
}

手动修改（只改需要的字段）：

{
  "projectId": "项目ID",
  "styleName": "反诈3D卡通短片",
  "styleDescription": "3D卡通渲染，插画风格，非写实人物，柔和材质，清晰轮廓",
  "colorTone": "室内暖光主调，局部冷蓝辅光",
  "negativePrompt": "写实照片,真人肖像,照片级写实,畸形手指,文字水印",
  "defaultRatio": "16:9"
}

说明：generateStyleSetting / updateStyleSetting 只写文案与公共出图参数，不会自动出风格主图或锁定风格卡；主图与锁定请在 Web 风格母版页完成。风格卡已锁定时 updateStyleSetting 会返回错误，需先在 Web 解锁。

C 端使用引导

影境 Web 提供可视化接入引导（签发密钥、复制 MCP 配置与提示词）：

• 页面：/mcp
• 入口：顶栏「智能体」、我的项目「智能体接入」、首页能力区「智能体 MCP」

计费说明（一期）

Web 登录链路已复用 gonline 会员 + 巨豆：创建 AI / 导出任务时用用户 OAuth 预扣巨豆，失败自动退回。

MCP 走 Agent API Key，一期不扣巨豆、不做会员档位校验（videohub.billing.skip-when-no-access-token=true）。MCP 计费为二期（需服务端代扣或用户态会话）。

本地开发兜底

videohub-core-server 的 application-dev.yml 提供：

• videohub.mcp.fallback-token: videohub-mcp-dev-token
• videohub.mcp.fallback-user-id: mcp-dev-user

将 BIGAPP_API_KEY 设为该 Token 即可在未接主站 Key 时联调；测试/生产请使用正式 bigapp_ Key。

License

Private