Apifox Workspace MCP


> 🚀 工作空间级别的 Apifox MCP Server，为 Cursor AI 提供智能 API 文档集成能力

✨ 核心特性

$3

- 📋 统一管理工作空间中的所有 Apifox 项目
- 🔗 一键解析分享链接，自动添加项目配置
- 💾 智能维护统一缓存（.cursor/tmp/apifox-interfaces-cache.json）

$3

- 🔎 关键词搜索，快速定位目标接口
- 🏷️ 标签筛选，按模块分类查看
- 📄 完整接口详情（请求参数、响应结构、示例代码）

$3

- 📝 TypeScript 类型定义 - 自动生成请求/响应类型
- 🎭 Mock 数据 - 基于接口规范生成测试数据
- 🔌 请求封装 - 生成类型安全的 API 调用函数
- 🧪 测试脚本 - 生成单元测试模板

$3

- 🚀 本地缓存接口信息，减少 API 调用
- ⚡ 优先使用缓存，大幅降低 Token 消耗
- 🔄 自动更新缓存，确保数据最新

📦 安装

$3

最简单的使用方式，无需安装：

``json
{
"mcpServers": {
"apifox-workspace-mcp": {
"command": "npx",
"args": ["-y", "apifox-workspace-mcp"],
"env": {
"APIFOX_ACCESS_TOKEN": "your_apifox_access_token",
"APIFOX_API_BASE_URL": "https://api.apifox.com"
}
}
}
}
`

$3

`bash
npm install -g apifox-workspace-mcp
`

配置示例：

`json
{
"mcpServers": {
"apifox-workspace-mcp": {
"command": "apifox-workspace-mcp",
"env": {
"APIFOX_ACCESS_TOKEN": "your_apifox_access_token",
"APIFOX_API_BASE_URL": "https://api.apifox.com"
}
}
}
}
`

$3

`bash
git clone https://github.com/apifox/apifox-workspace-mcp.git
cd apifox-workspace-mcp
npm install
npm run build
`

配置示例：

`json
{
"mcpServers": {
"apifox-workspace-mcp": {
"command": "node",
"args": ["/path/to/apifox-workspace-mcp/dist/server/index.js"],
"env": {
"APIFOX_ACCESS_TOKEN": "your_apifox_access_token",
"APIFOX_API_BASE_URL": "https://api.apifox.com"
}
}
}
}
`

⚙️ 配置说明

$3

- APIFOX_ACCESS_TOKEN（必需）
- 你的 Apifox Access Token
- 获取方式：Apifox → 个人设置 → Access Tokens

$3

- APIFOX_API_BASE_URL（可选）
- 自定义 API 基础地址
- 默认：https://api.apifox.com
- 私有部署时需要配置

- LOG_LEVEL（可选）
- 日志级别：debug | info | warn | error
- 默认：info

$3

使用 npx apifox-workspace-mcp 时的执行流程：

1. ✅ npx 从 npm 仓库下载包（包含编译后的 dist/ 目录）
2. ✅ 执行 dist/server/index.js（无需构建）
3. ✅ MCP Server 启动并连接到 Cursor

无需操心：

- ❌ 克隆 Git 仓库
- ❌ 安装 TypeScript 或构建工具
- ❌ 运行 npm run build

> 📝 说明：dist/ 目录不在 Git 仓库中（开发者不提交编译产物），但会自动包含在 npm 包中（用户下载即用）。详见 分发机制说明

详细配置指南：📘 docs/setup.md

🚀 快速开始

$3

`
@apifox 添加项目：https://apifox.advai.net/apidoc/shared/xxx
`

$3

`
@apifox 列出所有项目
@apifox 搜索支付接口
@apifox 查询 mboss-backend 项目的退款接口
`

$3

`
@apifox 告诉我退款接口的详情
@apifox 显示接口 api-12345 的完整信息
`

$3

`typescript
// 生成 TypeScript 类型
@apifox 帮我生成退款接口的 TypeScript 类型

// 生成 Mock 数据
@apifox 生成 Mock 数据

// 生成请求封装
@apifox 生成请求封装函数

