# yapi-mcp

YApi MCP Server —— 基于 Model Context Protocol（MCP）的 YApi 接口查询服务，通过 stdio 方式启动，可被 Trae、Codex 等 MCP 客户端直接集成。

## 功能概述

提供三个核心工具，帮助 AI 助手快速获取 YApi 上的接口信息：

| 工具名称         | 别名                        | 说明                 |
| ---------------- | --------------------------- | -------------------- |
| `get_api_list`   | `yapi_list_interfaces`      | 获取项目完整接口列表 |
| `get_api_detail` | `yapi_get_interface_detail` | 根据接口 ID 获取详情 |
| `search_api`     | `yapi_search_interfaces`    | 按关键字搜索接口     |

> 旧名称和中文别名均可使用，功能完全相同。

## 环境要求

- **Node.js** >= 18
- 可访问的 YApi 服务

## 快速开始

### 1. 安装依赖并构建

```bash
npm install
npm run build
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env`，填入实际值：

```env
YAPI_BASE_URL=http://127.0.0.1:3000
YAPI_TOKEN=replace-with-your-yapi-token
YAPI_PROJECT_ID=1
```

| 变量名            | 必填 | 说明                                                            |
| ----------------- | ---- | --------------------------------------------------------------- |
| `YAPI_BASE_URL`   | 是   | YApi 服务根地址，如 `http://127.0.0.1:3000`，不要填项目页面地址 |
| `YAPI_TOKEN`      | 是   | YApi 项目级 Token，在项目设置中获取                             |
| `YAPI_PROJECT_ID` | 否   | 默认项目 ID，建议配置，可避免每次调用时手动传入                 |

### 3. 启动服务

```bash
npm start
```

或开发模式（无需构建，直接运行 TypeScript）：

```bash
npm run dev
```

## 客户端配置

### Trae

在项目根目录创建 `.trae/mcp.json`：

```json
{
  "mcpServers": {
    "yapi": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "http://127.0.0.1:3000",
        "YAPI_TOKEN": "replace-with-your-yapi-token",
        "YAPI_PROJECT_ID": "1",
        "START_MCP_TIMEOUT_MS": "60000",
        "RUN_MCP_TIMEOUT_MS": "60000"
      }
    }
  }
}
```

- 发布到npm上的使用方式

```json
{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["-y", "mcp-yapi"],
      "env": {
        "YAPI_BASE_URL": "http://127.0.0.1:3000",
        "YAPI_TOKEN": "replace-with-your-yapi-token",
        "YAPI_PROJECT_ID": "1",
        "START_MCP_TIMEOUT_MS": "60000",
        "RUN_MCP_TIMEOUT_MS": "60000"
      }
    }
  }
}
```

也可将上述 JSON 粘贴到 Trae 的 MCP 手动配置中实现全局配置。

### Codex

在 `~/.codex/config.toml` 或项目级 `.codex/config.toml` 中添加：

```toml
[mcp_servers.yapi]
command = "node"
args = ["/path/to/yapi-mcp/dist/index.js"]
cwd = "/path/to/yapi-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60

[mcp_servers.yapi.env]
YAPI_BASE_URL = "http://127.0.0.1:3000"
YAPI_TOKEN = "replace-with-your-yapi-token"
YAPI_PROJECT_ID = "1"
```

> 请将 `/path/to/yapi-mcp` 替换为项目的实际路径。

### CodeBuddy

在 CodeBuddy 的 MCP 配置中添加：

- 本地项目方式：

```json
{
  "mcpServers": {
    "yapi": {
      "command": "node",
      "args": ["/path/to/mcp-yapi/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "http://127.0.0.1:3000",
        "YAPI_TOKEN": "replace-with-your-yapi-token",
        "YAPI_PROJECT_ID": "1"
      }
    }
  }
}
```

- npm 包方式：

```json
{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["-y", "mcp-yapi"],
      "env": {
        "YAPI_BASE_URL": "http://127.0.0.1:3000",
        "YAPI_TOKEN": "replace-with-your-yapi-token",
        "YAPI_PROJECT_ID": "1"
      }
    }
  }
}
```

> 请将 `/path/to/mcp-yapi` 替换为项目的实际路径。

### Cursor / VS Code + Cline 等

任何支持 stdio 模式的 MCP 客户端均可接入，核心配置项：

- **command**: `node`
- **args**: `["/path/to/mcp-yapi/dist/index.js"]`
- **env**: 按上方环境变量表格配置

## 工具详情

