65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
# 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)。
|
|
|
|
### 命令
|
|
- **安装依赖**:
|
|
```bash
|
|
npm install
|
|
```
|
|
- **启动 (Stdio 模式)** - *默认，用于与 Claude Desktop 集成*:
|
|
```bash
|
|
node index.js
|
|
# 或者显式指定:
|
|
node index.js --transport stdio
|
|
```
|
|
- **启动 (HTTP/SSE 模式)** - *用于远程部署或检查*:
|
|
```bash
|
|
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 客户端公开以下工具：
|
|
|
|
1. **`get_api_by_path`**:
|
|
- **描述**: 根据路径检索详细的 API 定义 schema。
|
|
- **输入**: `path` (字符串), `projectId` (数字, 可选)。
|
|
2. **`get_apis_by_folder`**:
|
|
- **描述**: 检索特定文件夹内的所有 API 定义。
|
|
- **输入**: `folderName` (字符串), `projectId` (数字, 可选)。
|
|
|
|
## 开发约定
|
|
- **ES Modules**: 项目使用 ES 模块（`package.json` 中的 `"type": "module"`）。
|
|
- **错误处理**: 工具返回带有 `isError: true` 的结构化错误响应，而不是崩溃。
|
|
- **日志记录**: Stdio 传输使用 `stderr` 进行日志记录，以避免干扰 `stdout` 上的 JSON-RPC 消息。 |