Apifox MCP 服务上下文

项目概述

本项目是一个针对 Apifox 的 Model Context Protocol (MCP) 服务器。它充当大型语言模型 (LLM)（如 Claude 或 Gemini）与 Apifox API 文档之间的桥梁。它允许 AI 助手直接从 Apifox 项目中检索强类型的 API 定义 (Schema)，从而生成准确的 API 请求代码。

架构

index.js: 主入口点。它设置 MCP 服务器，注册工具，并处理传输（Stdio 或 HTTP/SSE）。
apifox.js: 包含 ApifoxService 类。它封装了与 Apifox API 交互的逻辑，处理身份验证、缓存，并递归解析 JSON Schema 引用 ($ref) 以提供自包含的 API 定义。

构建与运行

前置要求

Node.js (v18+)
Apifox 账号及项目

环境变量

需要以下环境变量：

APIFOX_PROJECT_ID: 目标 Apifox 项目 ID (数字)。
APIFOX_TOKEN: Apifox 个人访问令牌 (Bearer Token)。

命令

安装依赖:
```
npm install
```

启动 (Stdio 模式) - 默认，用于与 Claude Desktop 集成:

node index.js
# 或者显式指定:
node index.js --transport stdio

启动 (HTTP/SSE 模式) - 用于远程部署或检查:
```
node index.js --transport http --port 8889
```
- 端点: http://localhost:8889/sse
- 健康检查: http://localhost:8889/health

关键文件

index.js:
- 初始化 McpServer。
- 注册工具: get_api_by_path, get_apis_by_folder。
- 处理传输选择的命令行参数。
apifox.js:
- ApifoxService 类实现。
- 从 https://apifox.gzmiyuan.com/api/v1 获取数据。
- 使用 node-cache 实现缓存策略。
- 包含扁平化和解析复杂 JSON schema 以供 LLM 使用的逻辑。

可用工具

服务器向 MCP 客户端公开以下工具：

get_api_by_path:
- 描述: 根据路径检索详细的 API 定义 schema。
- 输入: path (字符串), projectId (数字, 可选)。
get_apis_by_folder:
- 描述: 检索特定文件夹内的所有 API 定义。
- 输入: folderName (字符串), projectId (数字, 可选)。

开发约定

ES Modules: 项目使用 ES 模块（package.json 中的 "type": "module"）。
错误处理: 工具返回带有 isError: true 的结构化错误响应，而不是崩溃。
日志记录: Stdio 传输使用 stderr 进行日志记录，以避免干扰 stdout 上的 JSON-RPC 消息。

2.5 KiB Raw Permalink Blame History