使用说明

项目简介

ApiFox MCP Server 是一个 MCP (Model Context Protocol) 服务器，它桥接了 ApiFox 接口文档平台和 LLM (大型语言模型) 客户端，例如 Cursor 编辑器。通过此服务器，LLM 能够获取指定 ApiFox 项目的接口信息，从而在代码生成、理解和调试等场景中，更好地利用 ApiFox 中预定义的 API 接口。

主要功能点

提供 ApiFox 接口信息： 通过 MCP 协议，向 LLM 客户端提供 ApiFox 项目中定义的接口文档 (OpenAPI 3.1 规范的 JSON 数据)。
支持 HTTP 和 CLI 两种模式： 既可以作为 HTTP 服务器长期运行，也可以通过命令行按需启动。
工具 (Tool) 注册： 注册 'get-interface' 工具，允许 LLM 客户端通过指定模块 ID 和模块名称来获取特定模块的接口信息。
SSE 传输协议： 支持通过 Server-Sent Events (SSE) 协议与 LLM 客户端进行通信，实现实时的请求和响应。
环境变量配置： 支持通过环境变量灵活配置 ApiFox API Key 和 Project ID 等敏感信息。

安装步骤

确保已安装 Node.js 和 npm 或 pnpm: 本仓库使用 Node.js 和 pnpm 进行开发和管理。请确保你的开发环境中已安装 Node.js (建议 18.x 或以上版本) 和 pnpm。
拉取代码或下载仓库: 将 GitHub 仓库 'https://github.com/wangmhaha/apifox-mcp-server' 克隆到本地或下载 ZIP 包并解压。
安装依赖: 在仓库根目录下，打开终端并运行命令 'pnpm install' 或 'npm install' 安装项目依赖。
构建项目: 运行命令 'pnpm build' 或 'npm run build' 构建项目，将 TypeScript 代码编译为 JavaScript。

服务器配置

对于 MCP 客户端（如 Cursor），需要配置 MCP 服务器的启动命令。以下是两种配置方式，选择其一添加到 Cursor 的 MCP 配置文件中：

方式一：使用 'npx' 快速启动 (推荐)

这种方式无需本地构建，直接使用 'npx' 运行已发布的 npm 包。

"apifox-mcp-server": {
    "command": "npx",
    "args": [
      "-y",
      "@wangmhaha/apifox-mcp-server@latest",
      "--local" // 使用 Stdio 传输，如果客户端支持 HTTP SSE，可以移除此参数并配置 "url"
    ],
    "env": {
      "APIFOX_API_KEY": "<your-apifox-api-key>", // 替换为你的 ApiFox API Key
      "PROJECT_ID": "<your-project-id>"      // 替换为你的 ApiFox 项目 ID
    }
  }

参数说明：

'"command": "npx"': 指定使用 'npx' 命令运行。
'"args": [...]'：传递给 'npx' 的参数列表：
- '"-y"': 'npx' 参数，自动确认安装包。
- '"@wangmhaha/apifox-mcp-server@latest"': 指定要运行的 npm 包和版本（latest 表示最新版本）。
- '"--local"': 可选参数，如果添加此参数，服务器将使用 Stdio 传输协议，否则默认启动 HTTP SSE 服务器。如果客户端支持 HTTP SSE 并且需要通过 HTTP 连接，请移除此参数，并按照方式二配置 "url"。
'"env": {...}': 设置环境变量：
- '"APIFOX_API_KEY"': 必填，你的 ApiFox API Key，用于访问 ApiFox API。
- '"PROJECT_ID"': 必填，你的 ApiFox 项目 ID，指定要获取接口信息的项目。

方式二：从本地构建产物运行

这种方式需要先本地构建项目，然后指定 'node' 命令和构建后的 'index.js' 文件路径来运行。

"apifox-mcp-server": {
    "command": "node",
    "args": [
      "<your-local-path>/build/index.js", // 替换为实际的 build/index.js 文件路径
      "--local" // 使用 Stdio 传输，如果客户端支持 HTTP SSE，可以移除此参数并配置 "url"
    ],
    "env": {
      "APIFOX_API_KEY": "<your-apifox-api-key>", // 替换为你的 ApiFox API Key
      "PROJECT_ID": "<your-project-id>"      // 替换为你的 ApiFox 项目 ID
    }
  }

参数说明：

'"command": "node"': 指定使用 'node' 命令运行。
'"args": [...]'：传递给 'node' 的参数列表：
- '"<your-local-path>/build/index.js"': 必填，替换为项目本地构建后 'build/index.js' 文件的绝对路径。
- '"--local"': 可选参数，作用同方式一。
'"env": {...}': 环境变量配置同方式一。

如果使用 HTTP SSE 模式 (不加 '--local' 参数):

在上述两种配置方式中，移除 '"--local"' 参数，并在 MCP 客户端配置中添加 '"url"' 字段，指向服务器的 SSE 端点。服务器默认端口为 '3000'，可以通过设置环境变量 'PORT' 修改。

"apifox-mcp-server": {
    "url": "http://localhost:3000/sse", // HTTP SSE 端点 URL，可根据实际情况修改主机名和端口
    "command": "npx", // 或 "command": "node" 和 "args": [...]
    "args": [
      "-y",
      "@wangmhaha/apifox-mcp-server@latest" // 或 本地构建的 index.js 路径
    ],
    "env": {
      "APIFOX_API_KEY": "<your-apifox-api-key>",
      "PROJECT_ID": "<your-project-id>"
    }
  }

基本使用方法

启动 MCP 服务器: 配置完成后，在 MCP 客户端中启动 'apifox-mcp-server' 服务。
调用 'get-interface' 工具: 在 LLM 客户端中，可以使用 '@apifox-mcp-server/get-interface' 工具，并提供 'moduleId' 和 'moduleName' 参数来获取指定 ApiFox 模块的接口信息。

示例 (Cursor 编辑器):

在 Cursor 中，你可以通过 '@' 符号触发工具调用，例如：

@apifox-mcp-server/get-interface moduleName=用户模块 moduleId=xxxxxxxxxxxxx

其中 'xxxxxxxxxxxxx' 需要替换为你在 ApiFox 中 用户模块 对应的模块 ID。服务器会将用户模块的接口文档信息返回给 Cursor，供 LLM 使用。

注意：

请务必替换配置中的 '<your-apifox-api-key>' 和 '<your-project-id>' 为你真实的 ApiFox API Key 和项目 ID。
建议将敏感信息 (如 API Key) 存储在环境变量中，避免硬编码在配置文件中。
如果遇到连接问题，请检查端口是否被占用，以及网络连接是否正常。

关键词