# 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 配置详细说明
```