Apifox MCP

# Apifox MCP 服务器 **让 AI 助手自动管理你的 Apifox API 文档！** 这是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器，允许 Claude Desktop、Claude Code、Cursor 等 MCP 客户端通过 Apifox Open API 自动导入 OpenAPI/Swagger 规范到你的 Apifox 项目。 ## ✨ 主要功能 - ✅ **API 导入**：批量导入 OpenAPI/Swagger 规范到 Apifox（稳定可靠） - ✅ **API 导出**：支持 Summary（目录结构）和 Full（完整规范）两种模式 - ✅ **智能废弃标记**：自动检测并标记已删除的接口为废弃状态（v1.2.1） - ✅ **部分模块导入**：支持只导入部分模块，不影响其他模块（智能范围检测） - ✅ **多格式支持**：支持 OpenAPI 3.0/3.1 和 Swagger 2.0 - ✅ **详细统计**：完整的导入/导出统计信息和错误报告 ## 🚀 快速开始 ### 1. 安装 #### 方式 1: 使用 npx（推荐） 无需安装，直接使用最新版本： ```bash npx -y apifox-openapi-mcp@latest --token "YOUR_TOKEN" --project-id "YOUR_PROJECT_ID" ``` #### 方式 2: 本地安装 ```bash # 克隆仓库 git clone https://github.com/yourusername/apifox-mcp.git cd apifox-mcp # 安装依赖 npm install # 构建 npm run build # 本地链接（可选，用于全局使用） npm link ``` ### 2. 获取 API Token 和项目 ID **步骤：** 1. **获取 Token**：登录 Apifox → 头像 → 账号设置 → API 访问令牌 → 新建令牌 2. **获取 Project ID**：打开项目 → 项目设置 → 基本设置 → 复制项目 ID ### 3. 配置 MCP 客户端 #### 3.1 Claude Desktop 编辑 Claude Desktop 配置文件： - **Linux/Mac**: `~/.config/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` #### 方式 1: 使用 npx（推荐，总是使用最新版本） ```json { "mcpServers": { "apifox": { "command": "npx", "args": [ "-y", "apifox-openapi-mcp@latest", "--token", "你的-APIFOX-TOKEN", "--project-id", "你的-项目-ID" ] } } } ``` #### 方式 2: 本地安装（使用绝对路径） ```json { "mcpServers": { "apifox": { "command": "node", "args": [ "/绝对路径/apifox-mcp/dist/index.js", "--token", "你的-APIFOX-TOKEN", "--project-id", "你的-项目-ID" ] } } } ``` #### 方式 3: 使用 npm link 后 ```json { "mcpServers": { "apifox": { "command": "apifox-mcp", "args": [ "--token", "你的-APIFOX-TOKEN", "--project-id", "你的-项目-ID" ] } } } ``` #### 3.2 Claude Code **方式 1: 使用 CLI 命令（推荐）** ```bash # 添加 MCP 服务器 claude mcp add apifox # 按提示输入配置 # Command: npx # Args: -y apifox-openapi-mcp@latest --token "你的-TOKEN" --project-id "你的-项目-ID" # 验证配置 claude mcp list ``` **方式 2: 直接编辑配置文件** 编辑 `~/.config/Claude/claude_desktop_config.json`（与 Claude Desktop 共享配置文件）： ```json { "mcpServers": { "apifox": { "command": "npx", "args": [ "-y", "apifox-openapi-mcp@latest", "--token", "你的-APIFOX-TOKEN", "--project-id", "你的-项目-ID" ] } } } ``` 重启 Claude Code 后生效。 #### 3.3 Cursor **步骤：** 1. 打开 Cursor 设置：`Cursor Settings` > `Features` > `MCP` 2. 点击 `+ Add New MCP Server` 按钮 3. 填写配置信息： - **Name**: `apifox` - **Command**: `npx` - **Args**: ``` -y apifox-openapi-mcp@latest --token 你的-APIFOX-TOKEN --project-id 你的-项目-ID ``` - **Transport**: `stdio` 4. 保存配置 **使用提示**： - Cursor 的 Composer Agent 会自动使用 MCP 工具 - 最多支持 40 个 MCP 工具 - 给出明确指令时效果最佳，例如："请使用 Apifox 工具导入这个 API" ### 4. 重启客户端 完全退出并重新打开对应的 MCP 客户端（Claude Desktop / Claude Code / Cursor），MCP 服务器会自动加载。 ### 📌 版本管理说明 **为什么使用 `@latest`？** - ✅ **总是使用最新版本** - 自动获取最新功能和修复 - ✅ **无需手动更新** - npx 会自动下载最新版本 - ✅ **避免缓存问题** - 配合 `-y` 参数跳过确认 **查看当前版本：** ```bash # 查看 npx 使用的版本 npx -y apifox-openapi-mcp@latest --version # 查看 npm 上的最新版本 npm view apifox-openapi-mcp version # 查看全局安装的版本 npm list -g apifox-openapi-mcp ``` **其他版本管理方式：** 1. **指定具体版本**（适合生产环境）： ```json "args": ["-y", "apifox-openapi-mcp@1.3.1", ...] ``` 2. **全局安装**（更快的启动速度）： ```bash npm install -g apifox-openapi-mcp ``` 然后在配置中使用 `"command": "apifox-mcp"` ## 📖 使用方法 ### 在 MCP 客户端中使用 与 AI 助手（Claude Desktop / Claude Code / Cursor）对话，它会自动调用 MCP 工具： ``` 你: 帮我创建一个用户管理 API 并导入到 Apifox Claude: 好的，我为你创建一个用户管理 API... [自动生成 OpenAPI 规范] [自动调用 import_openapi 工具] ✅ OpenAPI 规范导入完成！ 📋 接口导入统计： - 创建: 4 - 更新: 0 - 失败: 0 - 忽略: 0 🎉 成功导入 4 个项！ ``` ## 🔧 可用工具 ### 1. `import_openapi` - API 导入（推荐） 使用 Apifox Open API 批量导入 OpenAPI/Swagger 规范。**稳定可靠，推荐使用。** **参数**： - `spec` (必需): OpenAPI/Swagger 规范对象（必须包含 `openapi`/`swagger`、`info`、`paths` 字段） - `options` (可选): 导入选项 - `endpointOverwriteBehavior`: 接口覆盖行为 - `OVERWRITE_EXISTING` (默认): 覆盖现有接口 - `AUTO_MERGE`: 自动合并 - `KEEP_EXISTING`: 保留现有 - `CREATE_NEW`: 创建新接口 - `schemaOverwriteBehavior`: 数据模型覆盖行为（同上） - `markDeprecatedEndpoints`: 自动标记废弃接口（**v1.2.1 新增**） - `true`: 启用智能废弃标记（**强烈推荐**） - `false`: 不标记（默认） - **工作原理**： 1. 导出现有接口 2. 智能检测导入范围（如只导入 `/api/marketing` 模块） 3. 只对比该范围内的接口 4. 标记已删除的接口为 `deprecated` - **支持部分模块导入**，不会误标记其他模块 - `updateFolderOfChangedEndpoint`: 是否更新修改接口的目录（默认：`false`） - `prependBasePath`: 是否添加 `basePath` 前缀到路径（默认：`false`） - `targetBranchId`: 目标分支 ID（可选，用于多分支项目） **示例 1：基础导入** ```json { "spec": { "openapi": "3.0.0", "info": { "title": "用户管理 API", "version": "1.0.0" }, "paths": { "/users": { "get": { "summary": "获取用户列表", "tags": ["用户管理"], "responses": { "200": { "description": "成功" } } } } } }, "options": { "endpointOverwriteBehavior": "OVERWRITE_EXISTING" } } ``` **示例 2：启用智能废弃标记（推荐）** ```json { "spec": { "openapi": "3.0.0", "info": { "title": "营销模块 API", "version": "2.0.0" }, "paths": { "/api/marketing/campaigns": { "get": { "summary": "获取营销活动列表", "tags": ["营销活动"], "responses": { "200": { "description": "成功" } } } } } }, "options": { "endpointOverwriteBehavior": "OVERWRITE_EXISTING", "markDeprecatedEndpoints": true } } ``` **说明**： - 导入时会自动检测范围为 `/api/marketing` - 只标记该范围内已删除的接口为废弃 - 不会影响 `/api/users`、`/api/products` 等其他模块 **返回结果**： ``` ✅ OpenAPI 规范导入完成！ 📋 接口导入统计： - 创建: 4 - 更新: 0 - 失败: 0 - 忽略: 0 📦 数据模型导入统计： - 创建: 2 - 更新: 0 - 失败: 0 - 忽略: 0 🎉 成功导入 6 个项！ ``` ### 2. `export_openapi` - API 导出 从 Apifox 项目导出 OpenAPI/Swagger 规范。**AI 可以使用此工具查看现有接口，避免重复创建或参考现有风格。** **参数**： - `mode` (可选): 导出模式 - `summary`: 仅导出目录结构和接口列表（**推荐，节省上下文**） - `full`: 导出完整的 OpenAPI 规范（默认） - `oasVersion` (可选): OpenAPI/Swagger 版本（仅 `full` 模式有效） - `2.0`: Swagger 2.0 - `3.0`: OpenAPI 3.0（默认） - `3.1`: OpenAPI 3.1 - `exportFormat` (可选): 导出格式（仅 `full` 模式有效） - `JSON`: JSON 格式（默认） - `YAML`: YAML 格式 - `pathFilter` (可选): 路径过滤器，只导出匹配的接口路径（支持前缀匹配） - 示例：`"/api/user"` 只导出用户相关接口 **示例 1：Summary 模式（推荐）** ```json { "mode": "summary" } ``` **返回结果**： ``` ✅ 接口文档概览（Summary 模式） 📊 统计信息： - 项目标题: 我的 API 项目 - 总接口数: 26 📁 目录结构和接口列表： 📂 用户管理 └─ [GET] /api/users 获取用户列表 └─ [POST] /api/users 创建用户 📂 商品管理 └─ [GET] /api/products 获取商品列表 💡 提示： - 导入新接口时，请参考上述目录结构 - 将相关接口放入对应的目录（使用 tags 字段） ``` **示例 2：Full 模式 + 路径过滤** ```json { "mode": "full", "oasVersion": "3.0", "exportFormat": "JSON", "pathFilter": "/api/user" } ``` **返回结果**： ``` ✅ OpenAPI 规范导出成功（Full 模式） 📊 导出统计： - OpenAPI 版本: 3.0.1 - 项目标题: 我的 API 项目 - 接口数量: 2（已按 pathFilter 过滤） - 数据模型数量: 1 📋 接口列表： - /api/user [GET, POST] - /api/user/{id} [GET, PUT, DELETE] 📄 完整 OpenAPI 规范： { "openapi": "3.0.1", "info": { "title": "我的 API 项目", "version": "1.0.0" }, "paths": { "/api/user": {...}, "/api/user/{id}": {...} }, "components": { "schemas": { "User": {...} } } } ``` ## 💡 使用场景 ### 场景 1：首次创建 API 文档 ``` 你: 帮我创建一个用户管理 API，包括 CRUD 操作 AI: [生成 OpenAPI 规范] [调用 import_openapi] ✅ 成功创建 4 个接口 ``` ### 场景 2：更新部分模块 + 自动标记废弃接口 ``` 你: 更新营销模块 API，移除优惠券接口，改用积分系统 AI: [先调用 export_openapi mode=summary 查看现有结构] [生成新的营销模块规范] [调用 import_openapi 并启用 markDeprecatedEndpoints] 🔍 检测到导入范围: /api/marketing 🔖 标记了 1 个废弃接口路径（优惠券相关） ✅ 其他模块（用户、商品）保持不变 ``` ### 场景 3：查看现有接口避免重复 ``` 你: 帮我添加商品搜索功能 AI: [先调用 export_openapi mode=summary] 发现项目中已有 /api/products/search 接口 我可以参考现有的接口风格来设计新功能... ``` ## 📊 API 响应格式 导入成功后会返回详细的统计信息： ```json { "data": { "counters": { "endpointCreated": 4, // 创建的接口数 "endpointUpdated": 0, // 更新的接口数 "endpointFailed": 0, // 失败的接口数 "endpointIgnored": 0, // 忽略的接口数 "schemaCreated": 2, // 创建的数据模型数 "schemaUpdated": 0, // 更新的数据模型数 "schemaFailed": 0, // 失败的数据模型数 "schemaIgnored": 0 // 忽略的数据模型数 // ... 其他计数 }, "errors": [] // 错误信息（如果有） } } ``` ## ⚙️ 命令行使用 你也可以直接从命令行运行 MCP 服务器： ```bash # 方式 1: 使用命令行参数 node dist/index.js --token "YOUR_TOKEN" --project-id "YOUR_PROJECT_ID" # 方式 2: 使用环境变量 export APIFOX_TOKEN="YOUR_TOKEN" export APIFOX_PROJECT_ID="YOUR_PROJECT_ID" node dist/index.js # 可选参数 node dist/index.js \ --token "YOUR_TOKEN" \ --project-id "YOUR_PROJECT_ID" \ --base-url "https://api.apifox.com" ``` ## 🛠 技术栈 - **TypeScript** - 类型安全的开发 - **MCP SDK** - Model Context Protocol 实现 - **Apifox Open API** - 官方 API 接口 - **Axios** - HTTP 客户端 ## 🔗 关于 Apifox Open API 本项目使用 [Apifox Open API](https://apifox-openapi.apifox.cn/) 官方接口，经过充分测试，以下功能稳定可用： | 功能 | API 端点 | 状态 | 说明 | |-----|---------|------|------| | 导入 OpenAPI | `POST /v1/projects/{projectId}/import-openapi` | ✅ 稳定 | 支持批量导入、覆盖策略、废弃标记 | | 导出 OpenAPI | `POST /v1/projects/{projectId}/export-openapi` | ✅ 稳定 | 支持多版本、过滤、格式选择 | **版本支持**： - OpenAPI 3.0.x ✅ - OpenAPI 3.1.x ✅ - Swagger 2.0 ✅ ## 📝 开发 ```bash # 安装依赖 npm install # 开发模式（自动重新编译） npm run watch # 构建 npm run build # 清理构建产物 npm run clean ``` ## 🐛 故障排除 ### 问题：Claude Desktop 看不到工具 **解决方案**： 1. 检查配置文件路径和格式是否正确 2. 确保使用绝对路径 3. 完全退出并重启 Claude Desktop（不是最小化） ### 问题：导入失败 **可能原因**： 1. Token 或项目 ID 不正确 2. OpenAPI 规范格式不完整 3. 网络连接问题 **解决方案**： - 检查 Token 和项目 ID 是否正确 - 验证 OpenAPI 规范是否包含必需字段（openapi/swagger, info, paths） - 查看错误信息了解具体原因 ### 问题：导入后没有创建任何内容 **可能原因**： - 项目中已存在相同的 API（被设置为忽略） **解决方案**： - 修改 API 的路径或名称 - 使用 `endpointOverwriteBehavior: "OVERWRITE_EXISTING"` 选项覆盖现有接口 - 在 Apifox Web 界面检查导入结果 ### 问题：导出失败或返回空数据 **可能原因**： - 项目中没有接口 - Token 权限不足 **解决方案**： - 检查项目中是否有接口 - 确认 Token 有读取权限 ## 📚 相关文档 - [Apifox Open API 文档](https://apifox-openapi.apifox.cn/) - [导入 OpenAPI 文档](https://apifox-openapi.apifox.cn/api-173409873) - [导出 OpenAPI 文档](https://apifox-openapi.apifox.cn/api-173411997) - [Model Context Protocol](https://modelcontextprotocol.io) ## 📄 许可证 MIT License ## 🤝 贡献 欢迎提交 Issue 和 Pull Request！ 如果你发现了更多可用的 Apifox Open API 端点，欢迎分享。 --- **Made with ❤️ for the Apifox community**