概览

apifox-api-mcp 是一个通过 stdio 模式运行的 MCP Server，封装了 Apifox Open API，为 AI 编程工具提供结构化的 API 端点查询能力。

它的核心工作流程：

1. 首次查询时自动调用 Apifox API 导出完整的 OpenAPI 规范
2. 将数据缓存到本地内存（默认 10 分钟 TTL），避免重复请求
3. 解析 OpenAPI 规范并构建多维索引（按 ID、路径、文件夹、关键词）
4. 通过 7 个 MCP 工具向 AI 助手提供结构化查询结果

特性

• 7 个查询工具 — 按 ID、URL、文件夹、模块、关键词等多种方式查询端点
• Apifox 扩展属性 — 完整解析 x-apifox-id、x-apifox-folder 等扩展字段
• 智能缓存 — 内存缓存 + TTL 过期策略，减少 API 调用
• 结构化输出 — 面向代码生成优化的数据格式，参数按类型分组
• Schema 查询 — 支持获取项目中所有数据模型定义
• 完善的错误处理 — 9 种错误类型，清晰的中文错误提示

快速开始

前置条件

• Node.js 18+
• Apifox 账号及 个人访问令牌
• Apifox 项目 ID

获取 Apifox 访问令牌

1. 登录 Apifox
2. 进入 个人设置 → API 访问令牌
3. 创建一个新的访问令牌并复制

获取项目 ID

在 Apifox 中打开你的项目，从浏览器地址栏中获取项目 ID：

https://app.apifox.com/project/{{projectId}}

安装

# 通过 npm 全局安装
npm install -g apifox-api-mcp

# 或者从源码构建
git clone https://github.com/minetsh/apifox-api-mcp.git
cd apifox-api-mcp
npm install
npm run build

配置示例

以下示例均使用 npx 运行，无需全局安装。也可以替换为全局安装后的路径。

Kiro

在项目根目录创建或编辑 .kiro/settings/mcp.json：

{
  "mcpServers": {
    "apifox": {
      "command": "npx",
      "args": ["-y", "apifox-api-mcp"],
      "env": {
        "APIFOX_ACCESS_TOKEN": "<your-access-token>",
        "APIFOX_PROJECT_ID": "<your-project-id>"
      }
    }
  }
}

Cursor

在项目根目录创建或编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "apifox": {
      "command": "npx",
      "args": ["-y", "apifox-api-mcp"],
      "env": {
        "APIFOX_ACCESS_TOKEN": "<your-access-token>",
        "APIFOX_PROJECT_ID": "<your-project-id>"
      }
    }
  }
}

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "apifox": {
      "command": "npx",
      "args": ["-y", "apifox-api-mcp"],
      "env": {
        "APIFOX_ACCESS_TOKEN": "<your-access-token>",
        "APIFOX_PROJECT_ID": "<your-project-id>"
      }
    }
  }
}

Windsurf

在项目根目录创建或编辑 .windsurf/mcp.json：

{
  "mcpServers": {
    "apifox": {
      "command": "npx",
      "args": ["-y", "apifox-api-mcp"],
      "env": {
        "APIFOX_ACCESS_TOKEN": "<your-access-token>",
        "APIFOX_PROJECT_ID": "<your-project-id>"
      }
    }
  }
}

VS Code (Copilot)

在项目根目录创建或编辑 .vscode/mcp.json：

{
  "servers": {
    "apifox": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "apifox-api-mcp"],
      "env": {
        "APIFOX_ACCESS_TOKEN": "<your-access-token>",
        "APIFOX_PROJECT_ID": "<your-project-id>"
      }
    }
  }
}

环境变量

| 变量 | 必填 | 说明 | 默认值 | |------|------|------|--------| | APIFOX_ACCESS_TOKEN | ✅ | Apifox 个人访问令牌 | — | | APIFOX_PROJECT_ID | ✅ | Apifox 项目 ID | — | | APIFOX_MODULE_ID | ❌ | 限定查询范围到指定模块 | 全部模块 | | APIFOX_CACHE_TTL | ❌ | 缓存过期时间（分钟） | 10 |

可用工具

list_endpoints

列出项目中所有 API 端点的摘要信息。

• 参数：无
• 返回：端点摘要列表（ID、方法、路径、名称、标签）

search_endpoints

按关键词搜索 API 端点，支持大小写不敏感的模糊匹配。

• 参数：keyword (string) — 搜索关键词，匹配路径、名称、方法、描述
• 返回：匹配的端点摘要列表

get_endpoint_by_id

按端点 ID 查询完整的 API 端点定义。

• 参数：endpointId (string) — Apifox 端点 ID（即 x-apifox-id）
• 返回：结构化端点数据，包含方法、路径、参数（按类型分组）、请求体、响应、标签等

get_endpoint_by_url

解析 Apifox 文档链接并返回对应的端点定义。

• 参数：url (string) — Apifox 链接，格式：https://app.apifox.com/link/project/{projectId}/apis/api-{endpointId}
• 返回：结构化端点数据

get_endpoints_by_folder

按文件夹查询该文件夹下所有 API 端点。

• 参数：folderId (string) — 文件夹标识（即 x-apifox-folder 值）
• 返回：该文件夹下所有端点的结构化数据列表

get_endpoints_by_module

按模块 ID 查询该模块下所有 API 端点。

• 参数：moduleId (number) — Apifox 模块 ID
• 返回：该模块下所有端点的结构化数据列表

