# 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 消息。