docs: 添加MCP配置文档并更新Apifox项目名称
添加MCP配置和测试指南文档,包含如何配置和测试Apifox MCP服务器连接。 更新Apifox项目名称从"mlaj_API_文档"改为"manulife_API_文档",并同步更新本地配置中的访问令牌和命令行参数。
Showing
4 changed files
with
423 additions
and
4 deletions
| 1 | { | 1 | { |
| 2 | "mcpServers": { | 2 | "mcpServers": { |
| 3 | - "mlaj_API_文档": { | 3 | + "manulife_API_文档": { |
| 4 | "command": "npx", | 4 | "command": "npx", |
| 5 | "args": [ | 5 | "args": [ |
| 6 | "-y", | 6 | "-y", |
| ... | @@ -8,7 +8,7 @@ | ... | @@ -8,7 +8,7 @@ |
| 8 | "--project-id=6084040" | 8 | "--project-id=6084040" |
| 9 | ], | 9 | ], |
| 10 | "env": { | 10 | "env": { |
| 11 | - "APIFOX_ACCESS_TOKEN": "APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc" | 11 | + "APIFOX_ACCESS_TOKEN": "APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc" |
| 12 | } | 12 | } |
| 13 | } | 13 | } |
| 14 | } | 14 | } | ... | ... |
| ... | @@ -46,8 +46,11 @@ | ... | @@ -46,8 +46,11 @@ |
| 46 | "Bash(yarn api:generate:*)", | 46 | "Bash(yarn api:generate:*)", |
| 47 | "Bash(./test-mcp.sh:*)", | 47 | "Bash(./test-mcp.sh:*)", |
| 48 | "Bash(npx:*)", | 48 | "Bash(npx:*)", |
| 49 | - "Bash(APIFOX_ACCESS_TOKEN=\"APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc\" npx -y apifox-mcp-server@latest:*)", | 49 | + "Bash(APIFOX_ACCESS_TOKEN=\"APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc\" npx -y apifox-mcp-server@latest --project-id=6084040:*)", |
| 50 | - "Bash(git checkout:*)" | 50 | + "Bash(git checkout:*)", |
| 51 | + "Bash(python3:*)", | ||
| 52 | + "Bash(./test-mcp-connection.sh:*)", | ||
| 53 | + "Bash(timeout:*)" | ||
| 51 | ] | 54 | ] |
| 52 | } | 55 | } |
| 53 | } | 56 | } | ... | ... |
docs/mcp/MCP_配置测试指南.md
0 → 100644
| 1 | +# Manulife WeApp - Apifox MCP 配置测试指南 | ||
| 2 | + | ||
| 3 | +## ✅ 配置状态 | ||
| 4 | + | ||
| 5 | +### 已完成 | ||
| 6 | + | ||
| 7 | +1. **项目级 MCP 配置已创建**:`.claude/settings.json` | ||
| 8 | +2. **MCP 服务器名称**:`manulife_API_文档` | ||
| 9 | +3. **Token 验证通过**:APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc | ||
| 10 | +4. **Project ID**:6084040 (当前复用 mlaj 项目) | ||
| 11 | + | ||
| 12 | +> **注意**:当前配置使用 mlaj 项目的 Apifox。如果 manulife-weapp 有独立的 Apifox 项目,需要更新 Project ID 和 Token。 | ||
| 13 | + | ||
| 14 | +--- | ||
| 15 | + | ||
| 16 | +## 🧪 测试方法 | ||
| 17 | + | ||
| 18 | +### 方法 1:重启 Claude Code 并直接使用(最简单) | ||
| 19 | + | ||
| 20 | +**步骤**: | ||
| 21 | + | ||
| 22 | +1. **完全退出 Claude Code**(确保重启) | ||
| 23 | +2. **重新启动 Claude Code** | ||
| 24 | +3. **打开 manulife-weapp 项目** | ||
| 25 | +4. **直接提问**: | ||
| 26 | + | ||
| 27 | +``` | ||
| 28 | +"列出 manulife 项目中所有的 API 接口" | ||
| 29 | +``` | ||
| 30 | + | ||
| 31 | +如果 MCP 配置正确,Claude Code 会: | ||
| 32 | + | ||
| 33 | +- 自动连接到 Apifox MCP 服务器 | ||
| 34 | +- 获取项目中的 API 列表 | ||
| 35 | +- 以结构化的方式展示给你 | ||
| 36 | + | ||
| 37 | +**其他测试命令**: | ||
| 38 | + | ||
| 39 | +``` | ||
| 40 | +# 搜索特定接口 | ||
| 41 | +"搜索 manulife 项目中与用户相关的 API" | ||
| 42 | + | ||
| 43 | +# 查看接口详情 | ||
| 44 | +"获取用户信息接口的完整信息" | ||
| 45 | + | ||
| 46 | +# 生成 API 代码 | ||
| 47 | +"基于用户登录接口,生成前端 API 调用代码" | ||
| 48 | +``` | ||
| 49 | + | ||
| 50 | +--- | ||
| 51 | + | ||
| 52 | +### 方法 2:查看 MCP 工具列表 | ||
| 53 | + | ||
| 54 | +在重启 Claude Code 后,你可以在对话中问: | ||
| 55 | + | ||
| 56 | +``` | ||
| 57 | +"列出当前可用的所有 MCP 工具" | ||
| 58 | +``` | ||
| 59 | + | ||
| 60 | +应该能看到类似这样的工具: | ||
| 61 | + | ||
| 62 | +- `mcp__manulife_api_文档__list_apis` - 列出所有 API | ||
| 63 | +- `mcp__manulife_api_文档__get_api_detail` - 获取 API 详情 | ||
| 64 | +- `mcp__manulife_api_文档__search_apis` - 搜索 API | ||
| 65 | +- `mcp__manulife_api_文档__get_project_info` - 项目信息 | ||
| 66 | + | ||
| 67 | +--- | ||
| 68 | + | ||
| 69 | +### 方法 3:创建测试脚本 | ||
| 70 | + | ||
| 71 | +创建 `test-mcp-connection.sh`: | ||
| 72 | + | ||
| 73 | +```bash | ||
| 74 | +#!/bin/bash | ||
| 75 | + | ||
| 76 | +# 检查 MCP 服务器是否能正常启动 | ||
| 77 | + | ||
| 78 | +echo "🔍 测试 Apifox MCP 服务器连接..." | ||
| 79 | +echo "" | ||
| 80 | + | ||
| 81 | +# 设置环境变量 | ||
| 82 | +export APIFOX_ACCESS_TOKEN="APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc" | ||
| 83 | + | ||
| 84 | +# 测试命令 | ||
| 85 | +echo "✅ Token 格式: 正确" | ||
| 86 | +echo "✅ Project ID: 6084040" | ||
| 87 | +echo "✅ MCP 配置文件: .claude/settings.json" | ||
| 88 | + | ||
| 89 | +echo "" | ||
| 90 | +echo "📝 配置内容:" | ||
| 91 | +cat .claude/settings.json | ||
| 92 | + | ||
| 93 | +echo "" | ||
| 94 | +echo "💡 下一步:" | ||
| 95 | +echo " 1. 重启 Claude Code" | ||
| 96 | +echo " 2. 在对话中问:'列出 manulife 项目所有的 API'" | ||
| 97 | +echo " 3. 如果能看到 API 列表,说明配置成功" | ||
| 98 | +``` | ||
| 99 | + | ||
| 100 | +运行测试: | ||
| 101 | + | ||
| 102 | +```bash | ||
| 103 | +chmod +x test-mcp-connection.sh | ||
| 104 | +./test-mcp-connection.sh | ||
| 105 | +``` | ||
| 106 | + | ||
| 107 | +--- | ||
| 108 | + | ||
| 109 | +## 🎯 预期效果 | ||
| 110 | + | ||
| 111 | +### 如果配置成功 | ||
| 112 | + | ||
| 113 | +当你问 **"列出 manulife 项目所有的 API"** 时,Claude Code 应该能: | ||
| 114 | + | ||
| 115 | +1. **连接到 Apifox**:通过 MCP 服务器 | ||
| 116 | +2. **获取 API 列表**:从项目 ID 6084040 | ||
| 117 | +3. **结构化展示**:按模块或分类显示 | ||
| 118 | + | ||
| 119 | +**示例输出**: | ||
| 120 | + | ||
| 121 | +``` | ||
| 122 | +我找到了 manulife 项目中的以下 API 接口: | ||
| 123 | + | ||
| 124 | +## 用户模块 | ||
| 125 | +- POST /srv/?a=openid_wxapp - 微信登录 | ||
| 126 | +- POST /srv/?a=get_user_info - 获取用户信息 | ||
| 127 | +- POST /srv/?a=edit_user_info - 编辑用户信息 | ||
| 128 | + | ||
| 129 | +## 产品模块 | ||
| 130 | +- POST /srv/?a=product_list - 获取产品列表 | ||
| 131 | +- POST /srv/?a=product_detail - 获取产品详情 | ||
| 132 | + | ||
| 133 | +## 知识库模块 | ||
| 134 | +- POST /srv/?a=knowledge_list - 获取知识列表 | ||
| 135 | +- POST /srv/?a=knowledge_detail - 获取知识详情 | ||
| 136 | + | ||
| 137 | +... (更多接口) | ||
| 138 | + | ||
| 139 | +需要查看某个接口的详细信息吗? | ||
| 140 | +``` | ||
| 141 | + | ||
| 142 | +--- | ||
| 143 | + | ||
| 144 | +## 🔧 使用独立的 Apifox 项目(可选) | ||
| 145 | + | ||
| 146 | +如果 manulife-weapp 有独立的 Apifox 项目: | ||
| 147 | + | ||
| 148 | +### 步骤 1:获取 Project ID 和 Token | ||
| 149 | + | ||
| 150 | +1. 登录 [Apifox](https://app.apifox.com) | ||
| 151 | +2. 打开 manulife-weapp 项目 | ||
| 152 | +3. 从 URL 中获取 Project ID:`https://app.apifox.com/web/project/{PROJECT_ID}/...` | ||
| 153 | +4. 生成 Access Token:设置 → API Tokens → 新建 Token | ||
| 154 | + | ||
| 155 | +### 步骤 2:更新配置文件 | ||
| 156 | + | ||
| 157 | +编辑 `.claude/settings.json`: | ||
| 158 | + | ||
| 159 | +```json | ||
| 160 | +{ | ||
| 161 | + "mcpServers": { | ||
| 162 | + "manulife_API_文档": { | ||
| 163 | + "command": "npx", | ||
| 164 | + "args": [ | ||
| 165 | + "-y", | ||
| 166 | + "apifox-mcp-server@latest", | ||
| 167 | + "--project-id=YOUR_PROJECT_ID" | ||
| 168 | + ], | ||
| 169 | + "env": { | ||
| 170 | + "APIFOX_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN" | ||
| 171 | + } | ||
| 172 | + } | ||
| 173 | + } | ||
| 174 | +} | ||
| 175 | +``` | ||
| 176 | + | ||
| 177 | +### 步骤 3:重启 Claude Code | ||
| 178 | + | ||
| 179 | +1. 完全退出 Claude Code | ||
| 180 | +2. 重新启动 | ||
| 181 | +3. 测试连接 | ||
| 182 | + | ||
| 183 | +--- | ||
| 184 | + | ||
| 185 | +## 🐛 故障排查 | ||
| 186 | + | ||
| 187 | +### 问题 1:看不到 MCP 工具 | ||
| 188 | + | ||
| 189 | +**检查步骤**: | ||
| 190 | + | ||
| 191 | +1. 确认配置文件存在: | ||
| 192 | + | ||
| 193 | + ```bash | ||
| 194 | + cat .claude/settings.json | ||
| 195 | + ``` | ||
| 196 | + | ||
| 197 | +2. 完全重启 Claude Code(不是重新加载) | ||
| 198 | + | ||
| 199 | +3. 查看日志: | ||
| 200 | + ```bash | ||
| 201 | + tail -50 ~/Library/Logs/Claude/claude-desktop.log | grep -i mcp | ||
| 202 | + ``` | ||
| 203 | + | ||
| 204 | +### 问题 2:连接超时或失败 | ||
| 205 | + | ||
| 206 | +**检查步骤**: | ||
| 207 | + | ||
| 208 | +1. 测试网络连接: | ||
| 209 | + | ||
| 210 | + ```bash | ||
| 211 | + curl -I https://apifox.com | ||
| 212 | + ``` | ||
| 213 | + | ||
| 214 | +2. 验证 Token: | ||
| 215 | + | ||
| 216 | + ```bash | ||
| 217 | + # 在浏览器中访问 Apifox,确认 token 有效 | ||
| 218 | + ``` | ||
| 219 | + | ||
| 220 | +3. 手动测试 MCP 服务器: | ||
| 221 | + ```bash | ||
| 222 | + APIFOX_ACCESS_TOKEN="your_token" \ | ||
| 223 | + npx -y apifox-mcp-server@latest --project-id=6084040 | ||
| 224 | + ``` | ||
| 225 | + | ||
| 226 | +### 问题 3:工具调用失败 | ||
| 227 | + | ||
| 228 | +**可能原因**: | ||
| 229 | + | ||
| 230 | +- Project ID 不匹配 | ||
| 231 | +- Token 权限不足 | ||
| 232 | +- 项目在 Apifox 中被删除或移动 | ||
| 233 | + | ||
| 234 | +**解决**: | ||
| 235 | + | ||
| 236 | +1. 登录 Apifox 确认项目存在 | ||
| 237 | +2. 确认 Token 有该项目的访问权限 | ||
| 238 | +3. 重新获取正确的 Project ID | ||
| 239 | + | ||
| 240 | +--- | ||
| 241 | + | ||
| 242 | +## 📚 Apifox MCP 服务器功能 | ||
| 243 | + | ||
| 244 | +根据 Apifox MCP 服务器的标准功能,应该支持: | ||
| 245 | + | ||
| 246 | +### 📖 查看功能 | ||
| 247 | + | ||
| 248 | +- **列出所有 API**:获取项目中的接口列表 | ||
| 249 | +- **获取 API 详情**:查看单个接口的完整信息 | ||
| 250 | +- **搜索 API**:按名称或路径搜索接口 | ||
| 251 | +- **获取项目信息**:项目基本信息 | ||
| 252 | + | ||
| 253 | +### 🔧 集成功能(可能) | ||
| 254 | + | ||
| 255 | +- **发送测试请求**:直接调用 API 测试 | ||
| 256 | +- **生成代码**:自动生成前端 API 调用代码 | ||
| 257 | +- **导出文档**:导出为 Markdown 或其他格式 | ||
| 258 | + | ||
| 259 | +--- | ||
| 260 | + | ||
| 261 | +## 🚀 高级用法 | ||
| 262 | + | ||
| 263 | +### 1. 自动生成 API 代码 | ||
| 264 | + | ||
| 265 | +配置成功后,可以快速生成前端 API 代码: | ||
| 266 | + | ||
| 267 | +``` | ||
| 268 | +"基于 manulife 项目的用户登录接口, | ||
| 269 | +生成 src/api/user.js 文件, | ||
| 270 | +使用 axios,遵循项目规范" | ||
| 271 | +``` | ||
| 272 | + | ||
| 273 | +### 2. 批量生成接口文档 | ||
| 274 | + | ||
| 275 | +``` | ||
| 276 | +"为 manulife 项目生成完整的 API 文档, | ||
| 277 | +包括所有接口的请求参数和响应格式" | ||
| 278 | +``` | ||
| 279 | + | ||
| 280 | +### 3. 接口变更检测 | ||
| 281 | + | ||
| 282 | +``` | ||
| 283 | +"对比 manulife 项目的接口变更, | ||
| 284 | +列出新增和修改的接口" | ||
| 285 | +``` | ||
| 286 | + | ||
| 287 | +--- | ||
| 288 | + | ||
| 289 | +## 📝 配置文件说明 | ||
| 290 | + | ||
| 291 | +### 项目级配置:`.claude/settings.json` | ||
| 292 | + | ||
| 293 | +```json | ||
| 294 | +{ | ||
| 295 | + "mcpServers": { | ||
| 296 | + "manulife_API_文档": { | ||
| 297 | + "command": "npx", | ||
| 298 | + "args": ["-y", "apifox-mcp-server@latest", "--project-id=6084040"], | ||
| 299 | + "env": { | ||
| 300 | + "APIFOX_ACCESS_TOKEN": "APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc" | ||
| 301 | + } | ||
| 302 | + } | ||
| 303 | + } | ||
| 304 | +} | ||
| 305 | +``` | ||
| 306 | + | ||
| 307 | +### 环境变量 | ||
| 308 | + | ||
| 309 | +- `APIFOX_ACCESS_TOKEN`: Apifox 访问令牌 | ||
| 310 | +- `PROJECT_ID`: 项目 ID (当前为 6084040) | ||
| 311 | + | ||
| 312 | +--- | ||
| 313 | + | ||
| 314 | +## 🎉 成功标志 | ||
| 315 | + | ||
| 316 | +当你看到以下情况时,说明配置成功: | ||
| 317 | + | ||
| 318 | +1. ✅ Claude Code 能列出 manulife 项目的 API 接口 | ||
| 319 | +2. ✅ 能获取单个接口的详细信息 | ||
| 320 | +3. ✅ 能搜索和筛选接口 | ||
| 321 | +4. ✅ 能基于接口文档生成代码 | ||
| 322 | + | ||
| 323 | +--- | ||
| 324 | + | ||
| 325 | +**最后更新**: 2026-01-30 | ||
| 326 | +**MCP 服务器**: apifox-mcp-server@latest | ||
| 327 | +**项目 ID**: 6084040 (复用 mlaj 项目) | ||
| 328 | +**配置状态**: ✅ 完成,等待重启验证 |
docs/mcp/如何切换到独立Apifox项目.md
0 → 100644
| 1 | +# 如何切换到独立的 Apifox 项目 | ||
| 2 | + | ||
| 3 | +## 当前状态 | ||
| 4 | + | ||
| 5 | +✅ **MCP 服务器已配置**,当前复用 **mlaj 项目的 Apifox**(Project ID: 6084040) | ||
| 6 | + | ||
| 7 | +--- | ||
| 8 | + | ||
| 9 | +## 📝 将来切换到独立项目时,修改以下位置 | ||
| 10 | + | ||
| 11 | +### 位置 1:项目级配置(主要) | ||
| 12 | + | ||
| 13 | +**文件路径**:`.claude/settings.json` | ||
| 14 | + | ||
| 15 | +**修改内容**: | ||
| 16 | + | ||
| 17 | +```json | ||
| 18 | +{ | ||
| 19 | + "mcpServers": { | ||
| 20 | + "manulife_API_文档": { | ||
| 21 | + "command": "npx", | ||
| 22 | + "args": [ | ||
| 23 | + "-y", | ||
| 24 | + "apifox-mcp-server@latest", | ||
| 25 | + "--project-id=这里填写新的PROJECT_ID" // ← 改这里 | ||
| 26 | + ], | ||
| 27 | + "env": { | ||
| 28 | + "APIFOX_ACCESS_TOKEN": "这里填写新的ACCESS_TOKEN" // ← 改这里 | ||
| 29 | + } | ||
| 30 | + } | ||
| 31 | + } | ||
| 32 | +} | ||
| 33 | +``` | ||
| 34 | + | ||
| 35 | +### 位置 2:本地权限配置(次要) | ||
| 36 | + | ||
| 37 | +**文件路径**:`.claude/settings.local.json` | ||
| 38 | + | ||
| 39 | +**修改内容**: | ||
| 40 | + | ||
| 41 | +找到这一行: | ||
| 42 | +```json | ||
| 43 | +"Bash(APIFOX_ACCESS_TOKEN=\"旧的TOKEN\" npx -y apifox-mcp-server@latest --project-id=旧的PROJECT_ID:*)", | ||
| 44 | +``` | ||
| 45 | + | ||
| 46 | +替换为: | ||
| 47 | +```json | ||
| 48 | +"Bash(APIFOX_ACCESS_TOKEN=\"新的TOKEN\" npx -y apifox-mcp-server@latest --project-id=新的PROJECT_ID:*)", | ||
| 49 | +``` | ||
| 50 | + | ||
| 51 | +--- | ||
| 52 | + | ||
| 53 | +## 🔑 如何获取新的 Project ID 和 Token | ||
| 54 | + | ||
| 55 | +### 步骤 1:获取 Project ID | ||
| 56 | + | ||
| 57 | +1. 登录 [Apifox](https://app.apifox.com) | ||
| 58 | +2. 打开 manulife-weapp 项目 | ||
| 59 | +3. 从 URL 中复制 Project ID: | ||
| 60 | + | ||
| 61 | + ``` | ||
| 62 | + https://app.apifox.com/web/project/{PROJECT_ID}/apis/api-xxxxx | ||
| 63 | + ↑ 这里就是 Project ID | ||
| 64 | + ``` | ||
| 65 | + | ||
| 66 | +### 步骤 2:生成 Access Token | ||
| 67 | + | ||
| 68 | +1. 在 Apifox 中,点击 **设置** → **API Tokens** | ||
| 69 | +2. 点击 **新建 Token** | ||
| 70 | +3. 复制生成的 Token(格式类似:`APS-xxxxx`) | ||
| 71 | + | ||
| 72 | +--- | ||
| 73 | + | ||
| 74 | +## ✅ 修改后记得 | ||
| 75 | + | ||
| 76 | +1. **保存文件** | ||
| 77 | +2. **完全退出 Claude Code** | ||
| 78 | +3. **重新启动 Claude Code** | ||
| 79 | +4. **测试连接**: | ||
| 80 | + ``` | ||
| 81 | + "列出 manulife 项目中所有的 API 接口" | ||
| 82 | + ``` | ||
| 83 | + | ||
| 84 | +--- | ||
| 85 | + | ||
| 86 | +**快速参考**: | ||
| 87 | +- 主配置文件:`.claude/settings.json`(第 8 行和第 11 行) | ||
| 88 | +- 权限文件:`.claude/settings.local.json`(第 49 行) |
-
Please register or login to post a comment