# YApi MCP Bridge

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

## 功能

当前提供以下工具：

| 工具 | 用途 | 类型 |
| --- | --- | --- |
| `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 客户端误执行不可逆操作。

## 使用 npm 安装

无需克隆仓库，可以直接运行：

```bash
npx -y yapi-mcp-bridge
```

也可以全局安装：

```bash
npm install -g yapi-mcp-bridge
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
```

## 接入 MCP 客户端

使用 npm 包时，在支持 stdio MCP Server 的客户端中添加以下配置：

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

如果使用源码启动，可以继续使用 Node.js 绝对路径配置：

```json
{
  "command": "node",
  "args": ["/absolute/path/to/yapi-mcp-server/src/index.js"],
  "env": {
    "YAPI_HOST": "https://yapi.example.com",
    "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
  }
}
```

修改配置后，重启或重新加载 MCP 客户端。客户端应能发现 9 个以 `yapi_` 开头的工具。

## 使用

接入后，可以直接用自然语言让 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

- 确认 MCP 配置中的 `src/index.js` 使用绝对路径。
- 确认 `command` 指向可执行的 Node.js。
- 在项目目录执行 `pnpm test`，确认依赖和运行环境正常。

### 修改 `.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 安装目录。