### get_api_list / yapi_list_interfaces

获取指定 YApi 项目的完整接口列表，自动分页获取全量数据。

**参数：**

| 参数        | 类型   | 必填 | 说明                                          |
| ----------- | ------ | ---- | --------------------------------------------- |
| `projectId` | number | 否   | 项目 ID，不传则使用环境变量 `YAPI_PROJECT_ID` |

**返回示例：**

```json
{
  "errcode": 0,
  "data": {
    "project_id": 1,
    "total_pages": 1,
    "fetched_count": 25,
    "list": [
      {
        "_id": 101,
        "title": "用户登录",
        "path": "/api/user/login",
        "method": "POST"
      }
    ]
  }
}
```

### get_api_detail / yapi_get_interface_detail

根据接口 ID 获取完整详情，包含请求参数、响应结构等信息。

**参数：**

| 参数 | 类型   | 必填 | 说明    |
| ---- | ------ | ---- | ------- |
| `id` | number | 是   | 接口 ID |

**返回示例：**

```json
{
  "errcode": 0,
  "data": {
    "_id": 101,
    "title": "用户登录",
    "path": "/api/user/login",
    "method": "POST",
    "req_body_type": "json",
    "req_body_other": "{ ... }",
    "res_body_type": "json",
    "res_body": "{ ... }"
  }
}
```

### search_api / yapi_search_interfaces

根据关键字搜索接口，使用 YApi 内置搜索 API 并进行本地精确匹配过滤。

**参数：**

| 参数        | 类型   | 必填 | 说明                                          |
| ----------- | ------ | ---- | --------------------------------------------- |
| `keyword`   | string | 是   | 搜索关键字，匹配接口名称和路径                |
| `projectId` | number | 否   | 项目 ID，不传则使用环境变量 `YAPI_PROJECT_ID` |

**返回示例：**

```json
{
  "keyword": "login",
  "total": 2,
  "list": [
    {
      "id": 101,
      "title": "用户登录",
      "path": "/api/user/login",
      "method": "POST"
    },
    {
      "id": 102,
      "title": "登录日志",
      "path": "/api/user/loginLog",
      "method": "GET"
    }
  ]
}
```

## 项目结构

```
yapi-mcp/
├── index.ts                  # 入口文件（含 shebang）
├── src/
│   ├── index.ts              # 加载 MCP Server
│   ├── config/
│   │   └── yapi.ts           # 环境变量解析与校验
│   ├── server/
│   │   └── mcp.ts            # MCP Server 初始化与 stdio 连接
│   ├── services/
│   │   └── yapi.service.ts   # YApi API 请求层
│   ├── tools/
│   │   ├── index.ts          # 工具注册入口
│   │   ├── getApiList.ts      # 接口列表工具
│   │   ├── getApiDetail.ts    # 接口详情工具
│   │   └── searchApi.ts       # 接口搜索工具
│   └── types/
│       └── yapi.ts           # 共享类型定义
├── .env.example              # 环境变量示例
├── .trae/mcp.json.example    # Trae 配置示例
├── package.json
└── tsconfig.json
```

## npm 脚本

| 命令            | 说明                                   |
| --------------- | -------------------------------------- |
| `npm run build` | 编译 TypeScript 到 `dist/`             |
| `npm start`     | 运行编译后的 `dist/index.js`           |
| `npm run dev`   | 开发模式，使用 tsx 直接运行 TypeScript |
| `npm run check` | 仅类型检查，不生成文件                 |

## 常见问题

### 启动时报错 "Missing required environment variable"

请确保已正确配置 `YAPI_BASE_URL` 和 `YAPI_TOKEN` 环境变量。可在 MCP 客户端配置的 `env` 字段中设置，或创建 `.env` 文件。

### 搜索结果不准确

`search_api` 使用 YApi 内置搜索 API 获取结果后，会进行本地二次过滤以确保关键字精确匹配。如果结果仍不理想，可尝试使用更具体的关键字。

### 接口列表不全

`get_api_list` 会自动分页获取全量数据（每页 100 条），无需手动翻页。如果数据量特别大，可能需要等待更长时间。

## 参考

- [Trae 添加 MCP Server](https://www.volcengine.com/docs/86677/2137601?lang=zh)
- [Trae MCP Server 安装链接](https://www.volcengine.com/docs/86677/2137600?lang=zh)
- [Codex MCP 文档](https://developers.openai.com/codex/mcp)
- [Model Context Protocol 规范](https://modelcontextprotocol.io/)