160 lines
4.2 KiB
Markdown
160 lines
4.2 KiB
Markdown
# Apifox MCP Service
|
||
|
||
这是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 标准实现的 Apifox 服务端。它充当 LLM (如 Claude, Gemini 等) 与 Apifox API 文档之间的桥梁，允许 AI 助手直接检索 Apifox 中的接口定义，并根据定义生成强类型的 API 请求代码。
|
||
|
||
## ✨ 功能特性
|
||
|
||
* **MCP 协议支持**: 支持标准 MCP 协议，可集成到 Claude Desktop, Cursor 等支持 MCP 的客户端。
|
||
* **多传输模式**: 支持 `stdio` (标准输入输出，默认) 和 `http` (SSE 流式传输) 两种模式。
|
||
* **接口检索**:
|
||
* `get_api_by_path`: 根据路径获取指定接口的详细定义 (Schema)。
|
||
* `get_apis_by_folder`: 获取指定目录下的所有接口定义。
|
||
* **AI 提示词 (Prompts)**:
|
||
* `gen-api-by-path`: 指导 AI 根据接口路径生成 API 代码。
|
||
* `gen-api-by-folder`: 指导 AI 根据目录批量生成 API 代码。
|
||
* **健康检查**: HTTP 模式下提供 `/health` 端点。
|
||
|
||
## 🛠️ 安装与配置
|
||
|
||
### 前置要求
|
||
|
||
* Node.js (v18 或更高版本)
|
||
* Apifox 账号及项目访问权限
|
||
|
||
### 环境变量
|
||
|
||
运行此服务需要配置以下环境变量：
|
||
|
||
| 变量名 | 描述 |
|
||
| :--- | :--- |
|
||
| `APIFOX_PROJECT_ID` | 你的 Apifox 项目 ID (数字) |
|
||
| `APIFOX_TOKEN` | 你的 Apifox 访问令牌 (Bearer Token) |
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
## 🚀 启动服务
|
||
|
||
### 命令行选项
|
||
|
||
```bash
|
||
node index.js [选项]
|
||
|
||
选项:
|
||
-t, --transport <type> 传输方式 (stdio|http) [默认: stdio]
|
||
-p, --port <number> HTTP 服务器端口号 [默认: 8889]
|
||
-h, --help 显示帮助信息
|
||
```
|
||
|
||
### 1. Stdio 模式 (默认)
|
||
|
||
适用于 Claude Desktop、Cursor 或作为子进程运行的场景。
|
||
|
||
```bash
|
||
# 需确保环境变量已设置
|
||
export APIFOX_PROJECT_ID=你的项目ID
|
||
export APIFOX_TOKEN=你的Token
|
||
|
||
# 默认使用 stdio 模式
|
||
node index.js
|
||
|
||
# 或显式指定
|
||
node index.js --transport stdio
|
||
```
|
||
|
||
**特点:**
|
||
- 通过标准输入/输出与客户端通信
|
||
- 适合本地集成 (Claude Desktop, Cursor 等)
|
||
- 日志输出到 stderr,不干扰 JSON-RPC 通信
|
||
|
||
### 2. HTTP (SSE) 模式
|
||
|
||
适用于远程部署、调试或需要 HTTP 访问的场景。
|
||
|
||
```bash
|
||
# 使用默认端口 8889
|
||
node index.js --transport http
|
||
|
||
# 或指定自定义端口
|
||
node index.js --transport http --port 3000
|
||
```
|
||
|
||
**HTTP 端点:**
|
||
- **MCP 服务**: `http://localhost:8889/sse` (Server-Sent Events)
|
||
- **MCP 消息**: `http://localhost:8889/messages`
|
||
- **健康检查**: `http://localhost:8889/health`
|
||
|
||
**HTTP 请求头支持:**
|
||
- `Authorization`: Bearer token (可选,覆盖环境变量 `APIFOX_TOKEN`)
|
||
- `x-apifox-project-id`: 项目 ID (可选,覆盖环境变量 `APIFOX_PROJECT_ID`)
|
||
|
||
**特点:**
|
||
- 支持 CORS,可跨域访问
|
||
- 支持动态认证 (通过请求头传递 token 和 projectId)
|
||
- 提供健康检查端点
|
||
- 详细的请求日志
|
||
|
||
### 环境变量验证
|
||
|
||
服务启动时会自动验证必需的环境变量:
|
||
- `APIFOX_TOKEN` (必需): 如未设置,服务将拒绝启动并提示配置方法
|
||
- `APIFOX_PROJECT_ID` (可选): 可通过请求头动态指定
|
||
|
||
### 查看帮助信息
|
||
|
||
```bash
|
||
node index.js --help
|
||
```
|
||
|
||
## 💻 客户端集成示例
|
||
|
||
### Claude Desktop 配置
|
||
|
||
编辑 Claude Desktop 的配置文件 (通常位于 `%APPDATA%\Claude\claude_desktop_config.json` 或 `~/Library/Application Support/Claude/claude_desktop_config.json`)：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"apifox": {
|
||
"command": "node",
|
||
"args": [
|
||
"D:/demo/apifox-mcp-service/index.js"
|
||
],
|
||
"env": {
|
||
"APIFOX_PROJECT_ID": "123456",
|
||
"APIFOX_TOKEN": "apifox_pat_xxxxxxxx"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
*注意：请将路径替换为你本地的实际绝对路径。*
|
||
|
||
## 📚 工具详情
|
||
|
||
### Tools
|
||
|
||
#### `get_api_by_path`
|
||
根据接口路径获取 Apifox 接口定义数据。
|
||
* 参数: `path` (string), `projectId` (number, 可选)
|
||
|
||
#### `get_apis_by_folder`
|
||
根据接口目录名称获取目录下所有接口定义。
|
||
* 参数: `folderName` (string), `projectId` (number, 可选)
|
||
|
||
### Prompts
|
||
|
||
#### `gen-api-by-path`
|
||
流程化 Prompt，引导 LLM 获取接口定义并生成符合项目规范的 API 代码。
|
||
|
||
#### `gen-api-by-folder`
|
||
流程化 Prompt，引导 LLM 批量获取目录下接口并生成代码。
|
||
|
||
## 📝 License
|
||
|
||
ISC
|