@zengjing/yapi-mcp

v1.0.0

Published

a month ago

YApi MCP server for querying and managing API documentation

0High
0Medium
0Low

zengjing

mcp yapi api documentation interface model-context-protocol claude

YApi MCP Server

一个轻量级 MCP（Model Context Protocol）服务器，让 Claude、Cursor 等 AI 助手直接查询和管理 YApi 接口文档。

通过 stdio 传输协议启动，可与任意支持 MCP 的客户端对接；提供 10 个常用工具，覆盖项目、分类、接口的查询、搜索、解析等场景。

📑 目录

✨ 功能特性

📚 接口文档查询 — 获取完整的 API 规范和请求/响应详情
🔍 智能搜索 — 9 个搜索和查询工具，按路径、名称、分类、标签查找接口
📁 项目管理 — 获取和列出 YApi 项目详情
🏷️ 分类浏览 — 按分类查看接口、菜单导航
🔗 URL 解析 — 直接粘贴 YApi 链接自动提取项目 ID 与接口 ID
✅ 健康检查 — Ping YApi 服务验证连接
🛡️ 错误处理 — 提供可操作的错误建议和排查指引
🧰 多种配置方式 — 命令行参数、YAML 配置文件、环境变量均可

🚀 快速开始

安装

npm install -g @zengjing/yapi-mcp

或在项目中本地安装：

npm install --save-dev @zengjing/yapi-mcp

配置 Token

YApi Token 的获取方式：

登录 YApi
右上角个人资料 → Settings
在 Authentication 部分生成或复制 Token

推荐使用项目级配置文件：

cp .yapienv.example .yapienv
# 编辑 .yapienv 填入 baseUrl 与 token

.yapienv 内容示例：

yapiBaseUrl: https://yapi.example.com
yapiToken:
  - 100:your-token-here
  - 200:another-token
yapiTimeout: 30000
yapiLogLevel: warn
yapiCacheTtl: 0

启动

yapi-mcp --stdio
# 或
node /path/to/yapi-mcp/dist/index.js --stdio

启动成功后看到 ✓ YApi MCP server started successfully 即表示可用。

🔧 支持的工具

| 工具名 | 功能说明 | 典型使用场景 | |--------|---------|------------| | yapi_list_projects | 列出所有已配置项目 | 首次接入、获取 project_id | | yapi_project_get | 获取指定项目的详细信息 | 确认项目元信息、env 配置 | | yapi_search_apis | 按路径/名称/标签搜索接口 | 不知道接口 ID 时智能检索 | | yapi_interface_get | 根据 ID 获取接口完整定义 | 已知 ID 取请求/响应 schema | | yapi_interface_list | 列出项目下所有接口 | 浏览整个项目接口 | | yapi_interface_list_cat | 列出分类下的接口 | 按分类精确过滤 | | yapi_interface_list_menu | 获取项目菜单导航结构 | 了解项目分类体系 | | yapi_interface_get_cat_menu | 获取指定分类的菜单详情 | 单分类深度浏览 | | yapi_parse_url | 解析 YApi URL 提取 ID | 粘贴链接直接定位接口 | | yapi_ping | 检查 YApi 服务连通性 | 排查连接问题 |

💡 推荐工作流：yapi_list_projects → yapi_search_apis → yapi_interface_get，或者直接粘贴 YApi 链接用 yapi_parse_url 一步到位。

⚙️ 配置

支持 4 种配置方式，优先级从高到低：

| 优先级 | 方式 | 适用场景 | |--------|------|---------| | 1 | 命令行参数 | 临时调试、CI 环境 | | 2 | 项目级 .yapienv | 当前项目专用配置（推荐） | | 3 | 全局 ~/.yapienv | 跨项目共享配置 | | 4 | 环境变量 .env / shell | 容器化部署 |

方式一：项目级配置文件（推荐）

在项目根目录创建 .yapienv：

cp .yapienv.example .yapienv

支持两种 token 格式：

数组格式（推荐，可读性更好）：

yapiBaseUrl: https://yapi.example.com
yapiToken:
  - 100:token-for-project-100
  - 200:token-for-project-200
yapiTimeout: 30000
yapiLogLevel: warn
yapiCacheTtl: 0

字符串格式（逗号分隔）：

yapiBaseUrl: https://yapi.example.com
yapiToken: 100:token1,200:token2,300:token3
yapiTimeout: 30000
yapiLogLevel: warn
yapiCacheTtl: 0

方式二：全局配置文件

cp .yapienv.example ~/.yapienv
# 所有项目共享此配置

方式三：命令行参数

node dist/index.js --stdio \
  --yapi-base-url=https://yapi.example.com \
  --yapi-token=100:token1,200:token2 \
  --yapi-timeout=30000 \
  --yapi-log-level=info \
  --yapi-cache-ttl=300

可选项：

