YApi MCP 服务器

一个 Model Context Protocol (MCP) 服务器，用于自动解析和搜索 YApi 接口文档，提取接口路径、入参、出参等信息，让 AI 助手能够理解并直接使用 YApi 中的 API 接口。

✨ 功能特性

• 🔐 自动登录 - 自动处理 YApi 的 LDAP 登录认证并管理 Cookie
• 📄 接口解析 - 智能解析接口，提取：
  • 接口路径与方法（GET/POST/PUT/DELETE 等）
  • 请求参数（查询 / 路径 / 表单 / 请求体 JSON Schema / 请求头）
  • 响应参数（含完整 JSON Schema）
  • 接口状态、分类与项目信息
• 🔍 接口查询 - 按项目/分类列出接口、按关键字搜索接口
• 🎯 AI 友好 - 返回结构化 JSON，方便 AI 助手理解与二次开发
• ⚡ 即开即用 - 已发布到 npm（@liguangdong/mcp-yapi），通过 npx 直接使用，零源码编译、无需全局安装
• 📦 零冗余依赖 - 仅依赖 MCP SDK，使用 Node.js 内置 fetch，体积更小

🚀 快速开始

本服务器是一个标准 stdio MCP 服务器（仅依赖 @modelcontextprotocol/sdk），因此适用于任何支持本地 MCP 的客户端：Cursor、Claude Code、Codex 和 opencode 均开箱即用，仅配置文件的位置与格式不同。

安装完成后，在所有客户端中都可以直接告诉 AI 助手：

请解析这个 YApi 接口：/project/739/interface/api/128185

AI 助手会自动调用 YApi MCP 服务器，返回接口的详细信息。

📦 安装

本包已发布到 npm，包名为 @liguangdong/mcp-yapi。推荐方式是在各客户端的 MCP 配置里直接用 npx 拉起，无需全局安装、无需下载源码；也支持全局安装后使用 mcp-yapi 命令。两种方式二选一：

# 方式一（推荐）：npx 直接运行，零安装
npx --yes @liguangdong/mcp-yapi

# 方式二：全局安装（所有客户端共用同一个 mcp-yapi 可执行文件，安装一次即可）
npm install -g @liguangdong/mcp-yapi
mcp-yapi

运行上面命令会打印服务器启动日志，说明已可用。

使用 npx 时，每个客户端的配置只需把 command 指向 npx 并传入 @liguangdong/mcp-yapi 作为参数即可，详见下方各客户端示例。

🖥️ Cursor

配置文件：~/.cursor/mcp.json（macOS/Linux）或 %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["--yes", "@liguangdong/mcp-yapi@latest"],
      "env": {
        "YAPI_EMAIL": "your_email",
        "YAPI_PASSWORD": "your_password",
        "YAPI_BASE_URL": "http://yapi.example.com:30000"
      }
    }
  }
}

若已全局安装（npm install -g @liguangdong/mcp-yapi），可简化为 "command": "mcp-yapi", "args": []。

保存后重启 Cursor 使配置生效。

🧠 Claude Code

推荐方式（命令行添加，用户级跨项目生效）：

claude mcp add --transport stdio yapi -- npx --yes @liguangdong/mcp-yapi@latest \
  --env YAPI_EMAIL=your_email \
  --env YAPI_PASSWORD=your_password \
  --env YAPI_BASE_URL=http://yapi.example.com:30000

注意 -- 后面的参数会原样传给服务器命令；--env 需放在 -- 之前。若已全局安装，可把 npx --yes @liguangdong/mcp-yapi@latest 换成 mcp-yapi。

或使用项目级 .mcp.json（可提交到版本库供团队共享）：

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["--yes", "@liguangdong/mcp-yapi@latest"],
      "env": {
        "YAPI_EMAIL": "your_email",
        "YAPI_PASSWORD": "your_password",
        "YAPI_BASE_URL": "http://yapi.example.com:30000"
      }
    }
  }
}

在 Claude Code 会话内用 /mcp 检查服务器连接状态。

⭕ Codex (OpenAI)

配置文件：~/.codex/config.toml（TOML 格式）

[mcp_servers.yapi]
command = "npx"
args = ["--yes", "@liguangdong/mcp-yapi@latest"]

[mcp_servers.yapi.env]
YAPI_EMAIL = "your_email"
YAPI_PASSWORD = "your_password"
YAPI_BASE_URL = "http://yapi.example.com:30000"

保存后在 Codex 会话中重启即可。可选字段：enabled = true、cwd = "/path"、startup_timeout_sec = 10、tool_timeout_sec = 60。

⚡ opencode

