# Apifox Workspace MCP

[![npm version](https://img.shields.io/npm/v/apifox-workspace-mcp)](https://www.npmjs.com/package/apifox-workspace-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node Version](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)

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

## ✨ 核心特性

### 🗂️ 多项目管理

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

### 🔍 智能接口查询

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

### 🛠️ 代码自动生成

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

### 💾 智能缓存系统

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

## 📦 安装

### 方式 1：通过 npx（推荐）

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

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

### 方式 2：全局安装

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

## ⚙️ 配置说明

### 必需配置

- **`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` 时的执行流程：

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

**无需操心**：

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

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

详细配置指南：[📘 docs/setup.md](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
// 生成 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](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](docs/architecture.md)

## 📚 可用工具

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

## 🧪 开发指南

### 本地开发

```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
```

### 添加新功能

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` 中导出

### 测试覆盖

```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+

## 📖 完整文档

- 📘 [配置指南](docs/setup.md) - 详细的安装和配置步骤
- 📗 [使用指南](docs/usage.md) - 各种使用场景和示例
- 📙 [架构设计](docs/architecture.md) - 项目架构和设计原则
- 📕 [发布指南](docs/publishing.md) - npm 发布流程
- 🎯 [功能详细介绍](docs/features.md) - 完整的功能介绍、逻辑流程和使用方式
- 💾 [缓存结构说明](docs/cache-structure.md) - 缓存文件结构和 Token 消耗优化
- 🧪 [本地测试指南](docs/local-testing-guide.md) - 开发测试流程

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

### 开发流程

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

### 提交规范

遵循 [Conventional Commits](https://www.conventionalcommits.org/)：

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

### 代码规范

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

## 🐛 问题反馈

遇到问题？请查看：

1. [常见问题](docs/setup.md#常见问题)
2. [Issues](https://github.com/apifox/apifox-workspace-mcp/issues)

## 📄 许可证

[MIT License](LICENSE) - 自由使用、修改和分发

## 🔗 相关资源

- [Apifox 官网](https://apifox.com) - API 设计、开发、测试一体化平台
- [MCP Protocol](https://modelcontextprotocol.io) - Model Context Protocol 官方文档
- [Cursor AI](https://cursor.sh) - 智能 AI 代码编辑器
- [GitHub Repository](https://github.com/apifox/apifox-workspace-mcp) - 项目源码

## 🌟 Star History

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

---

<div align="center">

**Made with ❤️ by Apifox Team**

[报告问题](https://github.com/apifox/apifox-workspace-mcp/issues) · [功能建议](https://github.com/apifox/apifox-workspace-mcp/issues) · [贡献代码](https://github.com/apifox/apifox-workspace-mcp/pulls)

</div>