# Apifox MCP 服务器
这是一个 MCP（Model Context Protocol）服务器，实现了一个可以将 OpenAPI、Swgger 格式的 JSON 数据导入到 Apifox 项目中的工具。
## 功能特性
- 📡 **Apifox 导入工具**: 将 OpenAPI 3、Swagger 2 格式的 JSON 数据导入到 Apifox 项目中
## 安装依赖
```bash
pip install -r requirements.txt
```
## MCP 服务器配置
### 1. 启动服务器
有两种方式启动服务器：
**方式一：直接启动**
```bash
python main.py
```
**方式二：使用启动脚本**
```bash
./start_server.sh
```
### 2. MCP 客户端配置
#### Claude Desktop 配置
在 Claude Desktop 的配置文件中添加服务器配置：
**macOS 配置文件位置：** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows 配置文件位置：** `%APPDATA%\Claude\claude_desktop_config.json`
**配置示例：**
```json
{
"mcpServers": {
"apifox-mcp-server": {
"command": "python",
"args": ["/path/to/your/apifox-mcp-server/main.py"],
"env": {
"APIFOX_TOKEN": "your-apifox-token",
"APIFOX_PROJECT_ID": "your-project-id"
}
}
}
}
```
> 💡 **提示：** 完整的配置示例和说明请参考项目中的 `mcp_config_example.json` 和 `MCP_CONFIG_README.md` 文件
#### 其他 MCP 客户端配置
对于其他支持 MCP 的客户端，请参考相应客户端的文档配置 stdio 连接：
```bash
python /path/to/apifox-mcp-server/main.py
```
### 3. 验证配置
配置完成后，重启 MCP 客户端，您应该能够看到 `import_api` 工具可用。
### 4. 环境变量配置
在 MCP 配置文件的 `env` 字段中设置以下环境变量：
| 环境变量 | 必需 | 说明 |
| ------------------- | ---- | --------------------------------- |
| `APIFOX_TOKEN` | 是 | Apifox API 访问令牌 |
| `APIFOX_PROJECT_ID` | 否 | 默认项目 ID（可在工具调用时覆盖） |
### 5. 项目路径配置
请确保在配置文件中使用绝对路径，例如：
- **正确：** `/Users/username/projects/apifox-mcp-server/main.py`
- **错误：** `./main.py` 或 `main.py`
## 使用方法
### 工具说明
#### `import_api`
调用工具，将 OpenAPI 3、Swagger 2 格式的 JSON 数据导入到指定的 Apifox 项目中。
**参数：**
- `project_id` (可选): Apifox 项目 ID，优先使用环境变量 `APIFOX_PROJECT_ID`
- `input` (必需): 要导入的 OpenAPI 3 或 Swagger 2 格式的 JSON 字符串数据（需要转义）
- `headers` (可选): HTTP 请求头，`Authorization` 自动从环境变量 `APIFOX_TOKEN` 添加
- `timeout` (可选): 请求超时时间，默认 30 秒
**配置环境变量后的简化使用：**
```json
{
"input": "{\"swagger\": \"2.0\", \"info\": {\"title\": \"API文档\", \"version\": \"1.0.0\"}, \"paths\": {...}}"
}
```
**完整参数使用（覆盖环境变量）：**
```json
{
"project_id": "specific-project-id",
"input": "{\"swagger\": \"2.0\", \"info\": {\"title\": \"API文档\", \"version\": \"1.0.0\"}, \"paths\": {...}}",
"headers": {
"Authorization": "Bearer specific-token"
},
"timeout": 60
}
```
**重要说明：**
- 优先使用环境变量配置，简化工具调用
- `Authorization` 格式为 `Bearer {token}`，从环境变量 `APIFOX_TOKEN` 自动添加
- `X-Apifox-Api-Version: 2024-03-28` 会自动添加，无需手动指定
- 支持 OpenAPI 3.0+ 和 Swagger 2.0 格式
## API Token 配置
### 获取 Apifox API Token
1. 登录 [Apifox](https://www.apifox.cn/)
2. 点击右上角头像，进入「账号设置」
3. 在左侧菜单中选择「API 访问令牌」
4. 点击「生成新令牌」按钮
5. 输入令牌名称（如：MCP Server）
6. 选择合适的过期时间
7. 点击「生成」并复制生成的 token
8. 在请求头中使用：`Authorization: Bearer {你的token}`
### 获取项目 ID
1. 打开 Apifox 并进入目标项目
2. 在项目设置页面可以找到项目 ID
3. 或者在项目 URL 中获取项目 ID
## 故障排除
### 常见问题
1. **工具不可用**
- 检查 MCP 服务器是否正常启动
- 确认配置文件中的路径是否正确
- 重启 MCP 客户端
2. **认证失败 (401)**
- 检查 API Token 是否正确
- 确认 Token 是否已过期
- 验证 Token 格式：`Bearer {token}`
3. **项目不存在 (404)**
- 检查项目 ID 是否正确
- 确认 Token 是否有该项目的访问权限
4. **JSON 格式错误 (422)**
- 验证输入的 JSON 格式是否正确
- 确认是否为有效的 OpenAPI/Swagger 格式
5. **项目 ID 未提供**
- 检查环境变量 `APIFOX_PROJECT_ID` 是否正确设置
- 或在工具调用时提供 `project_id` 参数
6. **认证信息未提供**
- 检查环境变量 `APIFOX_TOKEN` 是否正确设置
- 或在工具调用时的 `headers` 中提供 `Authorization`
### 调试模式
启动服务器时会显示详细日志，包括：
- API 调用信息
- 请求数据长度
- 响应状态码
- 错误详情
## 项目结构
```
apifox-mcp-server/
├── main.py # 主服务器代码
├── requirements.txt # 依赖管理
├── README.md # 项目说明
├── start_server.sh # 启动脚本
├── test_example.py # 测试示例
├── config_example.json # Swagger 2.0 格式示例
├── mcp_config_example.json # MCP 客户端配置示例
└── MCP_CONFIG_README.md # MCP 配置详细说明
```
