Package Exports

@liguangdong/mcp-yapi
@liguangdong/mcp-yapi/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@liguangdong/mcp-yapi) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

YApi MCP 服务器

这是一个 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

最简配置（推荐）：

{
  "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：

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

方式二：全局安装

npm install -g @liguangdong/mcp-yapi

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

# 克隆仓库
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），只需配置账号密码：

{
  "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：

{
  "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️⃣ 本地开发配置

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

{
  "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：使用测试脚本

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

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

# 设置环境变量
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（推荐）

返回格式：

{
  "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）

⚠️ 注意事项

网络访问：确保能够访问 YApi 服务器
- 内网地址需要 VPN 或内网环境
- 检查防火墙设置
登录凭证：确保提供有效的账号密码
- 使用 LDAP 登录方式
- 密码错误会导致认证失败
URL 格式：接口 URL 必须符合格式
- 格式：/project/{projectId}/interface/api/{interfaceId}
- 示例：/project/739/interface/api/128185
MCP 配置：修改配置后需要重启 Cursor
- macOS/Linux: ~/.cursor/mcp.json
- Windows: %USERPROFILE%\.cursor\mcp.json

🐛 故障排除

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

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

解决方案：

检查 mcp.json 格式是否正确（JSON 语法）
确认 Node.js 版本 >= 18.0.0
重启 Cursor
查看 Cursor 的日志输出

问题 2：登录失败

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

解决方案：

检查 YAPI_EMAIL 和 YAPI_PASSWORD 是否正确
确认 YApi 服务器地址可访问
验证账号是否有访问权限

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

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

解决方案：

检查接口 URL 格式是否正确
确认该接口在 YApi 中存在
验证账号是否有该项目的访问权限

问题 4：npx 安装慢或失败

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

解决方案：

配置 npm 镜像：npm config set registry https://registry.npmmirror.com
或使用全局安装：npm install -g @liguangdong/mcp-yapi

然后修改配置使用全局命令：

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

问题 5：Schema 相关错误

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

解决方案：

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

🔄 开发

本地开发

# 克隆项目
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

发布新版本

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

# 发布到 npm
npm publish

📝 更新日志

查看 CHANGELOG.md 了解版本更新历史。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🔗 相关链接

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

@liguangdong/mcp-yapi

Package Exports

Readme

YApi MCP 服务器

✨ 功能特性

🚀 快速开始

第一步：配置 MCP 服务器

第二步：重启 Cursor

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

📦 安装方式

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

方式二：全局安装

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

⚙️ 配置详解

配置参数说明

配置示例

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

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

3️⃣ 本地开发配置

📖 使用方法

在 Cursor AI 中使用

示例 1：解析单个接口

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

示例 3：批量处理接口

手动测试（开发者）

方法 1：使用测试脚本

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

API 参考

工具：parse_yapi_documentation

📁 项目结构

🛠️ 技术栈

核心实现

⚠️ 注意事项

🐛 故障排除

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

问题 2：登录失败

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

问题 4：npx 安装慢或失败

问题 5：Schema 相关错误

🔄 开发

本地开发

发布新版本

📝 更新日志

🤝 贡献

📄 许可证

🔗 相关链接

工具：`parse_yapi_documentation`