@zhangzhao1102/yapi-mcp-server/README.md

YApi MCP Server - 用于与YApi接口管理平台交互的MCP服务器

# YApi MCP Server

这是一个用于与 YApi 接口管理平台交互的 MCP (Model Context Protocol) 服务器。

## 功能特性

- 🔍 **项目管理** - 获取项目列表和详细信息
- 📋 **接口管理** - 查看、创建、更新和删除接口
- 📁 **分类管理** - 管理接口分类
- 🧪 **接口测试** - 运行接口测试并获取结果
- 🔐 **身份验证** - 支持 YApi Token 或者 账号密码 认证

## 安装

1. 进入项目目录
```bash
cd yapi-mcp-server
```

2. 安装依赖
```bash
npm install
```

3. 配置环境变量
```bash
# 复制环境变量示例文件
cp env.example .env

# 编辑 .env 文件，设置您的 YApi 服务器地址和令牌
```

## 配置

### 环境变量

- `YAPI_BASE_URL`: YApi 服务器地址 (默认: https://yapi.test.com)
- `YAPI_USERMAE`: YApi 访问令牌 (可选，用于需要认证的操作)
- `YAPI_PASSWORD`: YApi 访问令牌 (可选，用于需要认证的操作)

### MCP 客户端配置

在您的 MCP 客户端配置文件中添加以下配置：

```json
{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": [
        "-y",
        "@zhangzhao1102/yapi-mcp-server",
        "--stdio"
      ],
      "env": {
        "YAPI_BASE_URL": "https://your-yapi-server.com",
        "YAPI_USERNAME": "your_username_here",
        "YAPI_PASSWORD": "your_password_here"
      }
    }
  }
}
```

## 使用方法

启动服务器：
```bash
npm start
```

开发模式（自动重启）：
```bash
npm run dev
```

## 可用工具

### 项目相关

#### `get_project_list`
获取 YApi 项目列表

参数：
- `group_id` (可选): 项目分组 ID
- `page` (可选): 页码，默认为 1
- `limit` (可选): 每页数量，默认为 10

#### `get_project_info`
获取指定项目详细信息

参数：
- `project_id` (必需): 项目 ID

### 接口相关

#### `get_interface_list`
获取项目接口列表

参数：
- `project_id` (必需): 项目 ID
- `catid` (可选): 接口分类 ID
- `page` (可选): 页码，默认为 1
- `limit` (可选): 每页数量，默认为 20

#### `get_interface_detail`
获取接口详细信息

参数：
- `interface_id` (必需): 接口 ID

#### `create_interface`
创建新的接口

参数：
- `project_id` (必需): 项目 ID
- `catid` (必需): 接口分类 ID
- `title` (必需): 接口标题
- `path` (必需): 接口路径
- `method` (必需): 请求方法 (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
- `desc` (可选): 接口描述
- `req_body_type` (可选): 请求体类型 (form, json, file, raw)
- `status` (可选): 接口状态 (undone, done)

#### `update_interface`
更新接口信息

参数：
- `interface_id` (必需): 接口 ID
- `title` (可选): 接口标题
- `path` (可选): 接口路径
- `method` (可选): 请求方法
- `desc` (可选): 接口描述
- `status` (可选): 接口状态

#### `delete_interface`
删除接口

参数：
- `interface_id` (必需): 接口 ID

#### `run_interface_test`
运行接口测试

参数：
- `interface_id` (必需): 接口 ID
- `env` (可选): 测试环境
- `params` (可选): 测试参数

### 分类相关

#### `get_interface_categories`
获取项目接口分类

参数：
- `project_id` (必需): 项目 ID

#### `create_interface_category`
创建接口分类

参数：
- `project_id` (必需): 项目 ID
- `name` (必需): 分类名称
- `desc` (可选): 分类描述

## 示例用法

### 获取项目列表
```javascript
// 通过 MCP 客户端调用
await callTool('get_project_list', { 
  page: 1, 
  limit: 10 
});
```

### 创建接口
```javascript
// 通过 MCP 客户端调用
await callTool('create_interface', {
  project_id: '2081',
  catid: '20593',
  title: '用户登录接口',
  path: '/api/user/login',
  method: 'POST',
  desc: '用户登录验证接口',
  req_body_type: 'json',
  status: 'undone'
});
```

### 获取接口详情
```javascript
// 通过 MCP 客户端调用
await callTool('get_interface_detail', {
  interface_id: '12345'
});
```

## 错误处理

服务器会自动处理以下错误：
- 网络连接错误
- YApi API 错误
- 参数验证错误
- 权限验证错误

所有错误都会以友好的中文消息返回给客户端。

## 注意事项

1. 某些操作需要 YApi Token 认证
2. 确保您的 YApi 服务器地址正确且可访问
3. 接口 ID 和项目 ID 需要准确，错误的 ID 会导致操作失败

### 依赖项

- `@modelcontextprotocol/sdk`: MCP SDK
- `axios`: HTTP 客户端
- `node-fetch`: Fetch API 实现