foxy-mcp

v1.0.4

Published

2 months ago

智能Apifox MCP中转服务器 - 支持多项目、智能缓存、团队协作

0High
0Medium
0Low

goozyshi

apifox mcp model-context-protocol api-bridge cursor openapi multi-project api-documentation mock-server api-testing

🦊 Foxy MCP

让 AI 助手无缝访问 Apifox 接口文档

一个智能的 MCP (Model Context Protocol) 服务器，专为 Cursor 打造，支持：

✅ 读取 Apifox 接口文档（OpenAPI 3.1 规范）
✅ 智能缓存系统（混合内存+磁盘持久化）
✅ Mock 数据生成（支持真实数据混合）
✅ HTTP / CLI 双模式运行
✅ 交互式初始化向导

🚀 快速开始

一键初始化（推荐）

# 1. 克隆并安装
git clone <repo-url>
cd foxy-mcp
pnpm install

# 2. 构建项目
pnpm build

# 3. 运行交互式向导
pnpm intro

向导会自动完成：

选择鉴权方式（API Key / Cookie Token）
配置默认项目 ID
选择运行模式（HTTP 常驻服务 / CLI 自动管理）
生成 .env 配置文件
输出 MCP 配置（手动复制到 ~/.cursor/mcp.json）

示例流程：

🦊 Foxy MCP 初始化向导

? 选择鉴权方式: API Key（Apifox 开发者令牌，需要 apifox 权限管理员以上）
? 请输入 Apifox API Key: ••••••••
? 是否配置默认项目ID？ Yes
? 请输入项目ID: 31890xx
? 选择运行模式: HTTP模式（团队共享，常驻后台）
? 服务端口: 3000

✅ 配置已保存到 .env

📋 复制以下配置到 ~/.cursor/mcp.json:
{
  "mcpServers": {
    "foxy-mcp": {
      "url": "http://localhost:3000/sse"
    }
  }
}

🚀 下一步:
  1. 启动服务: pnpm start
  2. 复制配置到 ~/.cursor/mcp.json
  3. 重启 Cursor

手动配置（可选）

特点：

无需后台服务，Cursor 自动启动和关闭进程
适合个人使用

步骤：

配置 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "foxy-mcp": {
      "command": "node",
      "args": ["/path/to/foxy-mcp-nodejs/build/index.js", "--local"],
      "env": {
        "APIFOX_API_KEY": "APS-xxx",
        "PROJECT_ID": "31890xx"
      }
    }
  }
}

重启 Cursor

常驻后台服务，支持多个 Cursor 实例共享
适合团队协作
可能相对频繁启停服务

步骤：

创建 .env 文件：

APIFOX_API_KEY=APS-xxx
PROJECT_ID=31890xx
PORT=3000

启动服务：

pnpm start

配置 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "foxy-mcp": {
      "url": "http://localhost:3000/sse"
    }
  }
}

重启 Cursor

🛠️ 核心功能

1. 接口文档获取

工具：get-api-by-url

通过 Apifox 链接直接获取接口详情（OpenAPI 3.1 规范）

使用示例：

@foxy-mcp 这个接口的详情 https://app.apifox.com/link/project/3189010/apis/api-362821568

@foxy-mcp 分析登录接口的请求参数 https://app.apifox.com/link/project/xxx/apis/api-xxx

特点：

✅ 自动解析 Apifox URL
✅ 智能缓存（内存+磁盘持久化）
✅ 缓存命中提示（💾 内存 / 💿 磁盘）

工具：get-openapi-doc

获取整个文件夹的 OpenAPI 文档

使用示例：

@foxy-mcp 获取文件夹 123456 的接口文档

@foxy-mcp 导出用户模块的所有接口

2. 缓存管理

`cache-stats` - 查看缓存统计

@foxy-mcp 查看缓存统计

输出示例：

📊 缓存统计:

内存缓存: 15/200 个接口
磁盘缓存: 42/500 个接口

内存命中率: 78.5% (156 hits / 199 total)
磁盘命中率: 21.5% (43 hits / 199 total)

`refresh-cache` - 刷新单个接口缓存

