# 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