mcn-short-video/project/短视频脚本创作/V1.0/references/接口调用/MCP_工具调用规范.md

MCP 工具调用规范

本文件是 MCP 依赖配置、安装引导、登录检查、降级策略的单一权威源。其他文件（SKILL.md、Douyin_Video_Analysis.md 等）只做指针引用，不重复内容。

---

1) 依赖的 MCP 服务

服务名	配置文件	环境标识	API 地址	用途
myai-mcp-production	scripts/mcp-config.json	正式	https://maiya-trans.youmanvideo.com/api	创意灵感搜索、抖音/本地视频解析等
myai-mcp-test	scripts/mcp-config.json	测试	http://maiya-trans.test.youmanvideo.com/api	开发调试用，数据非生产数据

---

2) 环境判定与安装策略

复用技能已有的部署检测机制（两步判定锚点：本机有 D:\AgentSkill 且技能根目录路径在 D:\AgentSkill\ 下 = 开发机；技能路径含 .dsh = dsh 部署环境；本机无 D:\AgentSkill = 用户环境——开发机装正式+测试，其余只装正式）。

环境	判定条件	安装内容
开发环境	本机存在 D:\AgentSkill 且 Skill 根目录路径在 D:\AgentSkill\ 下（源技能仓库）	myai-mcp-production + myai-mcp-test（推荐两个都装，可选只装正式）
非开发环境	部署到其他路径（组员机器、服务器）	只装 myai-mcp-production（正式），不装测试环境

---

3) 自动检测与安装引导流程

触发时机：用户首次提问（技能被触发）时即检测并提醒安装，不等到真正用到 API 功能才提示。「首次提问」= 本技能会话的首次交互（用户询问功能/功能介绍/发起任何任务，无论问什么），由 SKILL.md「MCP 依赖（摘要）·安装引导」作为必做动作驱动。

触发点	行为
用户首次提问（技能触发，无论问什么）	立即检测 MCP 可用性 → 未安装 → 主动提醒（步骤2-4）
创作流程步骤3 对标拆解 / 步骤5 创意灵感	若首次提问已提醒过 → 不重复提醒，直接使用或降级；若未提醒过 → 按本流程提醒
直接工具调用（"解析这个视频/查账号设定"）	未安装 → 按本流程提醒

按以下流程处理：

1. 检测：检查 myai-mcp-production 的 MCP 工具是否在可用列表中。检测方法（任一即可判定）：① 查看当前会话可用 MCP 工具列表是否含该服务工具（如 auth_status/upload_douyin_video/short_video_detail）；② 读 ~/.workbuddy/mcp.json（Windows 为 %USERPROFILE%\.workbuddy\mcp.json）是否含 myai-mcp-production 服务配置。两者都无 → 未安装 → 进入步骤2
2. 判定环境 + 提示：
   • 首次提问（轻量提醒，不打断创作）：

     本技能部分功能（对标视频解析 / 创意灵感 / 账号设定查询）依赖 MCN MCP 服务。是否现在安装？暂时不需要可跳过，不影响核心创作流程，用到时会再次提醒。

   • 创作中需用 API 功能 · 开发环境：

     本技能的 MCN API 功能需要安装 MCP 服务。开发环境可同时安装正式环境和测试环境。是否自动配置？

     • 两个都装（推荐）：正式环境用 myai-mcp-production，测试环境用 myai-mcp-test
     • 只装正式环境

   • 创作中需用 API 功能 · 非开发环境：

     本技能的 MCN API 功能需要安装 myai-mcp-production MCP 服务。是否自动配置？

