Files
jinghui a85f7b7bbc feat(mcp): 每 IP 每日 5 次调用限流 + 教程更新限流说明
- _AuthMiddleware 新增 POST /mcp 按客户端 IP 日配额(X-Forwarded-For 优先,UTC+8 日期键,内存存储重启清零,env MCP_DAILY_LIMIT 默认 5)
- 超限返回 429 + Retry-After: 86400,限流只计 /mcp POST,/health /out/* 不受限
- mcp-guide.md 端点小节新增限流规则 + 常见问题第 9 条 429 排查
- 实测:前 5 次放行、第 6 次 429
2026-11-14 11:03:20 +08:00
..

米剪 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)。