# YApi MCP Bridge

一个基于 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/) 的 YApi Server，让支持 MCP 的 AI 客户端可以查询、搜索、创建和更新 YApi 接口。

## 快速开始：配置 MCP 客户端

推荐直接在 MCP 客户端中通过 `npx` 启动，无需提前克隆仓库或全局安装 npm 包。

使用前请确认：

- 已安装 Node.js 18 或更高版本，并且可以运行 `npx`。
- 当前电脑可以访问目标 YApi 服务。
- 已准备好 `YAPI_HOST` 和有相应项目权限的 `YAPI_COOKIE`。

`YAPI_HOST` 只填写协议和域名，不要包含 `/api`。登录 YApi 后，可以在浏览器开发者工具的 Network 面板中选择任意 YApi 请求，从 Request Headers 复制完整的 `Cookie`。

### Cursor

全局配置文件为 `~/.cursor/mcp.json`；只希望当前项目使用时，可以配置在项目目录的 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "yapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "yapi-mcp-bridge@1"],
      "env": {
        "YAPI_HOST": "https://yapi.example.com",
        "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
      }
    }
  }
}
```

保存配置后重启 Cursor，或者在 **Customize > MCP** 中重新加载并确认 `yapi` 已启用。参见 [Cursor MCP 官方文档](https://cursor.com/docs/mcp)。

### Codex

推荐使用命令添加：

```bash
codex mcp add \
  --env 'YAPI_HOST=https://yapi.example.com' \
  --env 'YAPI_COOKIE=_yapi_token=xxx;_yapi_uid=xx;' \
  yapi -- npx -y yapi-mcp-bridge@1
```

也可以直接编辑 `~/.codex/config.toml`：

```toml
[mcp_servers.yapi]
command = "npx"
args = ["-y", "yapi-mcp-bridge@1"]
enabled = true

[mcp_servers.yapi.env]
YAPI_HOST = "https://yapi.example.com"
YAPI_COOKIE = "_yapi_token=xxx;_yapi_uid=xx;"
```

检查是否配置成功：

```bash
codex mcp get yapi
```

修改配置后重启 Codex。参见 [Codex MCP 官方文档](https://developers.openai.com/codex/mcp/)。

### Claude Code

使用 Claude Code CLI 添加到用户级配置：

```bash
claude mcp add --scope user \
  -e 'YAPI_HOST=https://yapi.example.com' \
  -e 'YAPI_COOKIE=_yapi_token=xxx;_yapi_uid=xx;' \
  yapi -- npx -y yapi-mcp-bridge@1
