apifox-mcp-server-enterprise

v1.0.2

Published

a month ago

Apifox MCP Server for Cursor AI - 支持企业版私有部署的 Model Context Protocol 服务，支持跨项目自动识别接口，智能获取详情，通过 ID 直接查找，AI 视觉验证码识别

0High
0Medium
0Low

teemo.huang

mcp apifox cursor api-documentation model-context-protocol ai-assistant cursor-ai apifox-enterprise auto-detect-project

apifox-mcp-server-enterprise

Apifox MCP Server for Cursor AI - 支持企业版私有部署

让 Cursor AI 直接访问你的 Apifox 企业版接口文档，自动生成 API 代码。支持自动登录、Token 管理、接口搜索等功能。

✨ 功能特性

✅ 自动登录和 Token 管理 - 无需手动获取 Token，自动刷新
✅ 获取项目列表 - 列出所有可访问的 Apifox 项目
✅ 智能搜索接口 - 支持单项目搜索和跨项目自动识别
✅ 智能获取详情 - 搜索结果唯一时自动返回完整接口详情（一步到位）
✅ 响应示例格式化 - 支持 example 格式，方便 AI 理解
✅ 企业版私有部署支持 - 兼容 Apifox 企业版私有服务器

📦 安装

方式 1：使用 npx（推荐，无需安装）

直接在 Cursor 配置中使用 npx，每次自动获取最新版本。

方式 2：全局安装

npm install -g apifox-mcp-server-enterprise

🚀 快速开始

1. 创建配置文件（推荐）

创建 ~/.apifox-mcp-config.json 文件，避免在 mcp.json 中暴露敏感信息：

cat > ~/.apifox-mcp-config.json << 'EOF'
{
  "baseUrl": "http://your-apifox-server.com",
  "account": "your_account",
  "password": "your_password"
}
EOF

重要提示：

⚠️ 将 your-apifox-server.com 替换为你的 Apifox 服务器地址
⚠️ 将 your_account 和 your_password 替换为你的实际账号密码
🔒 配置文件仅存储在本地，不会被提交到代码仓库

2. 配置 Cursor

编辑 ~/.cursor/mcp.json (macOS/Linux) 或 C:\Users\你的用户名\.cursor\mcp.json (Windows)：

使用配置文件（推荐）

{
  "mcpServers": {
    "apifox": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-mcp-server-enterprise@latest",
        "--config",
        "~/.apifox-mcp-config.json"
      ],
      "alwaysAllow": [
        "apifox_login",
        "apifox_get_projects",
        "apifox_search_apis",
        "apifox_get_api_detail"
      ]
    }
  }
}

优势：

✅ 敏感信息不暴露在配置文件中
✅ 配置文件可加入 .gitignore，避免泄露
✅ 多人协作时，每人维护自己的配置文件

使用环境变量（仅供参考）

⚠️ 不推荐：敏感信息会暴露在 mcp.json 中

{
  "mcpServers": {
    "apifox": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-mcp-server-enterprise@latest"
      ],
      "env": {
        "APIFOX_BASE_URL": "http://your-server.com",
        "APIFOX_ACCOUNT": "your_account",
        "APIFOX_PASSWORD": "your_password"
      },
      "alwaysAllow": [
        "apifox_login",
        "apifox_get_projects",
        "apifox_search_apis",
        "apifox_get_api_detail"
      ]
    }
  }
}

3. 重启 Cursor

完全退出 Cursor 后重新打开。

4. 测试

在 Cursor 中输入：

列出所有 Apifox 项目

看到项目列表就成功了！🎉

💡 使用示例

🚀 一步生成 API 代码（推荐方式 - 新功能）

使用智能搜索，自动获取接口详情并生成代码：

根据接口 /photo/album/create 生成 iOS 代码

AI 会自动：

在所有项目中搜索该接口
如果找到唯一匹配，自动获取接口详情
如果找到多个匹配（例如 GET 和 POST 同路径），返回列表供选择
生成 iOS API 代码

性能提升：

搜索结果唯一时：只需 1 次调用（搜索+详情自动合并）
搜索结果多个时：需 2 次调用（先列出选择，再获取详情）

📝 查看接口文档

查看 /photo/share/external/detail 接口的文档

🔍 搜索接口

跨项目搜索（推荐）

不需要知道接口在哪个项目，直接搜索：

搜索 album 相关的接口

