hookehuyr

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

添加MCP配置和测试指南文档,包含如何配置和测试Apifox MCP服务器连接。
更新Apifox项目名称从"mlaj_API_文档"改为"manulife_API_文档",并同步更新本地配置中的访问令牌和命令行参数。
{
"mcpServers": {
"mlaj_API_文档": {
"manulife_API_文档": {
"command": "npx",
"args": [
"-y",
......@@ -8,7 +8,7 @@
"--project-id=6084040"
],
"env": {
"APIFOX_ACCESS_TOKEN": "APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc"
"APIFOX_ACCESS_TOKEN": "APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc"
}
}
}
......
......@@ -46,8 +46,11 @@
"Bash(yarn api:generate:*)",
"Bash(./test-mcp.sh:*)",
"Bash(npx:*)",
"Bash(APIFOX_ACCESS_TOKEN=\"APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc\" npx -y apifox-mcp-server@latest:*)",
"Bash(git checkout:*)"
"Bash(APIFOX_ACCESS_TOKEN=\"APS-t3Lm53YUvYMwNWEqb5Y5nnrRSlDz04Mc\" npx -y apifox-mcp-server@latest --project-id=6084040:*)",
"Bash(git checkout:*)",
"Bash(python3:*)",
"Bash(./test-mcp-connection.sh:*)",
"Bash(timeout:*)"
]
}
}
......
# Manulife WeApp - Apifox MCP 配置测试指南
## ✅ 配置状态
### 已完成
1. **项目级 MCP 配置已创建**`.claude/settings.json`
2. **MCP 服务器名称**`manulife_API_文档`
3. **Token 验证通过**:APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc
4. **Project ID**:6084040 (当前复用 mlaj 项目)
> **注意**:当前配置使用 mlaj 项目的 Apifox。如果 manulife-weapp 有独立的 Apifox 项目,需要更新 Project ID 和 Token。
---
## 🧪 测试方法
### 方法 1:重启 Claude Code 并直接使用(最简单)
**步骤**
1. **完全退出 Claude Code**(确保重启)
2. **重新启动 Claude Code**
3. **打开 manulife-weapp 项目**
4. **直接提问**
```
"列出 manulife 项目中所有的 API 接口"
```
如果 MCP 配置正确,Claude Code 会:
- 自动连接到 Apifox MCP 服务器
- 获取项目中的 API 列表
- 以结构化的方式展示给你
**其他测试命令**
```
# 搜索特定接口
"搜索 manulife 项目中与用户相关的 API"
# 查看接口详情
"获取用户信息接口的完整信息"
# 生成 API 代码
"基于用户登录接口,生成前端 API 调用代码"
```
---
### 方法 2:查看 MCP 工具列表
在重启 Claude Code 后,你可以在对话中问:
```
"列出当前可用的所有 MCP 工具"
```
应该能看到类似这样的工具:
- `mcp__manulife_api_文档__list_apis` - 列出所有 API
- `mcp__manulife_api_文档__get_api_detail` - 获取 API 详情
- `mcp__manulife_api_文档__search_apis` - 搜索 API
- `mcp__manulife_api_文档__get_project_info` - 项目信息
---
### 方法 3:创建测试脚本
创建 `test-mcp-connection.sh`
```bash
#!/bin/bash
# 检查 MCP 服务器是否能正常启动
echo "🔍 测试 Apifox MCP 服务器连接..."
echo ""
# 设置环境变量
export APIFOX_ACCESS_TOKEN="APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc"
# 测试命令
echo "✅ Token 格式: 正确"
echo "✅ Project ID: 6084040"
echo "✅ MCP 配置文件: .claude/settings.json"
echo ""
echo "📝 配置内容:"
cat .claude/settings.json
echo ""
echo "💡 下一步:"
echo " 1. 重启 Claude Code"
echo " 2. 在对话中问:'列出 manulife 项目所有的 API'"
echo " 3. 如果能看到 API 列表,说明配置成功"
```
运行测试:
```bash
chmod +x test-mcp-connection.sh
./test-mcp-connection.sh
```
---
## 🎯 预期效果
### 如果配置成功
当你问 **"列出 manulife 项目所有的 API"** 时,Claude Code 应该能:
1. **连接到 Apifox**:通过 MCP 服务器
2. **获取 API 列表**:从项目 ID 6084040
3. **结构化展示**:按模块或分类显示
**示例输出**
```
我找到了 manulife 项目中的以下 API 接口:
## 用户模块
- POST /srv/?a=openid_wxapp - 微信登录
- POST /srv/?a=get_user_info - 获取用户信息
- POST /srv/?a=edit_user_info - 编辑用户信息
## 产品模块
- POST /srv/?a=product_list - 获取产品列表
- POST /srv/?a=product_detail - 获取产品详情
## 知识库模块
- POST /srv/?a=knowledge_list - 获取知识列表
- POST /srv/?a=knowledge_detail - 获取知识详情
... (更多接口)
需要查看某个接口的详细信息吗?
```
---
## 🔧 使用独立的 Apifox 项目(可选)
如果 manulife-weapp 有独立的 Apifox 项目:
### 步骤 1:获取 Project ID 和 Token
1. 登录 [Apifox](https://app.apifox.com)
2. 打开 manulife-weapp 项目
3. 从 URL 中获取 Project ID:`https://app.apifox.com/web/project/{PROJECT_ID}/...`
4. 生成 Access Token:设置 → API Tokens → 新建 Token
### 步骤 2:更新配置文件
编辑 `.claude/settings.json`
```json
{
"mcpServers": {
"manulife_API_文档": {
"command": "npx",
"args": [
"-y",
"apifox-mcp-server@latest",
"--project-id=YOUR_PROJECT_ID"
],
"env": {
"APIFOX_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
}
}
}
}
```
### 步骤 3:重启 Claude Code
1. 完全退出 Claude Code
2. 重新启动
3. 测试连接
---
## 🐛 故障排查
### 问题 1:看不到 MCP 工具
**检查步骤**
1. 确认配置文件存在:
```bash
cat .claude/settings.json
```
2. 完全重启 Claude Code(不是重新加载)
3. 查看日志:
```bash
tail -50 ~/Library/Logs/Claude/claude-desktop.log | grep -i mcp
```
### 问题 2:连接超时或失败
**检查步骤**
1. 测试网络连接:
```bash
curl -I https://apifox.com
```
2. 验证 Token:
```bash
# 在浏览器中访问 Apifox,确认 token 有效
```
3. 手动测试 MCP 服务器:
```bash
APIFOX_ACCESS_TOKEN="your_token" \
npx -y apifox-mcp-server@latest --project-id=6084040
```
### 问题 3:工具调用失败
**可能原因**
- Project ID 不匹配
- Token 权限不足
- 项目在 Apifox 中被删除或移动
**解决**
1. 登录 Apifox 确认项目存在
2. 确认 Token 有该项目的访问权限
3. 重新获取正确的 Project ID
---
## 📚 Apifox MCP 服务器功能
根据 Apifox MCP 服务器的标准功能,应该支持:
### 📖 查看功能
- **列出所有 API**:获取项目中的接口列表
- **获取 API 详情**:查看单个接口的完整信息
- **搜索 API**:按名称或路径搜索接口
- **获取项目信息**:项目基本信息
### 🔧 集成功能(可能)
- **发送测试请求**:直接调用 API 测试
- **生成代码**:自动生成前端 API 调用代码
- **导出文档**:导出为 Markdown 或其他格式
---
## 🚀 高级用法
### 1. 自动生成 API 代码
配置成功后,可以快速生成前端 API 代码:
```
"基于 manulife 项目的用户登录接口,
生成 src/api/user.js 文件,
使用 axios,遵循项目规范"
```
### 2. 批量生成接口文档
```
"为 manulife 项目生成完整的 API 文档,
包括所有接口的请求参数和响应格式"
```
### 3. 接口变更检测
```
"对比 manulife 项目的接口变更,
列出新增和修改的接口"
```
---
## 📝 配置文件说明
### 项目级配置:`.claude/settings.json`
```json
{
"mcpServers": {
"manulife_API_文档": {
"command": "npx",
"args": ["-y", "apifox-mcp-server@latest", "--project-id=6084040"],
"env": {
"APIFOX_ACCESS_TOKEN": "APS-jkT1Q61MCKgzgvfCL2euIR2TcgKsnSyc"
}
}
}
}
```
### 环境变量
- `APIFOX_ACCESS_TOKEN`: Apifox 访问令牌
- `PROJECT_ID`: 项目 ID (当前为 6084040)
---
## 🎉 成功标志
当你看到以下情况时,说明配置成功:
1. ✅ Claude Code 能列出 manulife 项目的 API 接口
2. ✅ 能获取单个接口的详细信息
3. ✅ 能搜索和筛选接口
4. ✅ 能基于接口文档生成代码
---
**最后更新**: 2026-01-30
**MCP 服务器**: apifox-mcp-server@latest
**项目 ID**: 6084040 (复用 mlaj 项目)
**配置状态**: ✅ 完成,等待重启验证
# 如何切换到独立的 Apifox 项目
## 当前状态
**MCP 服务器已配置**,当前复用 **mlaj 项目的 Apifox**(Project ID: 6084040)
---
## 📝 将来切换到独立项目时,修改以下位置
### 位置 1:项目级配置(主要)
**文件路径**`.claude/settings.json`
**修改内容**
```json
{
"mcpServers": {
"manulife_API_文档": {
"command": "npx",
"args": [
"-y",
"apifox-mcp-server@latest",
"--project-id=这里填写新的PROJECT_ID" // 改这里
],
"env": {
"APIFOX_ACCESS_TOKEN": "这里填写新的ACCESS_TOKEN" // 改这里
}
}
}
}
```
### 位置 2:本地权限配置(次要)
**文件路径**`.claude/settings.local.json`
**修改内容**
找到这一行:
```json
"Bash(APIFOX_ACCESS_TOKEN=\"旧的TOKEN\" npx -y apifox-mcp-server@latest --project-id=旧的PROJECT_ID:*)",
```
替换为:
```json
"Bash(APIFOX_ACCESS_TOKEN=\"新的TOKEN\" npx -y apifox-mcp-server@latest --project-id=新的PROJECT_ID:*)",
```
---
## 🔑 如何获取新的 Project ID 和 Token
### 步骤 1:获取 Project ID
1. 登录 [Apifox](https://app.apifox.com)
2. 打开 manulife-weapp 项目
3. 从 URL 中复制 Project ID:
```
https://app.apifox.com/web/project/{PROJECT_ID}/apis/api-xxxxx
↑ 这里就是 Project ID
```
### 步骤 2:生成 Access Token
1. 在 Apifox 中,点击 **设置****API Tokens**
2. 点击 **新建 Token**
3. 复制生成的 Token(格式类似:`APS-xxxxx`
---
## ✅ 修改后记得
1. **保存文件**
2. **完全退出 Claude Code**
3. **重新启动 Claude Code**
4. **测试连接**
```
"列出 manulife 项目中所有的 API 接口"
```
---
**快速参考**
- 主配置文件:`.claude/settings.json`(第 8 行和第 11 行)
- 权限文件:`.claude/settings.local.json`(第 49 行)