hookehuyr

docs: 添加MCP配置文档并更新Apifox项目名称

添加MCP配置和测试指南文档,包含如何配置和测试Apifox MCP服务器连接。
更新Apifox项目名称从"mlaj_API_文档"改为"manulife_API_文档",并同步更新本地配置中的访问令牌和命令行参数。
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 }
......
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 +**配置状态**: ✅ 完成,等待重启验证
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 行)