apifox-workspace-mcp

v2.0.8

Published

6 days ago

Workspace-level Apifox MCP Server for intelligent API documentation integration in Cursor AI

0High
0Medium
0Low

zhengkuo

mcp mcp-server model-context-protocol apifox api-documentation api cursor cursor-ai typescript code-generation

Apifox Workspace MCP

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

✨ 核心特性

🗂️ 多项目管理

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

🔍 智能接口查询

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

🛠️ 代码自动生成

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

💾 智能缓存系统

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

📦 安装

方式 1：通过 npx（推荐）

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

{
  "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"
      }
    }
  }
}

方式 2：全局安装

npm install -g apifox-workspace-mcp

配置示例：

{
  "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：从源码运行

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

配置示例：

{
  "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"
      }
    }
  }
}

⚙️ 配置说明

必需配置

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

可选配置

APIFOX_API_BASE_URL（可选）
- 自定义 API 基础地址
- 默认：https://api.apifox.com
- 私有部署时需要配置
LOG_LEVEL（可选）
- 日志级别：debug | info | warn | error
- 默认：info

💡 工作原理

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

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

无需操心：

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

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

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

🚀 快速开始

1️⃣ 添加项目

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

2️⃣ 查询接口

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

3️⃣ 查看详情

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

4️⃣ 生成代码

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

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

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

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

5️⃣ 批量选择接口

查询接口列表后，每个接口都有编号标识（如 ☑️ [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       ↳ 所有共享类型

架构优势

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

详细架构：📙 docs/architecture.md

📚 可用工具

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

🧪 开发指南

本地开发

# 克隆仓库
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

添加新功能

添加新的 MCP 工具
- 在 src/server/handlers/ 创建 handler
- 在 src/server/handlers/index.ts 导出
- 在 src/server/index.ts 注册工具
添加核心功能
- 在 src/core/ 相应子模块中添加
- 在子模块 index.ts 中导出
添加工具函数
- 在 src/lib/ 中添加
- 在 src/lib/index.ts 中导出

测试覆盖

# 运行测试
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！

开发流程

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

提交规范

遵循 Conventional Commits：

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

代码规范

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

🐛 问题反馈

遇到问题？请查看：

📄 许可证

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

🔗 相关资源

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

🌟 Star History

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

Made with ❤️ by Apifox Team

报告问题 · 功能建议 · 贡献代码