YApi MCP Server

一个基于 Model Context Protocol (MCP) 的智能工具服务器，连接 YApi 和 LLM，自动化生成 TypeScript 接口定义。

✨ 功能特性

• 🔄 自动同步：从 YApi 自动获取 API 定义并生成 TypeScript 接口
• 🎯 双模式工具：
  • generate_ts_from_yapi: 生成完整的 TypeScript 代码
  • get_yapi_context: 获取接口上下文信息
• 🔐 安全认证：支持 YApi 用户名/密码登录
• 📦 开箱即用：通过 npm 全局安装，无需额外配置
• 🚀 高性能：基于 Bun 构建，快速响应

💡 解决的问题

在现代开发流程中，保持前端 TypeScript 接口与后端 YApi 定义的严格同步是一项繁琐且容易出错的任务。本项目通过智能自动化工作流解决这一痛点：

• ❌ 手动维护 TypeScript 类型定义费时费力
• ❌ API 变更后容易遗漏类型更新
• ❌ 枚举值和字段描述难以保持一致

✅ 一键生成 TypeScript 接口和枚举
✅ 自动添加 JSDoc 注释
✅ 智能识别 枚举类型

🛠️ 工作原理

graph LR
    A[MCP Client] -->|调用工具| B[YApi MCP Server]
    B -->|登录认证| C[YApi]
    C -->|返回API定义| B
    B -->|生成提示| D[LLM]
    D -->|生成代码| E[TypeScript 接口]

1. MCP 客户端：在 Chat 中通过 MCP 调用工具
2. 数据获取：使用凭证登录 YApi 并获取 API 定义
3. 提示生成：为 LLM 构建精确的提示词
4. 代码生成：LLM 根据定义生成 TypeScript 代码
5. 结果返回：以建议或面板形式呈现

📦 安装

方式一：npm 全局安装（推荐）

npm install @lstmxx/yapi-mcp-server -g

方式二：从源码构建

# 克隆仓库
git clone [email protected]:Lstmxx/yapi-mcp-server.git
cd yapi-mcp-server

# 安装依赖
bun install

# 构建
bun run build

⚙️ 配置

在 MCP 客户端的配置文件中添加以下内容（例如 Claude Desktop 的 claude_desktop_config.json 或 Cline 的 cline_mcp_settings.json）：

npm 安装方式

{
  "mcpServers": {
    "yapi-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["@lstmxx/yapi-mcp-server"],
      "disabled": false,
      "timeout": 60,
      "env": {
        "USERNAME": "your-yapi-username",
        "PASSWORD": "your-yapi-password",
        "DOMAIN": "http://your-yapi-domain.com"
      }
    }
  }
}

本地构建方式

{
  "mcpServers": {
    "yapi-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/yapi-mcp-server/dist/index.js"],
      "disabled": false,
      "timeout": 60,
      "env": {
        "USERNAME": "your-yapi-username",
        "PASSWORD": "your-yapi-password",
        "DOMAIN": "http://your-yapi-domain.com"
      }
    }
  }
}

📚 可用工具

1. generate_ts_from_yapi

生成完整的 TypeScript 接口和枚举代码。

使用场景：需要为 API 创建类型定义时

输入：YApi 接口 URL

输出：

• TypeScript 请求接口（XxxReq）
• TypeScript 响应接口（XxxRes）
• 相关枚举类型
• 完整的 JSDoc 注释

示例：

请使用 YApi 接口 http://yapi.example.com/project/123/interface/api/456 生成 TypeScript 代码

2. get_yapi_context

获取 YApi 接口的详细信息作为上下文。

使用场景：需要了解 API 定义但不生成代码时

输入：YApi 接口 URL

输出：

• 接口路径和方法
• 请求体结构
• 响应体结构

示例：

请获取 http://yapi.example.com/project/123/interface/api/456 的接口信息

🎯 使用示例

示例 1：生成登录接口类型

输入：

使用 http://yapi.example.com/project/1/interface/api/100 生成 TypeScript

YApi 定义：

{
  "path": "/api/user/login",
  "method": "POST",
  "req_body_other": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "description": "用户名" },
      "password": { "type": "string", "description": "密码" }
    }
  },
  "res_body": {
    "type": "object",
    "properties": {
      "code": { "type": "number", "description": "状态码：0-成功；1-失败" },
      "data": {
        "type": "object",
        "properties": {
          "token": { "type": "string", "description": "认证令牌" }
        }
      }
    }
  }
}

生成结果：

/** 状态码枚举 */
enum CodeEnum {
  成功 = 0,
  失败 = 1
}

/** 登录请求 */
interface ApiUserLoginReq {
  /** 用户名 */
  username: string;
  /** 密码 */
  password: string;
}

/** 登录响应 */
interface ApiUserLoginRes {
  /** 状态码：0-成功；1-失败 */
  code: CodeEnum;
  data: {
    /** 认证令牌 */
    token: string;
  };
}

示例 2：获取接口上下文

输入：

获取 http://yapi.example.com/project/1/interface/api/100 的接口信息

输出：

YApi接口信息：

**接口标识**
- 类型名：ApiUserLogin
- 路径：/api/user/login
- 方法：POST

**请求体** (json)
{
  "type": "object",
  "properties": {...}
}

**响应体** (json)
{
  "type": "object",
  "properties": {...}
}

🏗️ 项目结构

src/
├── core/          # HTTP 客户端
├── types/         # TypeScript 类型定义
├── utils/         # 工具函数
├── prompts/       # 提示模板
├── services/      # 业务服务层
├── tools/         # MCP 工具定义
└── index.ts       # 主入口

🚀 版本发布

本项目使用自动化工具管理版本和 changelog。

Commit 规范

提交代码时请遵循 Conventional Commits 规范：

# 新功能 (minor 版本 +1)
git commit -m "feat: 添加新的 API 支持"

# Bug 修复 (patch 版本 +1)
git commit -m "fix: 修复登录认证问题"

# 破坏性变更 (major 版本 +1)
git commit -m "feat!: 重构核心 API
BREAKING CHANGE: 修改了工具参数结构"

# 其他类型 (不影响版本号)
git commit -m "docs: 更新 README"
git commit -m "chore: 更新依赖"

发布新版本

# 自动分析提交历史并确定版本号
bun run release

# 或手动指定版本类型
bun run release:patch   # 1.1.0 -> 1.1.1
bun run release:minor   # 1.1.0 -> 1.2.0
bun run release:major   # 1.1.0 -> 2.0.0

# 推送代码和标签
git push --follow-tags

# 发布到 npm
npm publish

版本发布后会自动：

• ✅ 更新 package.json 版本号
• ✅ 生成/更新 CHANGELOG.md
• ✅ 创建 git commit 和 tag

详细变更记录请查看 CHANGELOG.md。

🤝 贡献

欢迎各种形式的贡献！

• 🐛 提交 Bug 报告
• 💡 提出功能建议
• 🔧 提交 Pull Request
• 📖 改进文档

📄 许可证

本项目基于 MIT 许可证 开源。