返回所有项目中包含 "album" 的接口，并显示所属项目名称。

指定项目搜索

在相册2.0项目中搜索创建相关的接口

🎯 获取接口详情

获取接口 /ugreen/v5/photo/share/external/detail 的信息

🔧 配置说明

配置优先级

配置文件 (--config 参数指定，或默认 ~/.apifox-mcp-config.json)
环境变量 (APIFOX_BASE_URL, APIFOX_ACCOUNT, APIFOX_PASSWORD)

配置文件格式

{
  "baseUrl": "http://your-apifox-server.com",
  "account": "your_account",
  "password": "your_password"
}

参数说明：

baseUrl: Apifox 服务器地址（必填）
account: 登录账号（必填）
password: 登录密码（必填）

安全建议：

🔒 配置文件建议权限设置为 600：chmod 600 ~/.apifox-mcp-config.json
📝 加入 .gitignore，避免提交到版本控制
🔐 不要在公开文档中包含真实的账号密码

alwaysAllow 说明

配置 alwaysAllow 字段可以让 AI 自动调用工具，无需手动授权确认：

| 工具名称 | 说明 | |---------|------| | apifox_login | 登录 Apifox 获取访问令牌 | | apifox_get_captcha | 获取验证码图片（Cursor AI 识别用）| | apifox_submit_captcha | 提交验证码完成登录 | | apifox_get_projects | 获取项目列表 | | apifox_search_apis | 搜索项目中的接口 | | apifox_smart_search | 智能搜索并自动获取详情（推荐） | | apifox_get_api_by_id | 通过 ID 直接获取接口详情 | | apifox_get_api_detail | 获取接口详细信息 |

🤖 Cursor AI 验证码识别

版本 1.2.0 实现了 零成本、零配置 的验证码识别方案，利用 Cursor 自带的 AI 视觉能力。

工作原理

用户请求接口
   ↓
apifox_login 检测 400 状态码
   ↓
apifox_get_captcha 返回清理后的验证码图片
   ↓
Cursor AI 自动识别验证码字符
   ↓
apifox_submit_captcha 提交识别结果
   ↓
登录成功，继续执行 ✓

核心特性

✅ SVG 自动清理 - 智能移除干扰线，识别率 100%
✅ AI 视觉识别 - 利用 Cursor 自带能力，识别率 90%+
✅ 零额外成本 - 无需 API Key，使用 Cursor 订阅
✅ 全自动流程 - Cursor 自动调用 3 个工具完成登录
✅ 用户无感知 - 整个过程 1-2 秒完成

使用示例

正常使用时，Cursor 会自动处理验证码，用户无需关心：

👤 你: "获取接口 /photo/album 的详情"

🤖 Cursor:
   - 调用 apifox_login → 检测需要验证码
   - 调用 apifox_get_captcha → 获取图片
   - 识别验证码: "T4KE"
   - 调用 apifox_submit_captcha → 登录成功
   - 获取接口详情 ✓

详细说明请查看 CURSOR_AI_CAPTCHA.md

🛠️ 可用工具

apifox_login

参数： 无（使用配置文件或环境变量）

apifox_get_projects

获取所有可访问的项目列表。

参数： 无

apifox_smart_search（推荐 - 智能搜索⭐）

智能搜索接口并自动获取详情。

参数：

search_text (string, 必填) - 搜索关键词（支持接口路径、名称）
project_id (string, 可选) - 项目ID，如果不提供则跨所有项目搜索

智能行为：

如果搜索结果唯一（只有1个匹配的接口），自动返回接口的完整详情
如果找到多个匹配接口，返回接口列表供用户选择

使用场景：

✅ 直接生成 API 代码（搜索结果唯一时一步到位）
✅ 查看接口文档
✅ 避免多次调用（节省时间）

示例：

{
  "search_text": "/photo/album/create"
}
// 如果唯一匹配：直接返回详情
// 如果多个匹配：返回列表（例如 GET 和 POST 同路径）

apifox_get_api_by_id（新功能⭐）

通过接口 ID 直接获取接口详情，适用于从 Apifox 分享链接中提取的 ID。

参数：

api_id (string, 必填) - 接口 ID（例如从分享链接中提取的数字）

使用场景：

✅ 从 Apifox 分享链接快速获取接口详情
✅ 已知接口 ID，直接获取详情
✅ 无需提供项目 ID，自动识别

示例：

