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