配置文件：opencode.json（项目根目录或全局 ~/.config/opencode/opencode.json）

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yapi": {
      "type": "local",
      "command": ["npx", "--yes", "@liguangdong/mcp-yapi@latest"],
      "enabled": true,
      "environment": {
        "YAPI_EMAIL": "your_email",
        "YAPI_PASSWORD": "your_password",
        "YAPI_BASE_URL": "http://yapi.example.com:30000"
      }
    }
  }
}

保存后退出并重启 opencode 使配置生效。

⚙️ 配置参数

支持通过环境变量或 .env 文件配置：

| 参数 | 必需 | 说明 | |------|------|------| | YAPI_EMAIL | ⭕* | YApi 登录邮箱/用户名（与 YAPI_PASSWORD 搭配，走账号密码登录） | | YAPI_PASSWORD | ⭕* | YApi 登录密码 | | YAPI_TOKEN | ⭕* | YApi 登录 token（_yapi_token）。配置了 token 就无需账号密码 | | YAPI_BASE_URL | ✅ 推荐 | YApi 服务器地址，如 http://yapi.example.com:30000。未设置时，可通过接口的完整 URL 自动推断 | | YAPI_LOGIN_TYPE | ⭕ | 登录方式，默认 ldap。可选：ldap（LDAP 账号）、local（本地注册账号）、token、auto（自动依次尝试 local→ldap→token） | | YAPI_DEBUG | ⭕ | 调试模式开关，设为 true 启用详细日志输出（默认 false） |

* 认证二选一：要么配置 YAPI_TOKEN，要么配置 YAPI_EMAIL + YAPI_PASSWORD，无需两者都填。

📄 使用 .env 文件

如果不想在 MCP 配置中写环境变量，可以在项目根目录创建 .env 文件（从 v1.5.0 开始支持）：

# .env
YAPI_BASE_URL=http://yapi.example.com:30000
YAPI_EMAIL=your_email
YAPI_PASSWORD=your_password
# 或者使用 token
# YAPI_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....

然后 MCP 配置可以简化为：

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["--yes", "@liguangdong/mcp-yapi@latest"]
    }
  }
}

⚠️ 注意：.env 文件中的敏感信息（密码、token）不应提交到版本控制系统，请将 .env 添加到 .gitignore。

🔐 认证方式一：账号密码（LDAP / 本地）

适合愿意在配置里写账号密码的情况。默认走 LDAP，本地账号请设 YAPI_LOGIN_TYPE=local，不确定用 auto。

🔑 认证方式二：直接粘贴 token（推荐，无需账号密码）

如果不想在 MCP 配置里写账号密码，可直接粘贴 YApi 的登录 token（_yapi_token）。token 是一个 JWT，登录 YApi 后可从浏览器 Cookie 或登录响应中复制。

// Cursor / Claude Code / 项目 .mcp.json
{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["--yes", "@liguangdong/mcp-yapi@latest"],
      "env": {
        "YAPI_TOKEN": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
        "YAPI_BASE_URL": "http://yapi.example.com:30000"
      }
    }
  }
}

# Codex: ~/.codex/config.toml
[mcp_servers.yapi]
command = "npx"
args = ["--yes", "@liguangdong/mcp-yapi@latest"]
[mcp_servers.yapi.env]
YAPI_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
YAPI_BASE_URL = "http://yapi.example.com:30000"

// opencode: opencode.json
{
  "mcp": {
    "yapi": {
      "type": "local",
      "command": ["npx", "--yes", "@liguangdong/mcp-yapi@latest"],
      "environment": {
        "YAPI_TOKEN": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
        "YAPI_BASE_URL": "http://yapi.example.com:30000"
      }
    }
  }
}

token 会过期（JWT 有有效期），过期后重新登录 YApi 复制新 token 更新配置即可。

关于登录方式：使用账号密码时，默认只走 LDAP 登录。如果你的账号是 YApi 的本地注册账号（非 LDAP），登录时会一直卡住或失败。请将该参数设置为：

• 本地账号：YAPI_LOGIN_TYPE=local
• 不确定/想自动兼容：YAPI_LOGIN_TYPE=auto

配合内置的 15 秒请求超时，即使 YApi 服务器的 LDAP 长时间无响应，也会快速返回清晰错误，而不会让工具调用一直卡住。

🛠️ 提供的工具

1. parse_yapi_documentation — 解析单个接口

解析接口文档，提取路径、入参、出参信息。

参数：

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | url | string | ✅ | 接口 URL 或相对路径，如 /project/739/interface/api/128185 | | includeSchema | boolean | ⭕ | 是否包含完整 JSON Schema（默认 true） |

示例返回：

