Files
3970260761 3f064d7412 feat(mcp): 端点强制 Bearer 鉴权(公网必须授权)
- mcp/server.py 入站鉴权中间件:/mcp 要求 Authorization: Bearer <MCP_AUTH_TOKEN>
  (hmac.compare_digest 恒定时间比较),无/错令牌 401 + WWW-Authenticate;
  令牌未配置 fail-closed 拒绝一切调用
- 放行 /health(监控)与 /out/*(产物下载直链,浏览器无法带请求头)
- docker-compose.yml 注入 MCP_AUTH_TOKEN(令牌在 .env,git 忽略不入库)
- mcp/README.md 连接示例全部带鉴权头,修正 Hermes 键名为官方 mcp_servers
- README.md MCP 章节补授权说明、内联 compose 同步;CHANGELOG 记录
- 验证:401 矩阵/fail-closed/完整握手/9工具/service_status 真调用 全通过
2026-11-11 23:41:35 +08:00

5.8 KiB
Raw Permalink Blame History

米剪 MCP 服务(unicut-mcp)

让 AI 客户端以 Model Context Protocol 工具的形式调用米剪的创作能力:抓文章、写口播、配语音、生成米剪工程,人在米剪里打开就能剪。

AI(Claude / Cursor / Hermes …)
   │  MCP(Streamable HTTP)
   ▼
https://<米剪站点>/mcp  ──►  unicut-mcp 容器(本目录)
   ├─ grab_url            抓网页正文与配图(公众号文章可用)
   ├─ generate_script     大模型生成口播文案(OpenAI 兼容网关)
   ├─ tts / list_voices   edge-tts 配音(unicut-tts 容器)
   ├─ create_video_project 生成米剪工程 ZIP → 米剪「工程文件」导入
   └─ list/read/write_project  工作文件夹(文件夹模式)工程读写

工具一览

工具 作用 典型返回
service_status 自检抓取/配音/大模型/工程目录可用性 各依赖状态
grab_url(url) 抓取网页正文与配图(规则与前端 extractFromHtml 一致:#js_content 优先、懒加载属性、12000 字截断) {title, text, images[]}
generate_script(source, requirement?, style?, target_seconds?, paragraph_count?) 大模型写口播文案,严格 JSON 输出 {title, paragraphs[], text}
list_voices() edge-tts 音色列表 {count, voices[]}
tts(text, voice?, rate?, pitch?, volume?) 合成配音,音频落盘并给出可播放 URL {url, path, duration}
create_video_project(title, images, script?, audio?, width?, height?, …) 下载素材 → 组装 MovieData → 打包工程 ZIP(project.json + materials/,与米剪导出格式同构,过 checkNdata 九键门禁) {zip_path, zip_url, duration, captions, elements}
list_projects() / read_project(id) / write_project(project) 工作文件夹模式下直接读写 projects/*.json(需配置 MCP_PROJECTS_DIR) 工程 JSON

create_video_project 细节:

  • 图片校验与前端一致:≥160×120、≤10MB、识别失败自动跳过并在 warnings 里说明;
  • 有配音时图片自动拉伸平铺铺满配音时长,无配音时每图 image_duration(默认 3 秒);
  • script 按 \n 分段成字幕(单段超 24 字自动按句拆),按字数加权分配时间;
  • 字幕/图片/音频元素结构照抄官方 demo 工程(public/assets/demo/test-app.json)真实字段。

连接方式

端点:https://<米剪站点>/mcp(Streamable HTTP;本机默认 https://127.0.0.1:3005/mcp,自签证书需客户端允许 insecure)。局域网内也可直连容器端口 http://<主机>:8765/mcp(默认只在 compose 网络内,未映射宿主端口)。

🔒 必须授权:服务暴露在公网,/mcp 一律要求请求头 Authorization: Bearer <MCP_AUTH_TOKEN>(令牌取项目 .env 的 MCP_AUTH_TOKEN;未配置令牌时服务拒绝一切调用,fail-closed)。不带 / 错误令牌返回 401 {"error":"unauthorized"}。仅两类路径开放:/mcp-health(监控探针)与 /mcp-out/*(工程 ZIP / 配音 mp3 下载直链,浏览器点开无法附带请求头)。

Claude Desktop(claude_desktop_config.json):

{
  "mcpServers": {
    "unicut": {
      "command": "npx",
      "args": ["mcp-remote", "https://127.0.0.1:3005/mcp", "--allow-self-signed", "--header", "Authorization: Bearer <令牌>"]
    }
  }
}

Claude Code:

claude mcp add unicut --transport http --header "Authorization: Bearer <令牌>" https://127.0.0.1:3005/mcp

Cursor(~/.cursor/mcp.json):

{
  "mcpServers": {
    "unicut": {
      "url": "https://127.0.0.1:3005/mcp",
      "headers": { "Authorization": "Bearer <令牌>" }
    }
  }
}

Hermes(~/.hermes 或项目 config.yaml):

mcp_servers:
  unicut:
    url: https://127.0.0.1:3005/mcp
    headers:
      Authorization: "Bearer <令牌>"

部署

compose 已内置 unicut-mcp 服务(本仓库 docker-compose.yml),密钥走项目 .env:

# .env(勿提交)
MCP_LLM_BASE=http://192.168.68.19:3099/v1   # OpenAI 兼容 /v1 网关
MCP_LLM_KEY=sk-xxxx                          # 网关 Key
MCP_LLM_MODEL=mimo-v2.6-flash
MCP_PUBLIC_URL=https://127.0.0.1:3005        # 对外站点地址(生成 zip_url / 音频 URL 用)
MCP_AUTH_TOKEN=<随机长串>                    # 必填:/mcp 的 Bearer 令牌(公网必须授权;python3 -c 'import secrets;print(secrets.token_urlsafe(32))' 生成)
MCP_PROJECTS_DIR=                            # 可选:米剪「选择文件夹」的同一目录(文件夹模式)
docker compose up -d --build unicut-mcp

单独运行(不走 nginx):

docker build -t unicut-mcp ./mcp
docker run -d --name unicut-mcp --restart always \
  -e MCP_LLM_KEY=sk-xxxx -e MCP_LLM_BASE=http://192.168.68.19:3099/v1 \
  -p 8765:8765 -v "$PWD/mcp-out:/data/out" unicut-mcp

只有 service_status / grab_url / generate_script 需要网络依赖;tts 依赖同 compose 的 unicut-tts;不配置 .env 时除大模型类工具外均可使用。

验证

# 协议握手(必须带 Authorization,否则 401)
curl -sk https://127.0.0.1:3005/mcp -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

# 预期:不带令牌 → 401 {"ok":false,"error":"unauthorized"} + WWW-Authenticate: Bearer

产物下载:https://<站点>/mcp-out/<工程名>.zip;健康检查:经 nginx 用 https://<站点>/mcp-health,直连容器用 http://<容器>:8765/health(/mcp/health 不是端点,会被 SPA 回退成首页 HTML)。