清除旧缓存并立即获取最新数据（一步到位）

使用示例：

@foxy-mcp 获取最新协议 https://app.apifox.com/link/project/4519605/apis/api-175889154

@foxy-mcp 刷新缓存 https://app.apifox.com/link/project/4519605/apis/api-175889154

`clear-cache` - 清空缓存

@foxy-mcp 清空缓存

@foxy-mcp 清空项目 3189010 的缓存

3. Mock 数据生成

`generate-mock-data` - 生成 Mock 数据

基于 OpenAPI Schema 本地生成，无需依赖 Apifox Mock 服务

参数：

url - Apifox 接口链接
type - request（请求体）或 response（响应体）
statusCode - 响应状态码（可选，默认 200）

使用示例：

@foxy-mcp 生成登录接口的请求体示例 https://app.apifox.com/link/project/xxx/apis/api-xxx

@foxy-mcp 生成用户详情接口的响应体 https://app.apifox.com/link/project/xxx/apis/api-xxx

@foxy-mcp 生成 401 错误响应 https://app.apifox.com/link/project/xxx/apis/api-xxx

特点：

✅ 使用 @faker-js/faker 生成真实感数据
✅ 智能字段识别（email、phone、avatar、userId 等）
✅ 优先使用真实数据池（混合真实值）
✅ 自动复用缓存的接口文档

4. 真实数据池管理

`add-real-data` - 添加真实数据

将真实 API 响应数据添加到数据池，提升 Mock 真实感

参数：

data - JSON 格式字符串
scope - global（全局）或 project（项目级）
projectId - 项目 ID（scope=project 时必需）

使用示例：

@foxy-mcp 添加真实数据到全局池：
{
  "uid": "313012040519936",
  "nickname": "测试用户",
  "avatar": "https://example.com/avatar.jpg",
  "token": "real_token_abc123"
}

@foxy-mcp 为项目 3189010 添加真实数据：
{
  "userId": ["12345", "67890"],
  "email": ["[email protected]", "[email protected]"]
}

工作原理：

用户粘贴真实 API 响应（任意嵌套结构）
系统递归提取所有字段值
存储到数据池（全局或项目级）
生成 Mock 时优先使用这些真实值

特点：

✅ 零格式限制（递归提取所有字段）
✅ 自动去重合并
✅ 支持全局/项目级隔离
✅ 项目数据优先于全局数据

`list-real-data` - 查看数据池

@foxy-mcp 查看数据池

@foxy-mcp 查看全局数据池

@foxy-mcp 查看项目 3189010 的数据池

`clear-real-data` - 清空数据池

@foxy-mcp 清空全局数据池

@foxy-mcp 清空项目 3189010 的数据池

@foxy-mcp 清空所有数据池

注意：

⚠️ 此操作不影响接口缓存
⚠️ 清空后 Mock 生成将回退到 Faker

⚙️ 配置说明

鉴权方式

| 方式 | 获取方式 | 适用场景 | 稳定性 | | ---------------- | -------------------------------------------------------------------------------------------------------- | -------- | ----------- | | API Key | Apifox → 个人设置 → 开发者令牌 | 参考Apifox开放API-鉴权 | 生产环境 | ✅ 稳定 | | Cookie Token | 浏览器 F12 → Cookies → Authorization | 临时调试 | ⚠️ 会话过期 |

⚠️ API Key 权限要求：需要 Apifox 权限管理员及以上
💡 Cookie Token 获取：从浏览器 DevTools 的 Cookies 中复制 Authorization 字段

环境变量

| 变量 | 必需 | 默认值 | 说明 | | --------------------------- | ---- | ------- | ----------------------- | | APIFOX_API_KEY | ⚠️ | - | Apifox API 密钥（推荐） | | APIFOX_COOKIE_TOKEN | ⚠️ | - | Cookie Token（调试用） | | PROJECT_ID | ❌ | - | 默认项目 ID | | PORT | ❌ | 3000 | HTTP 模式端口 | | CACHE_ENABLED | ❌ | true | 是否启用缓存 | | CACHE_PERSISTENT | ❌ | true | 是否启用磁盘持久化 | | CACHE_TTL | ❌ | 3600000 | 缓存过期时间（毫秒） | | CACHE_MAX_SIZE | ❌ | 200 | 内存缓存最大数量 | | CACHE_PERSISTENT_MAX_SIZE | ❌ | 500 | 磁盘缓存最大数量 | | CACHE_SYNC_INTERVAL | ❌ | 30000 | 缓存同步间隔（毫秒） |

