npm package: @lstmxx/yapi-mcp-server
Description: 一个用 LLM 将 Yapi 的 API 定义自动化生成为 TypeScript 代码的MCP服务
Author: Lstmxx
Latest version: 1.1.0

# YApi MCP Server

[![MCP Status](https://img.shields.io/badge/MCP-Compatible-brightgreen)](https://modelcontext.protocol.ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/@lstmxx/yapi-mcp-server.svg)](https://www.npmjs.com/package/@lstmxx/yapi-mcp-server)

一个基于 [Model Context Protocol (MCP)](https://modelcontext.protocol.ai/) 的智能工具服务器，连接 YApi 和 LLM，自动化生成 TypeScript 接口定义。

## ✨ 功能特性

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

## 💡 解决的问题

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

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

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

## 🛠️ 工作原理

```mermaid
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 全局安装（推荐）

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

### 方式二：从源码构建

```bash
# 克隆仓库
git clone git@github.com: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 安装方式

```json
{
  "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"
      }
    }
  }
}
```

### 本地构建方式

```json
{
  "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 注释

**示例**：

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

### 2. `get_yapi_context`

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

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

**输入**：YApi 接口 URL

**输出**：

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

**示例**：

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

## 🎯 使用示例

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

**输入**：

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

**YApi 定义**：

```json
{
  "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": "认证令牌" }
        }
      }
    }
  }
}
```

**生成结果**：

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

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

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

### 示例 2：获取接口上下文

**输入**：

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

**输出**：

```text
YApi接口信息：

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

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

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

## 🏗️ 项目结构

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

## 🚀 版本发布

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

### Commit 规范

提交代码时请遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```bash
# 新功能 (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: 更新依赖"
```

### 发布新版本

```bash
# 自动分析提交历史并确定版本号
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](./CHANGELOG.md)。

## 🤝 贡献

欢迎各种形式的贡献！

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

## 📄 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。