3. 用户同意 → 前置检查运行环境 → 自动安装：
   • 部署预检（先做，按顺序）：
     1. 运行时版本：检查 Node.js（node --version）和 Python（python --version）是否已安装。缺失则先引导安装对应运行时再继续——npx 型 MCP 依赖 Node.js，python 型 MCP 依赖 Python，缺失会导致 MCP 安装/启动失败。
     2. npm 缓存权限（macOS 高发坑，必须查）：npx 型 MCP 首次运行需写入 npm 缓存（默认 ~/.npm 的 _npx/_cacache）。若缓存目录里有 root 权限文件（常见于曾用 sudo 装过包、系统迁移/重装后遗留），npx 无权限写入 → MCP 启动静默失败。典型症状：包能正常下载（源没问题）、配置也写入了，但 MCP 一直连不上/不出现。
        • 检查：npm config get cache 确认缓存目录（默认 ~/.npm）；macOS/Linux 用 find ~/.npm -user root 2>/dev/null | head 查看是否有 root 文件；Windows 无 root 权限文件问题，跳过此项检查（只需确认缓存目录可写即可）
        • 处理：缓存可重建，直接清理（目录本身归用户所有，无需 sudo）：rm -rf ~/.npm/_npx ~/.npm/_cacache，下次 npx 运行自动重建
        • 注意：只清缓存目录，不要动 ~/.npmrc（含 registry 配置）和全局已安装的包
     3. （可选）npm 源：国内网络确认 registry 已配镜像（npm config get registry，如 https://registry.npmmirror.com）避免拉包超时。但镜像不是启动失败的根因，排查顺序永远是 1 → 2 → 3。
   • 读取 scripts/mcp-config.json
   • 读取用户现有的 ~/.workbuddy/mcp.json（如不存在则创建）
   • 开发环境：将 myai-mcp-production + myai-mcp-test 两个服务合并写入（保留已有服务，不覆盖）
   • 非开发环境：只将 myai-mcp-production 服务合并写入（保留已有服务，不覆盖）
   • 提示用户：「配置已写入。请打开右上角「连接器管理」页面，找到 myai-mcp-production（开发环境额外找到 myai-mcp-test），分别点击 Trust 启用。启用后重新发起任务即可。」
4. 用户拒绝/跳过 → 降级：
   • 告知用户：「MCN API 功能将不可用，脚本创作核心流程（步骤1-11）不受影响，可正常使用。之后实际用到这些功能时会再次提醒安装。」
   • 继续执行不依赖 MCP 的创作流程

---

4) 登录状态检查

MCP 工具可用后，调用任何 MCP 工具前须先检查飞书登录状态。

检查频率：每天检查一次（当天缓存结果，当天内不重复检查）

检查流程：

1. auth_status()
   → 已登录 → 缓存状态，继续执行 MCP 调用
   → 未登录 → 进入步骤2

2. feishu_login()
   → 自动打开浏览器进行飞书 OAuth 授权
   → 等待用户完成授权（浏览器自动回调）

3. auth_status()
   → 已登录 → 缓存状态，继续执行 MCP 调用
   → 仍未登录 → 进入步骤4（兜底）

4. 提示用户：
   > 自动登录未成功，请手动提交授权码。
   > 从浏览器地址栏复制回调链接或授权码，粘贴提供给我。
   submit_auth_code(code_or_url="用户提供的值")

5. auth_status()
   → 已登录 → 缓存状态，继续执行 MCP 调用
   → 仍未登录 → 告知用户登录失败，进入降级流程

缓存规则：

• 缓存粒度：按天，每天首次调用时检查一次
• 缓存失效：跨天自动重新检查
• 缓存位置：运行时内存（不需要写文件）

---

5) 降级策略

功能	MCP 可用时	MCP 不可用时
步骤3 对标视频拆解	登录检查 → MCP 调用视频解析工具 → 等待3-15分钟 → 轮询结果	用户提供视频信息或跳过
步骤5 选题创意灵感	登录检查 → MCP 调用创意灵感 API（联网搜索/事件库）	用户手动提供选题方向
步骤1-2、4、6-11	不依赖 MCP，正常执行	不受影响

降级触发条件：

降级原因	处理方式
MCP 未安装/未 Trust	引导安装（见 3 自动检测与安装引导流程）
登录失败（auth_status 三次重试后仍未登录）	告知用户手动登录，跳过 API 功能
服务异常	告知用户稍后重试，跳过 API 功能
视频解析超时（超过 15 分钟）	告知用户超时，可稍后用 detailId 手动查询

---

6) MCP 工具清单

工具	用途	必填参数	适用场景
auth_status	检查当前登录状态是否有效	无	每天首次调用 MCP 前检查
feishu_login	飞书 OAuth 授权登录，打开浏览器自动完成	无	未登录时自动触发
submit_auth_code	手动提交飞书回调的授权码（自动登录失败时兜底）	code_or_url	自动登录失败时兜底
logout	退出登录，清除本地凭证	无	切换账号时
upload_douyin_video	提交抖音链接做 AI 内容解析入库	share_text（链接/分享文案）	对标视频是抖音链接时
upload_other_video	上传本地视频文件做 AI 内容解析入库	title + file_path	对标视频是本地文件时
short_video_detail	查询解析结果（文案+拆解），判断是否完成	id（详情ID）	上传后轮询获取解析内容
list_hot_accounts	列出全部达人账号	无	查看达人库
hot_account_detail	查看某个账号完整详情	account（账号名或ID）	对标账号拆解
current_user	获取当前登录用户完整资料	无	确认登录身份

视频解析工具的详细使用流程见 Douyin_Video_Analysis.md。