videohub-mcp

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

本服务通过 stdio 与 MCP 客户端通信，将工具调用转发至 videohub-core-server 的内网 MCP API（/internal/mcp/v1/*）。

前置条件

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": {
    "videohub": {
      "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） | | updateProject | 更新名称/描述/标签与/或脚本 | | deleteProject | 逻辑删除项目 |

首期不开放分镜 / 时间轴 JSON 写入；脚本通过 updateProject.scriptContent 维护。

推荐调用顺序

1. whoami — 确认身份
2. createProject — 创建项目，记下返回的 id
3. updateProject — 写入 scriptContent
4. getProject / listProjects — 核对结果

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

C 端使用引导

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

• 页面：/mcp
• 入口：顶栏「智能体」、我的项目「智能体接入」、首页能力区「智能体 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