// 保存到文件
@apifox 生成类型并保存到 src/api/types.ts
`

$3

查询接口列表后，每个接口都有编号标识（如 ☑️ [1]），你可以通过以下方式选择：

方式一：按编号选择
- 选择接口 1, 3, 5（选择多个）
- 选择接口 1-5（选择范围）
- 选择接口 1, 3, 5-10（混合选择）

方式二：按关键词选择
- 选择包含"支付"的接口
- 选择包含"退款"和"订单"的接口

方式三：按名称选择
- 选择"退款接口"和"支付接口"

选择完成后，说 生成这些接口的类型 即可批量生成。

更多示例：📗 docs/usage.md

🏗️ 项目架构

采用清晰的分层架构，遵循 MCP Server 最佳实践：

`
src/
├── server/ 🟦 MCP Server 层（协议交互）
│ ├── index.ts ↳ Server 主入口（309 行，精简 68%）
│ └── handlers/ ↳ 7 个工具处理器
│
├── core/ 🟩 核心业务逻辑层（与 MCP 无关）
│ ├── config/ ↳ 配置管理
│ ├── client/ ↳ API 客户端（REST + MCP）
│ ├── parser/ ↳ URL 解析器
│ ├── generator/ ↳ 代码生成器
│ └── ... ↳ 上下文、意图识别
│
├── lib/ 🟨 基础设施层（通用工具）
│ ├── logger.ts ↳ 日志系统
│ ├── errors.ts ↳ 错误类
│ └── ... ↳ 环境变量、工具函数
│
└── types/ 🟪 类型定义层
└── index.ts ↳ 所有共享类型
`

$3

- ✅ 模块化：27 个模块文件，职责清晰，易于维护
- ✅ 类型安全：100% TypeScript，零 any 类型
- ✅ 可测试：完整的单元测试覆盖（11 个测试）
- ✅ 低耦合：清晰的依赖方向，避免循环依赖

详细架构：📙 docs/architecture.md

📚 可用工具

| 工具 | 描述 | 使用场景 |
|------|------|----------|
| 工具 | 描述 | 使用场景 |
|------|------|----------|
| list_projects | 列出所有集成的项目 | 查看已配置的项目列表 |
| parse_and_add_project | 解析分享链接并添加项目 | 快速集成新项目 |
| query_interfaces | 查询项目接口列表 | 搜索、浏览接口 |
| get_interface_detail | 获取接口详细信息 | 查看完整接口文档 |
| generate_artifacts | 生成代码产物 | 自动生成类型、Mock、测试 |
| select_interfaces | 选择多个接口 | 批量操作接口 |

🧪 开发指南

$3

`bash


克隆仓库

git clone https://github.com/apifox/apifox-workspace-mcp.git
cd apifox-workspace-mcp

安装依赖

npm install

开发模式（监听文件变化）

npm run dev

构建项目

npm run build

运行测试

npm run test

代码检查

npm run lint

格式化代码

npm run format

类型检查

npm run typecheck
`

$3

1. 添加新的 MCP 工具
- 在 src/server/handlers/ 创建 handler
- 在 src/server/handlers/index.ts 导出
- 在 src/server/index.ts 注册工具

2. 添加核心功能
- 在 src/core/ 相应子模块中添加
- 在子模块 index.ts 中导出

3. 添加工具函数
- 在 src/lib/ 中添加
- 在 src/lib/index.ts 中导出

$3

`bash


运行测试

npm run test

监听模式

npm run test:watch

生成覆盖率报告

npm run test -- --coverage
`

当前测试状态：

- ✅ 30/30 测试通过 (100% 通过率)
- ✅ 6 个测试文件
- ✅ 覆盖核心模块：logger、types、url-parser、select-interfaces、unified-cache-manager、llms-parser

📊 项目指标

| 指标 | 数值 |
|------|------|
| TypeScript 文件 | 30+ 个 |
| 模块数量 | 27 个 |
| 单元测试 | 30 个（100% 通过）|
| 测试文件 | 6 个 |
| 类型安全 | 零 any 类型 |
| 代码规范 | ESLint + Prettier |

🛠️ 技术栈

- 运行时: Node.js >= 20
- 语言: TypeScript 5.3+
- 协议: Model Context Protocol (MCP) 0.5.0
- HTTP 客户端: Axios 1.7+
- 测试框架: Vitest 2.1+
- 代码规范: ESLint 9+ + Prettier 3+

📖 完整文档

- 📘 配置指南 - 详细的安装和配置步骤
- 📗 使用指南 - 各种使用场景和示例
- 📙 架构设计 - 项目架构和设计原则
- 📕 发布指南 - npm 发布流程
- 🎯 功能详细介绍 - 完整的功能介绍、逻辑流程和使用方式
- 💾 缓存结构说明 - 缓存文件结构和 Token 消耗优化
- 🧪 本地测试指南 - 开发测试流程

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

$3

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'feat: add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交 Pull Request

$3

遵循 Conventional Commits：

- feat: - 新功能
- fix: - 修复 Bug
- docs: - 文档更新
- style: - 代码格式化
- refactor: - 重构
- test: - 测试相关
- chore: - 构建/工具相关

$3

- ✅ 遵循 ESLint 规则
- ✅ 使用 Prettier 格式化
- ✅ 为新功能添加测试
- ✅ 更新相关文档
- ✅ 保持类型安全（避免 any`）

🐛 问题反馈

遇到问题？请查看：

1. 常见问题
2. Issues

📄 许可证

MIT License - 自由使用、修改和分发

🔗 相关资源

- Apifox 官网 - API 设计、开发、测试一体化平台
- MCP Protocol - Model Context Protocol 官方文档
- Cursor AI - 智能 AI 代码编辑器
- GitHub Repository - 项目源码

🌟 Star History

如果这个项目对你有帮助，请给我们一个 ⭐️ Star！

---