⚠️ 至少提供一种鉴权方式：APIFOX_API_KEY 或 APIFOX_COOKIE_TOKEN

📦 技术架构

混合缓存系统-减少接口调用

架构： 内存 LRU + 磁盘持久化

内存缓存（热数据）：毫秒级响应，默认 200 个接口
磁盘持久化（冷数据）：服务重启后仍有效，默认 500 个接口
自动同步：每 30 秒异步写入磁盘（非阻塞）
多维索引：支持 URL、接口名、路径快速查找
过期管理：默认 1 小时 TTL，自动清理

缓存位置：

macOS: ~/Library/Preferences/foxy-mcp-nodejs/config.json
Linux: ~/.config/foxy-mcp-nodejs/config.json
Windows: %APPDATA%\foxy-mcp\config.json

存储结构：

{
  "cache": {
    "apis": {}, // 接口缓存数据
    "urlIndex": {}, // URL 索引
    "nameIndex": {}, // 接口名索引
    "pathIndex": {} // 路径索引
  },
  "mockDataPool": {
    "global": {}, // 全局真实数据池
    "projects": {} // 项目级真实数据池
  }
}

数据隔离：

✅ 清空缓存不影响 Mock 数据池
✅ 清空数据池不影响接口缓存

Mock 数据生成

技术栈：

openapi-sampler - 基于 Schema 生成基础结构
@faker-js/faker - 生成真实感数据（中文语言包）
自定义数据池 - 混合用户提供的真实值

生成策略：

优先从数据池获取（项目级 > 全局）
其次使用智能字段识别（email、phone、avatar 等）
最后回退到 Faker 随机生成

智能字段识别：

| 字段名模式 | 生成逻辑 | | ---------------------- | ------------------------------ | | email, mail | faker.internet.email() | | phone, mobile | faker.phone.number() | | avatar, profilePic | faker.image.avatar() | | userId, uid, id | faker.string.numeric(15) | | nickname, username | faker.internet.username() | | token, accessToken | faker.string.alphanumeric(32) | | url, link | faker.internet.url() | | address | faker.location.streetAddress() |

🔧 命令行工具

可用命令

# 查看帮助
node build/cli.js --help

# 运行初始化向导
pnpm intro
node build/cli.js intro

# 启动服务（HTTP 模式）
pnpm start
node build/cli.js start

# 查看版本
node build/cli.js --version

❓ 常见问题

Apifox → 项目 → 左侧模块树 → 右键文件夹 → 复制文件夹 ID

Apifox → 个人设置 → 开发者令牌 | 参考Apifox开放API-鉴权

⚠️ 需要权限管理员及以上权限

打开 Apifox 网页版并登录
按 F12 打开开发者工具
切换到 Application → Cookies
复制 Authorization 字段的值

⚠️ Cookie 会随会话过期，适合临时调试

可能原因：

API Key 已过期或被撤销
API Key 格式错误
账号权限不足（需要管理员以上权限）

解决方案：

前往 Apifox → 个人设置 → 开发者令牌
重新生成 API Key
更新 .env 文件中的 APIFOX_API_KEY
重启服务

Cookie Token 鉴权失败：

可能原因：

浏览器会话已过期
Cookie Token 格式错误
已在浏览器端登出

解决方案：

重新登录 Apifox 网页版
按 F12 打开开发者工具
Application → Cookies → 复制 Authorization 字段
更新 .env 文件中的 APIFOX_COOKIE_TOKEN
重启服务

💡 建议：生产环境请使用 API Key（稳定性更好）

可能原因：

当前账号没有访问此项目的权限
API Key 权限级别不足（需要管理员以上）

解决方案：

联系项目管理员添加访问权限
或使用有权限的账号生成新的 API Key

错误信息：