| 参数 | 默认值 | 说明 | |------|--------|------| | --stdio | — | 使用 stdio 传输（MCP 默认） | | --yapi-base-url=<URL> | — | YApi 实例 URL | | --yapi-token=<TOKEN> | — | projectId:token 列表（逗号分隔） | | --yapi-timeout=<MS> | 30000 | 请求超时时间（毫秒） | | --yapi-log-level=<LEVEL> | warn | trace/debug/info/warn/error | | --yapi-cache-ttl=<SEC> | 0 | 缓存过期时间（秒，0=不缓存） | | --debug | — | 打印配置来源信息 | | --help, -h | — | 显示帮助信息 |

方式四：环境变量

export YAPI_BASE_URL=https://yapi.example.com
export YAPI_TOKEN=100:token1,200:token2
export YAPI_TIMEOUT=30000
export YAPI_LOG_LEVEL=warn
export YAPI_CACHE_TTL=0
node dist/index.js --stdio

也可以使用 .env 文件（备用方案，优先级最低）：

YAPI_BASE_URL=https://yapi.example.com
YAPI_TOKEN=100:token1,200:token2

🤖 客户端集成

Claude Code

编辑 ~/.claude/settings.json：

{
  "mcpServers": {
    "yapi": {
      "command": "yapi-mcp",
      "args": [
        "--stdio",
        "--yapi-base-url=https://yapi.example.com",
        "--yapi-token=<YOUR_TOKEN>"
      ]
    }
  }
}

如果本地开发，可使用 node 启动：

{
  "mcpServers": {
    "yapi": {
      "command": "node",
      "args": [
        "/absolute/path/to/yapi-mcp/dist/index.js",
        "--stdio"
      ]
    }
  }
}

Cursor

在 ~/.cursor/mcp.json（或项目级 .cursor/mcp.json）中添加：

{
  "mcpServers": {
    "yapi": {
      "command": "yapi-mcp",
      "args": ["--stdio"]
    }
  }
}

其他 MCP 客户端

任何支持 stdio 传输的 MCP 客户端都可以通过 yapi-mcp --stdio 启动该服务器。

💻 本地开发

# 克隆仓库
git clone https://github.com/hhtczengjing/yapi-mcp.git
cd yapi-mcp

# 安装依赖
npm install

# 开发模式（ts-node 热运行）
npm run dev

# 类型检查
npm run lint

# 构建产物
npm run build

# 清理构建产物
npm run clean

# 完整流程
npm run clean && npm run build

构建产物输出到 dist/ 目录，可执行入口：

dist/index.js — MCP 服务器主入口
dist/debug.js — 配置来源调试工具（--debug 时调用）

调试配置来源（打印最终生效的配置及来源）：

node dist/index.js --debug

🛠 常见问题

1. 启动时报 "YApi ping failed"

检查 yapiBaseUrl 是否可访问（浏览器打开试试）
确认网络通畅，企业内网需要 VPN
检查 token 格式是否正确：projectId:token（注意是英文冒号）
降低防火墙/代理限制

2. 报 "Invalid token" 或 401

Token 与 projectId 不匹配：在 YApi 项目设置 → token 配置中核对
Token 已被重置：重新生成
多项目时确认每个 token 对应的 projectId 正确

3. 接口搜索为空

先用 yapi_list_projects 确认项目可访问
尝试更宽松的关键词（路径片段、名称部分字符）
用 yapi_interface_list_menu 查看分类树再精确定位

4. 配置没生效

优先级：命令行 > 项目 .yapienv > ~/.yapienv > 环境变量 > .env
用 node dist/index.js --debug 查看实际生效的配置及来源
项目 .yapienv 必须是合法 YAML，注意缩进

5. Claude Code 中看不到 yapi 工具

检查 ~/.claude/settings.json 配置后重启 Claude Code
路径使用绝对路径
在终端手动运行 yapi-mcp --stdio 看是否报错

更多问题请前往 GitHub Issues 反馈。

📁 项目结构

yapi-mcp/
├── bin/
│   └── yapi-mcp              # CLI 启动脚本（npm 全局安装后可直接调用）
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── debug.ts              # 配置来源调试工具
│   ├── client/
│   │   └── yapi-client.ts    # YApi HTTP 客户端封装
│   ├── tools/
│   │   ├── interfaces-extended.ts  # 接口/项目相关工具
│   │   ├── utils.ts                # ping 等辅助工具
│   │   └── url-parser.ts           # URL 解析工具
│   ├── utils/
│   │   ├── config.ts         # 多源配置加载与优先级合并
│   │   ├── error-handler.ts  # 统一错误处理
│   │   ├── formatter.ts      # 输出格式化
│   │   └── logger.ts         # 日志工具
│   └── types/                # 类型定义
├── .yapienv.example          # 配置文件示例
├── .github/workflows/        # CI 配置
├── package.json
├── tsconfig.json
└── README.md

📦 相关资源

MCP 协议：https://modelcontextprotocol.io/
YApi 项目：https://github.com/YMFE/yapi
YApi OpenAPI 文档：https://hellosean1025.github.io/yapi/openapi.html
Model Context Protocol SDK：https://github.com/modelcontextprotocol/typescript-sdk