```

检查是否配置成功：

```bash
claude mcp get yapi
```

重新启动 Claude Code 后即可使用。参见 [Claude Code MCP 官方文档](https://code.claude.com/docs/en/mcp)。

### 验证使用

客户端成功加载后，应能发现 9 个以 `yapi_` 开头的工具。可以直接输入：

```text
获取 YApi 项目 1922 的详情。
```

每位使用者都应配置自己的 YApi Cookie。Cookie 等同于登录凭据，不要提交到 Git、写入项目共享配置或分享给其他人。

## 功能

当前提供以下工具：

| 工具 | 用途 | 类型 |
| --- | --- | --- |
| `yapi_get_project` | 获取项目详情 | 只读 |
| `yapi_get_interface` | 获取精简接口定义，可选返回原始全量数据 | 只读 |
| `yapi_list_categories` | 获取项目接口分类 | 只读 |
| `yapi_list_interfaces` | 分页获取项目接口，可按状态或标签筛选 | 只读 |
| `yapi_list_category_interfaces` | 分页获取分类下的接口 | 只读 |
| `yapi_search_interface` | 按标题、路径或 HTTP 方法搜索接口 | 只读 |
| `yapi_create_category` | 创建接口分类 | 写入 |
| `yapi_create_interface` | 创建接口 | 写入 |
| `yapi_update_interface` | 更新接口 | 写入 |

Server 不提供删除工具，避免 AI 客户端误执行不可逆操作。

## 可选：全局安装

一般不需要全局安装；MCP 配置中的 `npx` 会自动下载并启动兼容的 `1.x` 版本。如果希望直接使用命令行，可以全局安装：

```bash
npm install -g yapi-mcp-bridge@1
yapi-mcp-bridge
```

全局安装后，可以使用下面的命令查看工具调用统计：

```bash
yapi-mcp-stats
```

## 从源码安装

### 环境要求

- Node.js 18 或更高版本
- 一个可以正常访问的 YApi 实例
- 有对应项目访问权限的 YApi Cookie

从源码运行还需要 pnpm 10 或更高版本。macOS 可以使用 Homebrew 安装 Node.js 和 pnpm：

```bash
brew install node pnpm
```

### 安装依赖

进入项目目录后执行：

```bash
pnpm install
```

### 配置 YApi

复制环境变量示例：

```bash
cp .env.example .env
```

编辑 `.env`：

```dotenv
YAPI_HOST=https://yapi.example.com
YAPI_COOKIE=_yapi_token=xxx;_yapi_uid=xx;
```

参数说明：

- `YAPI_HOST`：YApi 服务地址，只填写协议和域名，不要包含 `/api`。
- `YAPI_COOKIE`：访问 YApi 时使用的完整 Cookie 字符串。
- `YAPI_LOG_FILE`：可选的日志文件路径，默认是 `~/.yapi-mcp/logs/yapi-mcp.log`。

可以在登录 YApi 后，通过浏览器开发者工具的 Network 面板选择任意 YApi 请求，从 Request Headers 中复制 `Cookie`。Cookie 等同于登录凭据，不要提交到 Git 或分享给其他人；本项目已经默认忽略 `.env`。

### 启动 Server

在项目根目录运行：

```bash
pnpm start
```

这是一个 stdio MCP Server。直接启动后没有普通的 HTTP 页面，也不会打印交互提示；它会等待 MCP 客户端通过标准输入输出进行通信。

启动成功后，Server 会通过 stderr 输出类似信息，不会污染用于 MCP 通信的 stdout：

```text
[yapi-mcp] server started (stdio), tools=9, log=~/.yapi-mcp/logs/yapi-mcp.log
```

运行测试：

```bash
pnpm test
```

## 使用

接入后，可以直接用自然语言让 AI 客户端操作 YApi。

### 查询项目与接口

```text
获取 YApi 项目 1922 的详情。
```

```text
列出 YApi 项目 1922 的所有接口分类。
```

```text
在 YApi 项目 1922 中搜索路径包含 /order 的接口，并获取匹配接口的常用定义。
```

`yapi_get_interface` 默认只返回以下常用信息：

- 接口 ID、标题、HTTP 方法和路径
- 接口描述
- Path、Query、Header 和 Body 入参
- 响应类型和响应内容

需要排查 YApi 元数据或获取原始响应时，可以明确要求使用 `full: true`：

```text
获取 YApi 接口 5001 的原始全量数据。
```

### 创建接口分类

```text
在 YApi 项目 1922 中创建一个名为“订单管理”的接口分类。
```

### 创建接口

```text
在 YApi 项目 1922、分类 3001 中创建接口：
标题为“创建订单”，方法为 POST，路径为 /orders，
请求体类型为 JSON，请求示例为 {"productId": 1001, "quantity": 2}，
响应示例为 {"id": 9001, "status": "created"}。
```

创建接口时的必填参数：

| 参数 | 说明 |
| --- | --- |
| `projectId` | YApi 项目 ID |
| `categoryId` | 接口分类 ID |
| `title` | 接口标题 |
| `path` | 以 `/` 开头的接口路径 |
| `method` | HTTP 方法，例如 `GET`、`POST` |

`requestBody` 和 `responseBody` 需要传入字符串。如果内容是 JSON 或 JSON Schema，也需要先序列化成字符串。

### 更新接口

```text
把 YApi 接口 5001 的标题修改为“查询订单详情”，状态修改为 done，并添加 order 标签。
```

更新接口只需要提供接口 ID 和需要修改的字段，未提供的字段不会发送给 YApi。

## 日志与调用统计

Server 默认把日志写入：

```text
~/.yapi-mcp/logs/yapi-mcp.log
```

日志采用 JSON Lines 格式，每行一个事件。例如：

```json
{"timestamp":"2026-08-21T08:00:00.000Z","event":"tool_call","tool":"yapi_get_interface","status":"success","durationMs":128}
```

工具日志只记录工具名、调用状态和耗时，不记录调用参数、接口内容、Cookie 或其他凭据。

日志追加后如果超过 1000 条记录，Server 会自动删除最早的 300 条，避免日志文件持续增长。

查看工具调用频次、成功数、失败数和平均耗时：

```bash
# 全局安装
yapi-mcp-stats

# 从源码运行
pnpm stats
```

通过 `YAPI_LOG_FILE` 可以修改日志位置。使用相对路径时，相对于 Server 的启动目录解析；MCP 客户端中建议配置绝对路径。

## 常见问题

### 返回“请登录”或没有权限

检查以下内容：

- `YAPI_COOKIE` 是否完整、是否已经过期。
- 当前 Cookie 对应的用户是否有项目访问或编辑权限。
- 修改 Cookie 后是否重新启动了 MCP Server。

### 客户端找不到 Server

- 执行 `node --version`，确认版本不低于 18。
- 执行 `npx --version`，确认 MCP 客户端可以找到 `npx`。
- 在终端执行 `npx -y yapi-mcp-bridge@1`，确认 Server 可以启动。
- 查看 MCP 客户端日志，确认 `YAPI_HOST` 和 `YAPI_COOKIE` 已传给 Server。

### 修改 `.env` 后没有生效

`.env` 默认从 Server 的当前工作目录加载。终端启动时请在项目根目录运行 `pnpm start`；MCP 客户端启动时建议通过配置中的 `env` 显式传入 `YAPI_HOST` 和 `YAPI_COOKIE`。

## 项目结构

```text
src/
├── handlers/       # MCP 工具 handler 与 YApi 方法映射
├── tools/          # 工具定义、Zod 输入输出 Schema
├── index.js        # stdio Server 入口
├── server.js       # McpServer 注册
└── yapi.js         # YApi HTTP API 封装
test/               # 单元测试与 MCP 注册测试
```

## 安全提示

- 不要提交 `.env` 或 YApi Cookie。
- 写入工具会真实修改 YApi 数据，执行前应确认项目 ID、分类 ID 和接口 ID。
- 建议使用权限范围尽可能小的 YApi 账号。
- 默认日志保存在用户目录下的 `.yapi-mcp/logs/`，不会写入 npm 安装目录。