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) 环境判定与安装策略

复用技能已有的部署检测机制（路径含 `MCNVideo AI` = 开发环境）。

| 环境 | 判定条件 | 安装内容 |
|------|---------|---------|
| **开发环境** | Skill 根目录路径包含 `MCNVideo AI` | `myai-mcp-production` + `myai-mcp-test`（推荐两个都装，可选只装正式） |
| **非开发环境** | 部署到其他路径（组员机器、服务器） | 只装 `myai-mcp-production`（正式），不装测试环境 |

---

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

**触发时机：用户首次提问（技能被触发）时即检测并提醒安装，不等到真正用到 API 功能才提示。**

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

按以下流程处理：

1. **检测**：检查 `myai-mcp-production` 的 MCP 工具是否在可用列表中。可用 → 跳到 [§4 登录检查]；不可用 → 进入步骤2
2. **判定环境 + 提示**：
   - **首次提问（轻量提醒，不打断创作）**：
     > 本技能部分功能（对标视频解析 / 创意灵感 / 账号设定查询）依赖 MCN MCP 服务。是否现在安装？暂时不需要可跳过，不影响核心创作流程，用到时会再次提醒。
   - **创作中需用 API 功能 · 开发环境**：
     > 本技能的 MCN API 功能需要安装 MCP 服务。开发环境可同时安装正式环境和测试环境。是否自动配置？
     > - 两个都装（推荐）：正式环境用 `myai-mcp-production`，测试环境用 `myai-mcp-test`
     > - 只装正式环境
   - **创作中需用 API 功能 · 非开发环境**：
     > 本技能的 MCN API 功能需要安装 `myai-mcp-production` MCP 服务。是否自动配置？
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 自动检测与安装引导流程](#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`。