npm package: @liguangdong/mcp-yapi
Description: MCP server for parsing YApi interface documentation - automatically extracts API paths, request parameters, and response parameters. Supports default configuration for easier setup.
Latest version: 1.1.0

# YApi MCP 服务器

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![npm version](https://img.shields.io/npm/v/@liguangdong/mcp-yapi.svg)](https://www.npmjs.com/package/@liguangdong/mcp-yapi)

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

## ✨ 功能特性

- 🔐 **自动登录** - 自动处理 YApi 系统的 LDAP 登录认证
- 📄 **接口解析** - 智能解析接口文档，提取关键信息：
  - ✅ 接口路径和请求方法（GET/POST/PUT/DELETE 等）
  - ✅ 请求参数（查询参数、路径参数、请求体、请求头等）
  - ✅ 响应参数（包括完整的 JSON Schema）
  - ✅ 接口状态和描述信息
- 🎯 **AI 友好** - 返回结构化的 JSON 格式数据，方便 AI 助手理解
- ⚡ **即开即用** - 通过 npx 直接使用，无需手动安装
- 🔧 **灵活配置** - 支持默认配置和自定义配置

## 🚀 快速开始

### 第一步：配置 MCP 服务器

在 Cursor 的 MCP 配置文件中添加以下配置：

**配置文件位置**：
- macOS/Linux: `~/.cursor/mcp.json`
- Windows: `%USERPROFILE%\.cursor\mcp.json`

**最简配置**（推荐）：

```json
{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": [
        "--yes",
        "@liguangdong/mcp-yapi@latest"
      ],
      "env": {
        "YAPI_EMAIL": "your_email",
        "YAPI_PASSWORD": "your_password"
      }
    }
  }
}
```

### 第二步：重启 Cursor

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

### 第三步：使用 AI 助手解析接口

在 Cursor 中，直接告诉 AI 助手：

```
请解析这个 YApi 接口：http://yapi.example.com:30000/project/739/interface/api/128185
```

AI 助手会自动调用 YApi MCP 服务器，解析接口并返回详细信息！

## 📦 安装方式

### 方式一：通过 npx 使用（推荐）⭐

无需安装，直接在 MCP 配置中使用 npx：

```json
{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["--yes", "@liguangdong/mcp-yapi@latest"],
      "env": {
        "YAPI_EMAIL": "your_email",
        "YAPI_PASSWORD": "your_password"
      }
    }
  }
}
```

### 方式二：全局安装

```bash
npm install -g @liguangdong/mcp-yapi
```

### 方式三：从源码安装（开发者）

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

# 安装依赖
npm install

# 本地链接（用于测试）
npm link
```

## ⚙️ 配置详解

### 配置参数说明

| 参数 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| `YAPI_EMAIL` | ✅ 是 | 无 | YApi 登录邮箱/用户名 |
| `YAPI_PASSWORD` | ✅ 是 | 无 | YApi 登录密码 |
| `YAPI_BASE_URL` | ⭕ 否 | `http://172.31.3.22:30000` | YApi 服务器地址 |
| `NODE_ENV` | ⭕ 否 | `production` | 运行环境 |

### 配置示例

#### 1️⃣ 最简配置（使用默认服务器）

如果使用默认的 YApi 服务器地址（`http://172.31.3.22:30000`），只需配置账号密码：

```json
{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["--yes", "@liguangdong/mcp-yapi@latest"],
      "env": {
        "YAPI_EMAIL": "your_email",
        "YAPI_PASSWORD": "your_password"
      }
    }
  }
}
```

**参数说明**：
- `--yes`：自动确认 npx 安装提示
- `@latest`：始终使用最新版本

#### 2️⃣ 完整配置（自定义服务器地址）

如果你的 YApi 服务器地址不同，需要指定 `YAPI_BASE_URL`：

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

#### 3️⃣ 本地开发配置

如果你在本地开发这个项目：

```json
{
  "mcpServers": {
    "yapi": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-yapi/src/index.js"],
      "env": {
        "YAPI_EMAIL": "your_email@example.com",
        "YAPI_PASSWORD": "your_password",
        "YAPI_BASE_URL": "http://172.31.3.22:30000"
      }
    }
  }
}
```

**注意**：本地开发时必须使用绝对路径。

## 📖 使用方法

### 在 Cursor AI 中使用

配置好 MCP 服务器后，你可以直接在 Cursor 中与 AI 助手对话：

#### 示例 1：解析单个接口

```
请帮我解析这个 YApi 接口：
http://172.31.3.22:30000/project/739/interface/api/128185
```

AI 助手会自动调用 YApi MCP 服务器，返回接口的详细信息，包括：
- 接口路径和方法
- 请求参数（含类型、是否必填、描述）
- 响应参数结构
- 使用示例代码

#### 示例 2：基于接口生成代码

```
根据 YApi 接口 http://172.31.3.22:30000/project/739/interface/api/128185 
生成一个 TypeScript 的 API 调用函数
```

AI 助手会解析接口后，自动生成对应的 TypeScript 代码。

#### 示例 3：批量处理接口

```
请解析以下接口并生成 API 文档：
1. http://172.31.3.22:30000/project/739/interface/api/128185
2. http://172.31.3.22:30000/project/739/interface/api/128186
```

### 手动测试（开发者）

如果需要手动测试服务器，可以使用以下方法：

#### 方法 1：使用测试脚本

```bash
cd /path/to/mcp-yapi
./test-with-env.sh
```

#### 方法 2：手动设置环境变量

```bash
# 设置环境变量
export YAPI_EMAIL="your_email"
export YAPI_PASSWORD="your_password"
export YAPI_BASE_URL="http://172.31.3.22:30000"

# 启动服务器
npm start
```

**注意**：直接运行 `npm start` 而不设置环境变量时，服务器会启动但等待配置。这是正常行为，MCP 客户端会自动提供这些配置。

### API 参考

#### 工具：`parse_yapi_documentation`

**功能**：解析 YApi 接口文档，提取接口路径、入参和出参信息。

**参数**：

| 参数名 | 类型 | 必需 | 说明 |
|--------|------|------|------|
| `url` | string | ✅ 是 | YApi 接口文档的 URL |

**URL 格式**：
- 完整 URL：`http://yapi.example.com:30000/project/739/interface/api/128185`
- 相对路径：`/project/739/interface/api/128185`（推荐）

**返回格式**：

```json
{
  "title": "导出方案",
  "path": "/app/example.do",
  "method": "POST",
  "description": "",
  "status": "done",
  "project_id": 739,
  "catid": 7882,
  "responseType": "json",
  "requestHeaders": [
    {
      "name": "Content-Type",
      "value": "application/json",
      "required": true,
      "description": ""
    }
  ],
  "requestParams": [
    {
      "name": "body",
      "type": "object",
      "required": true,
      "description": "请求体",
      "location": "body",
      "schema": {
        "type": "object",
        "properties": {
          "startDate": { "type": "string" },
          "endDate": { "type": "string" }
        }
      }
    }
  ],
  "responseParams": {
    "description": "",
    "schema": {
      "type": "object",
      "properties": {
        "code": { "type": "string" },
        "data": { "type": "string" },
        "success": { "type": "boolean" },
        "message": { "type": "string" }
      }
    }
  }
}
```

## 📁 项目结构

```
mcp-yapi/
├── src/
│   ├── index.js          # MCP 服务器主入口（使用 Server API）
│   ├── yapi-client.js    # YApi 客户端封装（处理登录和接口获取）
│   └── parser.js         # 接口文档解析器（解析入参和出参）
├── package.json          # 项目配置和依赖
├── README.md            # 项目文档
├── CHANGELOG.md         # 更新日志
├── LICENSE              # MIT 许可证
├── mcp.json.example     # MCP 配置示例
└── test-with-env.sh     # 测试脚本
```

## 🛠️ 技术栈

- **Node.js** (>= 18.0.0) - 运行环境
- **@modelcontextprotocol/sdk** (^1.0.4) - MCP SDK，使用 Server API
- **node-fetch** (^3.3.2) - HTTP 请求库

### 核心实现

- 使用 `Server` 类和 Schema 对象（`ListToolsRequestSchema`, `CallToolRequestSchema`）
- 通过 `StdioServerTransport` 与 MCP 客户端通信
- LDAP 登录认证（`/api/user/login_by_ldap`）
- 接口详情获取（`/api/interface/get`）

## ⚠️ 注意事项

1. **网络访问**：确保能够访问 YApi 服务器
   - 内网地址需要 VPN 或内网环境
   - 检查防火墙设置

2. **登录凭证**：确保提供有效的账号密码
   - 使用 LDAP 登录方式
   - 密码错误会导致认证失败

3. **URL 格式**：接口 URL 必须符合格式
   - 格式：`/project/{projectId}/interface/api/{interfaceId}`
   - 示例：`/project/739/interface/api/128185`

4. **MCP 配置**：修改配置后需要重启 Cursor
   - macOS/Linux: `~/.cursor/mcp.json`
   - Windows: `%USERPROFILE%\.cursor\mcp.json`

## 🐛 故障排除

### 问题 1：MCP 服务器无法启动

**症状**：配置后没有反应或报错

**解决方案**：
1. 检查 `mcp.json` 格式是否正确（JSON 语法）
2. 确认 Node.js 版本 >= 18.0.0
3. 重启 Cursor
4. 查看 Cursor 的日志输出

### 问题 2：登录失败

**症状**：提示登录错误或认证失败

**解决方案**：
1. 检查 `YAPI_EMAIL` 和 `YAPI_PASSWORD` 是否正确
2. 确认 YApi 服务器地址可访问
3. 验证账号是否有访问权限

### 问题 3：无法获取接口详情

**症状**：提示接口不存在或无权限访问

**解决方案**：
1. 检查接口 URL 格式是否正确
2. 确认该接口在 YApi 中存在
3. 验证账号是否有该项目的访问权限

### 问题 4：npx 安装慢或失败

**症状**：首次使用时安装超时

**解决方案**：
1. 配置 npm 镜像：`npm config set registry https://registry.npmmirror.com`
2. 或使用全局安装：`npm install -g @liguangdong/mcp-yapi`
3. 然后修改配置使用全局命令：
   ```json
   {
     "command": "mcp-yapi",
     "args": []
   }
   ```

### 问题 5：Schema 相关错误

**症状**：`Cannot read properties of undefined (reading 'method')`

**解决方案**：
- 这是旧版本的问题，已在最新版本修复
- 更新到最新版本：确保使用 `@latest`
- 或手动安装：`npm install -g @liguangdong/mcp-yapi@latest`

## 🔄 开发

### 本地开发

```bash
# 克隆项目
git clone https://github.com/yourusername/mcp-yapi.git
cd mcp-yapi

# 安装依赖
npm install

# 运行测试
npm test

# 启动服务器（需要环境变量）
export YAPI_EMAIL="your_email"
export YAPI_PASSWORD="your_password"
npm start
```

### 发布新版本

```bash
# 更新版本号
npm version patch  # 或 minor, major

# 发布到 npm
npm publish
```

## 📝 更新日志

查看 [CHANGELOG.md](./CHANGELOG.md) 了解版本更新历史。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

[MIT License](./LICENSE)

## 🔗 相关链接

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [YApi 官方文档](https://hellosean1025.github.io/yapi/)
- [Cursor 编辑器](https://cursor.sh/)

---

**提示**：如果觉得这个项目有帮助，欢迎 Star ⭐！