get_project_schemas

获取项目中所有数据模型（Schema）定义。

• 参数：无
• 返回：所有 Schema 的名称、类型、属性、必填字段、描述

输出格式

端点结构化输出

get_endpoint_by_id、get_endpoint_by_url、get_endpoints_by_folder、get_endpoints_by_module 返回的端点数据格式：

{
  "method": "POST",
  "path": "/api/users",
  "summary": "创建用户",
  "description": "创建一个新用户",
  "tags": ["User"],
  "folder": "用户管理",
  "pathParameters": [],
  "queryParameters": [],
  "headerParameters": [
    {
      "name": "Authorization",
      "in": "header",
      "required": true,
      "description": "Bearer token",
      "schema": { "type": "string" }
    }
  ],
  "requestBody": {
    "contentType": "application/json",
    "required": true,
    "schema": { "type": "object", "properties": { "name": { "type": "string" } } },
    "description": "用户信息"
  },
  "responses": [
    {
      "statusCode": "200",
      "description": "成功",
      "contentType": "application/json",
      "schema": { "type": "object" }
    }
  ],
  "deprecated": false
}

端点摘要输出

list_endpoints、search_endpoints 返回的摘要格式：

{
  "id": "12345",
  "method": "POST",
  "path": "/api/users",
  "summary": "创建用户",
  "tags": ["User"]
}

架构

┌─────────────────────────────────────────────────┐
│                  IDE / MCP Client                │
└──────────────────────┬──────────────────────────┘
                       │ stdio (JSON-RPC)
┌──────────────────────▼──────────────────────────┐
│               MCP Server (tools.ts)              │
│  ┌───────────────────────────────────────────┐  │
│  │  7 MCP Tools + Zod Schema Validation      │  │
│  └───────────────────┬───────────────────────┘  │
│  ┌─────────┐  ┌──────▼──────┐  ┌────────────┐  │
│  │ URL     │  │  Endpoint   │  │  Output    │  │
│  │ Parser  │  │  Index      │  │  Formatter │  │
│  └─────────┘  └──────┬──────┘  └────────────┘  │
│               ┌──────▼──────┐                   │
│               │   Cache     │                   │
│               │   Manager   │                   │
│               └──────┬──────┘                   │
│               ┌──────▼──────┐                   │
│               │  OpenAPI    │                   │
│               │  Parser     │                   │
│               └──────┬──────┘                   │
│               ┌──────▼──────┐                   │
│               │  Apifox     │                   │
│               │  Client     │                   │
│               └──────┬──────┘                   │
└──────────────────────┼──────────────────────────┘
                       │ HTTPS
              ┌────────▼────────┐
              │  Apifox Open API │
              └─────────────────┘

错误处理

所有工具在出错时返回统一的错误格式：

{
  "error": "ERROR_CODE",
  "message": "错误描述信息"
}

| 错误码 | 触发场景 | 说明 | |--------|---------|------| | AUTH_ERROR | Apifox API 返回 401 | 访问令牌无效或过期 | | API_VERSION_ERROR | Apifox API 返回 422 | API 版本头缺失或无效 | | RATE_LIMIT_ERROR | Apifox API 返回 429 | 请求频率超限，稍后重试 | | NETWORK_ERROR | 网络连接失败 | 检查网络连接 | | INVALID_SPEC | OpenAPI 规范格式无效 | Apifox 导出数据异常 | | NOT_FOUND | 端点/文件夹未找到 | 检查 ID 是否正确 | | INVALID_URL | Apifox 链接格式无效 | 检查 URL 格式 | | INVALID_PARAMS | 工具参数校验失败 | 检查参数类型和格式 | | INTERNAL_ERROR | 未预期的内部错误 | 查看 stderr 日志 |

开发指南

项目结构

src/
├── index.ts              # 服务入口，环境变量读取，MCP Server 启动
├── tools.ts              # 7 个 MCP 工具注册与错误处理
├── types.ts              # 核心数据模型接口定义
├── errors.ts             # 错误码枚举与自定义错误类
├── apifox-client.ts      # Apifox Open API HTTP 客户端
├── cache.ts              # 缓存管理器（内存缓存 + TTL）
├── parser.ts             # OpenAPI 规范解析器
├── index-store.ts        # 端点多维索引（ID / 路径 / 文件夹 / 搜索）
├── url-parser.ts         # Apifox 链接 URL 解析器
├── formatter.ts          # 输出格式化器
├── *.test.ts             # 单元测试
└── *.property.test.ts    # 属性测试（fast-check）

常用命令

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 运行测试（单次）
npm test

# 运行测试（监听模式）
npm run test:watch

# 运行测试（含覆盖率）
npm run test:coverage

测试策略

项目采用三层测试策略：

• 属性测试（fast-check）— 10 个正确性属性，每个运行 100+ 次随机迭代，覆盖缓存一致性、索引查找、搜索完整性、URL 解析往返等
• 单元测试（Vitest）— 覆盖各模块的具体示例和边界条件
• 集成测试 — Mock Apifox API，端到端验证完整的工具调用流程

技术栈

| 组件 | 技术 | |------|------| | 运行时 | Node.js 18+ | | 语言 | TypeScript (ES2022) | | MCP SDK | @modelcontextprotocol/sdk | | Schema 校验 | Zod | | 测试框架 | Vitest | | 属性测试 | fast-check | | HTTP 客户端 | Node.js 内置 fetch |

许可证

MIT