// 分享链接：http://apifox.ugreencloud.com/apidoc/shared/xxx/api-3476919
{
  "api_id": "3476919"
}
// 自动在所有项目中查找该 ID，返回完整详情

与智能搜索的互补关系： | 工具 | 适用场景 | 输入 | |------|---------|------| | apifox_get_api_by_id | 有 Apifox 分享链接 | 接口 ID | | apifox_smart_search | 知道接口路径/名称 | 路径或名称 |

apifox_search_apis

搜索接口（仅返回列表，不返回详情）。

参数：

project_id (string, 可选) - 项目 ID，如果不提供则自动在所有项目中搜索
search_text (string, 必填) - 搜索关键词（支持接口路径、名称）

示例 1：跨项目搜索（推荐）

{
  "search_text": "/photo/album"
}
// 返回所有项目中匹配的接口，包含 projectId 和 projectName

示例 2：指定项目搜索

{
  "project_id": "345090",
  "search_text": "/photo/album"
}
// 只在指定项目中搜索

优势：

✅ 无需知道接口在哪个项目
✅ 一次搜索，查找所有匹配的接口
✅ 自动识别项目信息
✅ 提高查询效率

apifox_get_api_detail

获取单个接口的详细信息。

参数：

project_id (string, 必填) - 项目 ID
api_id (string, 必填) - 接口 ID
format (string, 可选) - 输出格式
- 'full' - 完整的 API 定义（默认）
- 'example' - 格式化的示例输出（包含 request/response schema 和 example）

📝 示例输出

获取接口详情（example 格式）

{
  "api": {
    "id": 3477315,
    "name": "外部分享获取分享内容的资源列表",
    "method": "get",
    "path": "/ugreen/v5/photo/share/external/detail"
  },
  "request": {
    "headers": [...],
    "parameters": {...},
    "body": {...},
    "example": "..."
  },
  "response": {
    "schema": {...},
    "example": {...}
  }
}

❓ 常见问题

Cursor 看不到 MCP 服务

检查 mcp.json 格式是否正确（使用 https://jsonlint.com/ 验证）
确保完全重启了 Cursor
检查 Node.js 版本 >= 18.0.0

登录失败

检查 baseUrl 是否正确
检查账号密码是否正确
测试网络连通性：ping apifox.ugreencloud.com
查看 Cursor 日志：Help -> Toggle Developer Tools -> Console

首次使用弹出授权提示

如果没有配置 alwaysAllow，首次使用工具时会弹出授权提示。建议：

点击 "Allowlist MCP Tool" 加入白名单，以后不再提示
或在 mcp.json 中添加 alwaysAllow 配置

找不到 Node.js

下载安装：https://nodejs.org/ (选择 LTS 版本)

🔄 更新

使用 npx（自动更新）

如果使用 npx 方式，无需手动更新，每次启动自动获取最新版本。

全局安装更新

npm update -g @ugreen/apifox-mcp-server

查看当前版本

npm list -g @ugreen/apifox-mcp-server

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

提交 Issue: https://github.com/ugreen/apifox-mcp-server/issues
邮件: [email protected]

让 AI 自动生成代码，从接口文档开始！ 🚀

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

apifox-mcp-server-enterprise

✨ 功能特性

📦 安装

方式 1：使用 npx（推荐，无需安装）

方式 2：全局安装

🚀 快速开始

1. 创建配置文件（推荐）

2. 配置 Cursor

使用配置文件（推荐）

使用环境变量（仅供参考）

3. 重启 Cursor

4. 测试

💡 使用示例

🚀 一步生成 API 代码（推荐方式 - 新功能）

📝 查看接口文档

🔍 搜索接口

跨项目搜索（推荐）

指定项目搜索

🎯 获取接口详情

🔧 配置说明

配置优先级

配置文件格式

alwaysAllow 说明

🤖 Cursor AI 验证码识别

工作原理

核心特性

使用示例

🛠️ 可用工具

apifox_login

apifox_get_projects

apifox_smart_search（推荐 - 智能搜索⭐）

apifox_get_api_by_id（新功能⭐）

apifox_search_apis

apifox_get_api_detail

📝 示例输出

获取接口详情（example 格式）

❓ 常见问题

Cursor 看不到 MCP 服务

登录失败

首次使用弹出授权提示

找不到 Node.js

🔄 更新

使用 npx（自动更新）

全局安装更新

查看当前版本

📄 许可证

🤝 贡献

📞 支持