yapi-devloper-mcp/README.md

YApi MCP Integration

# YApi MCP Server

YApi MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，用于与 YApi 平台进行集成。它允许你通过 MCP 工具直接管理和操作 YApi 中的接口文档。

## 功能特性

- 🔐 支持用户名密码和 token 两种认证方式
- 📝 支持创建、更新、获取接口文档
- 🔄 自动管理认证状态
- 🌐 支持 HTTP 和 stdio 两种运行模式
- 📊 完整的 TypeScript 类型支持

## 快速使用

### 使用用户名和密码
```
{
  "mcpServers": {
    "yapi-devloper-mcp": {
      "command": "npx",
      "args": ["-y", "yapi-devloper-mcp", "--stdio"],
      "env": {
        "YAPI_BASE_URL": "<your-yapi-url>",
        "YAPI_USERNAME": "<your-username>", 
        "YAPI_PASSWORD": "<your-password>"
      }
    }
  }
}
```

### 使用token的方式

```
{
  "mcpServers": {
    "yapi-devloper-mcp": {
      "command": "npx",
      "args": ["-y", "yapi-devloper-mcp", "--stdio"],
      "env": {
        "YAPI_BASE_URL": "<your-yapi-url>",
        "YAPI_TOKEN": "<your-token>"
      }
    }
  }
}
```

# 最佳实践

创建接口，有时传参会有问题，建议将下面的规则，复制到cursor的rules中。
# YApi 接口开发规范

## 规则说明
本规则文件用于指导 YApi 接口的开发和维护工作。

## 规则定义

### POST 接口模板
```typescript
{
  "title": "接口名称",
  "path": "/api/v1/your-path",
  "method": "POST",
  "req_headers": [
    {
      "name": "Content-Type",
      "value": "application/json"
    }
  ],
  "req_body_type": "json",
  "req_body_is_json_schema": true,
  "req_body_other": {
    "type": "object",
    "properties": {
      // 在此定义请求参数
    },
    "required": []
  }
}
```

### GET 接口模板
```typescript
{
  "title": "接口名称",
  "path": "/api/v1/your-path",
  "method": "GET",
  "req_query": [
    {
      "name": "参数名",
      "desc": "参数描述",
      "required": "1"
    }
  ]
}
```
```typescript
{
  "title": "接口名称",
  "path": "/api/v1/your-path",
  "method": "GET",
  "req_query": [
    {
      "name": "参数名",
      "desc": "参数描述",
      "required": "1"
    }
  ]
}
```

### PUT 接口模板
```typescript
{
  "title": "接口名称",
  "path": "/api/v1/your-path/{id}",
  "method": "PUT",
  "req_headers": [
    {
      "name": "Content-Type",
      "value": "application/json"
    }
  ],
  "req_params": [
    {
      "name": "id",
      "desc": "资源ID",
      "required": "1"
    }
  ],
  "req_body_type": "json",
  "req_body_is_json_schema": true,
  "req_body_other": {
    "type": "object",
    "properties": {
      // 在此定义请求参数
    },
    "required": []
  },
  "res_body_type": "json",
  "res_body_is_json_schema": true,
  "res_body": {
    "type": "object",
    "properties": {
      "stat": {
        "type": "number",
        "description": "状态码，0表示成功"
      },
      "msg": {
        "type": "string",
        "description": "返回信息"
      }
    },
    "required": ["stat", "msg"]
  }
}
```

## 检查清单
- 接口路径必须使用小写字母和连字符
- 遵循 RESTful 风格
- Content-Type 必须正确设置
- 所有参数必须有描述
- 必填字段必须在 required 数组中
- 带默认值的字段必须使用 default 属性

## 最佳实践
- 使用清晰的接口描述
- 使用具体的参数描述
- 枚举值必须列出所有可能的值
- 接口变更必须遵循版本控制规范

## 常见问题
- 文件上传接口使用 multipart/form-data
- 数组参数使用 items 描述元素结构
- 嵌套对象使用嵌套的 properties