0 Fork 0

Files

T

zhangguoyun dd1d86706c feat: comprehensive refactor of index.js and documentation update

2026-01-15 11:09:13 +08:00

4.2 KiB

Raw Blame History

Apifox MCP Service

这是一个基于 Model Context Protocol (MCP) 标准实现的 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)

安装依赖

npm install

🚀 启动服务

命令行选项

node index.js [选项]

选项:
  -t, --transport <type>  传输方式 (stdio|http) [默认: stdio]
  -p, --port <number>     HTTP 服务器端口号 [默认: 8889]
  -h, --help              显示帮助信息

1. Stdio 模式 (默认)

适用于 Claude Desktop、Cursor 或作为子进程运行的场景。

# 需确保环境变量已设置
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 访问的场景。

# 使用默认端口 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 (可选): 可通过请求头动态指定

查看帮助信息

node index.js --help

💻 客户端集成示例

Claude Desktop 配置

编辑 Claude Desktop 的配置文件 (通常位于 %APPDATA%\Claude\claude_desktop_config.json 或 ~/Library/Application Support/Claude/claude_desktop_config.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

4.2 KiB Raw Blame History Unescape Escape