❌ 鉴权配置错误：未提供任何鉴权凭证

解决方案：

使用交互式向导（推荐）：
```
pnpm intro
```

手动配置 .env 文件：

# 方式 1：使用 API Key（推荐）
APIFOX_API_KEY=APS-xxx

# 方式 2：使用 Cookie Token
APIFOX_COOKIE_TOKEN=Bearer xxx

重启服务

| 模式 | 进程管理 | 适用场景 | 共享性 | | -------- | --------------- | -------- | ------------ | | CLI | Cursor 自动管理 | 个人使用 | 每个窗口独立 | | HTTP | 后台常驻服务 | 团队协作 | 多个实例共享 |

启动时会自动检测并提示：

解决方案：

清理占用进程（macOS/Linux）：
```
lsof -ti:3000 | xargs kill -9
```
换端口启动：
```
PORT=3001 pnpm start
```
等待几秒后重试（如刚关闭服务）

按 Ctrl+C，服务会自动：

关闭所有 SSE 连接
刷新缓存到磁盘
释放端口

macOS: ~/Library/Preferences/foxy-mcp-nodejs/config.json

可以手动删除该文件清空所有缓存

CACHE_PERSISTENT=false pnpm start

# 24 小时缓存
CACHE_TTL=86400000 pnpm start

# 仅内存缓存（不持久化）
CACHE_PERSISTENT=false CACHE_TTL=600000 pnpm start

两种模式都需要：

重新构建：pnpm build
重启服务：
- CLI 模式：重启 Cursor
- HTTP 模式：重启服务器

📊 功能总览

| 分类 | 工具 | 功能 | | ------------- | -------------------- | ------------------------- | | 接口文档 | get-api-by-url | 通过 URL 获取接口详情 | | | get-openapi-doc | 获取文件夹的 OpenAPI 文档 | | 缓存管理 | cache-stats | 查看缓存统计 | | | refresh-cache | 刷新单个接口缓存 | | | clear-cache | 清空缓存 | | Mock 生成 | generate-mock-data | 生成请求体/响应体 Mock | | 数据池 | add-real-data | 添加真实数据 | | | list-real-data | 查看数据池 | | | clear-real-data | 清空数据池 |

共 9 个工具 + 交互式初始化向导

🛡️ 稳定性保障

HTTP 模式特性

✅ 连接管理 - 实时追踪、自动清理、错误恢复
✅ 超时保护 - 非 SSE 端点 30 秒超时，SSE 保持长连接
✅ 请求日志 - 记录所有请求便于调试
✅ 错误处理 - 全局错误捕获和 404 处理
✅ 优雅关闭 - SIGTERM/SIGINT 信号处理，自动刷新缓存到磁盘

健康检查

curl http://localhost:3000/health

📝 开发

# 开发模式（热重载）
pnpm dev

# 构建
pnpm build

# 启动 HTTP 服务器
pnpm start

# 运行初始化向导
pnpm intro

🔗 相关链接

欢迎贡献和反馈！ 🦊✨

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🦊 Foxy MCP

🚀 快速开始

一键初始化（推荐）

手动配置（可选）

🛠️ 核心功能

1. 接口文档获取

2. 缓存管理

cache-stats - 查看缓存统计

refresh-cache - 刷新单个接口缓存

clear-cache - 清空缓存

3. Mock 数据生成

generate-mock-data - 生成 Mock 数据

4. 真实数据池管理

add-real-data - 添加真实数据

list-real-data - 查看数据池

clear-real-data - 清空数据池

⚙️ 配置说明

鉴权方式

环境变量

📦 技术架构

混合缓存系统-减少接口调用

Mock 数据生成

🔧 命令行工具

可用命令

❓ 常见问题

📊 功能总览

🛡️ 稳定性保障

HTTP 模式特性

健康检查

📝 开发

🔗 相关链接

`cache-stats` - 查看缓存统计

`refresh-cache` - 刷新单个接口缓存

`clear-cache` - 清空缓存

`generate-mock-data` - 生成 Mock 数据

`add-real-data` - 添加真实数据

`list-real-data` - 查看数据池

`clear-real-data` - 清空数据池