内容
# yapi-mcp
> English | [中文](README.zh-CN.md)
> 一个零依赖的 [YApi](https://github.com/YMFE/yapi) [MCP](https://modelcontextprotocol.io) 服务器，暴露 YApi 的 API 管理能力给 Claude Code 和任何 MCP 客户端。
## 为什么存在
npm 包 `@yogeliu/yapi-mcp-server` 有两个缺陷使其 **完全无法使用**：
1. **损坏的 `inputSchema` 序列化** — 它返回 Zod schema 对象本身作为 `inputSchema`。序列化后变成 `{"_def":...}`，这是一个无效的结构。MCP 客户端拒绝它并提示 `tools fetch failed`，因此没有工具能够加载。
2. **错误的接口列表策略** — YApi 的 `/api/interface/list` **忽略 `catid`** 在大多数版本中，并且默认只返回第一页。原始包的“遍历分类”方法导致大量重复并错过大多数接口；它还读取错误的 ID 字段（`_id`）。
这个项目从头开始重写，具有 **零运行时依赖**（仅 Node ≥18 内置 `fetch`），手写的有效 JSON Schemas 和项目级分页与去重 — 修复了上述所有问题。
## 工具
| 工具 | 描述 |
|---|---|
| `yapi_list_projects` | 列出已配置的项目（ID / 名称 / 描述） |
| `yapi_get_categories` | 列出项目分类和每个分类下的 API |
| `yapi_search_apis` | 按关键词（标题 / 路径）搜索 API，可选方法筛选 |
| `yapi_get_api_details` | 获取一个 API 的完整详情（参数 / 头部 / 正文 / 响应） |
| `yapi_save_api` | 创建或更新一个 API（带 `api_id` → 更新；不带 → 创建） |
## 安装
### 选项 1：npx（推荐）
无需安装 — 直接在 MCP 配置中使用：
```json
{ "command": "npx", "args": ["-y", "@hizml/yapi-mcp"] }
```
### 选项 2：克隆
```bash
git clone https://github.com/hizml/yapi-mcp.git
```
在配置文件中指向本地文件：
```json
{ "command": "node", "args": ["/绝对路径/to/yapi-mcp/yapi-mcp.mjs"] }
```
## 配置
两个环境变量：
- `YAPI_BASE_URL` — YApi 主机，例如 `http://yapi.example.com`
- `YAPI_TOKEN` — 格式 `projectId:tokenValue`，来自 YApi 项目的“设置 → token”
### Claude Code (`~/.claude.json`)
```json
{
"mcpServers": {
"yapi": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@hizml/yapi-mcp"],
"env": {
"YAPI_BASE_URL": "http://您的-yapi-主机",
"YAPI_TOKEN": "227:您的_token_值"
}
}
}
}
```
完整示例：[`examples/claude-code-config.json`](examples/claude-code-config.json)。
## 功能
- **零依赖** — 纯 Node ESM，仅 Node ≥18 内置 `fetch`
- **有效 JSON Schema** — 每个 `inputSchema` 都是手写的标准 JSON Schema，因此客户端可以正确验证
- **完整分页** — 项目级分页 + 去重，无缺失或重复 API
- **健壮的错误处理** — 参数错误、超时和 YApi `errcode` 都会变成 `isError` 消息；进程不会崩溃
- **可调试** — 设置 `DEBUG=1` 以将日志输出到 stderr
## 已知限制
- 目前 **单 token（单项目）**；对于多个项目，运行多个实例
- YApi 的 `/api/interface/list` `total` 字段不可靠，因此该工具在分页时遇到页面返回的 API 少于页面大小时会停止分页
## 许可证
MIT