{
  "title": "导出方案",
  "path": "/app/example.do",
  "method": "POST",
  "description": "",
  "status": "done",
  "project_id": 739,
  "catid": 7882,
  "requestParams": [
    {
      "name": "body",
      "type": "object",
      "required": true,
      "description": "请求体",
      "location": "body"
    }
  ],
  "responseParams": {
    "description": "",
    "schema": {
      "type": "object",
      "properties": {
        "code": { "type": "string" },
        "success": { "type": "boolean" }
      }
    }
  }
}

2. list_project_interfaces — 列出项目接口

列出指定项目（或指定分类）下的所有接口。

参数：

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | projectId | string/number | ✅ | 项目 ID | | catid | string/number | ⭕ | 分类 ID，仅列出该分类下的接口 | | keyword | string | ⭕ | 按标题/路径过滤关键字 |

示例：

请列出项目 739 下的所有接口

3. search_interfaces — 搜索接口

在指定项目中按关键字搜索接口（标题、路径等）。

参数：

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | projectId | string/number | ✅ | 项目 ID | | keyword | string | ✅ | 搜索关键字 |

示例：

在项目 739 中搜索包含“导出”的接口

📖 使用方法

配置好 MCP 服务器并重启对应客户端后，直接对 AI 助手说自然语言即可，AI 会自动调用对应的工具。

示例：解析单个接口

请解析这个 YApi 接口：/project/2822/interface/api/136274

或传完整 URL（会基于 YAPI_BASE_URL 或 URL 本身推断）：

请解析 http://172.31.3.22:30000/project/2822/interface/api/136274

只想要精简结果（不带完整 JSON Schema）：

解析 /project/2822/interface/api/136274，只要字段列表，不要完整 schema

示例：列出项目/分类下的接口

列出项目 2822 下的所有接口
列出项目 2822 分类 23134 下的接口
列出项目 2822 中路径包含 expense 的接口

示例：按关键字搜索接口

在项目 2822 中搜索包含“打卡”的接口

基于接口生成代码

根据接口 /project/2822/interface/api/136274 生成 TypeScript 的请求函数和类型定义

提示：MCP 配置在客户端启动时加载，新增或修改配置后需要重启客户端（Cursor / Claude Code / Codex / opencode）才会生效。

📁 项目结构

mcp-yapi/
├── src/
│   ├── index.js              # 入口：读取配置并启动 MCP 服务器（stdio）
│   ├── server.js             # MCP 服务器：注册工具与请求分发
│   ├── config.js             # 环境变量配置读取与校验
│   ├── auth/
│   │   └── index.js          # 认证：token 或 账号密码 统一入口
│   ├── clients/
│   │   └── yapi-client.js    # YApi HTTP 接口调用（登录/详情/列表）
│   ├── services/
│   │   └── yapi-service.js   # 业务编排：认证+调用+解析，供工具调用
│   ├── utils/
│   │   ├── http.js           # 带超时的 fetch、JSON 请求、Cookie 解析
│   │   └── token.js          # YApi token(JWT) 解析与 cookie 构造
│   └── parser/
│       └── index.js          # 接口文档解析器（提取入参/出参）
├── test/                     # 单元测试（node:test）
│   ├── parser.test.js
│   ├── yapi-client.test.js
│   └── token.test.js
├── scripts/
│   ├── smoke.js              # 无网络冒烟测试
│   └── integration-check.mjs # MCP 协议集成测试（连模拟客户端）
├── .github/workflows/        # CI 与 npm 发布流水线
├── package.json
└── README.md

分层说明：

• 入口/配置 (index.js, server.js, config.js)：只管启动与请求分发。
• 认证 (auth/)：决定用 token 还是账号密码，与具体工具解耦。
• HTTP 客户端 (clients/)：只做 YApi 接口调用，不含业务逻辑。
• 业务服务 (services/)：组合认证+调用+解析，供工具直接使用。
• 工具函数 (utils/)：可复用的底层能力（HTTP 超时、token 解析）。
• 解析器 (parser/)：纯函数，最易单元测试。

🛠️ 技术栈

• Node.js (>= 18) - 运行环境，使用内置全局 fetch
• @modelcontextprotocol/sdk - MCP SDK（Server + StdioServerTransport）

⚙️ 本地开发

npm install
npm test          # 运行单元测试
npm run lint      # 语法检查
npm run smoke     # 无网络冒烟测试

# 启动服务器（需要环境变量）
export YAPI_EMAIL="your_email"
export YAPI_PASSWORD="your_password"
export YAPI_BASE_URL="http://yapi.example.com:30000"
npm start

📄 许可证

MIT License

🔗 相关链接

• Model Context Protocol
• YApi 官方文档
• Cursor 编辑器