YApi MCP Server

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

功能特性

• 🔐 支持用户名密码和 token 两种认证方式
• 📝 支持创建、更新、获取接口文档
• 📋 支持获取分类下的接口列表，自动生成详情链接
• 🔄 自动管理认证状态
• 🌐 支持 HTTP 和 stdio 两种运行模式
• 📊 完整的 TypeScript 类型支持
• 🔇 智能日志管理，MCP模式下自动禁用日志输出，避免协议干扰

可用工具

get_api_desc

获取YApi中特定接口的详细信息

• 参数: apiId - YApi接口的ID
• 返回: 接口的完整详情信息，包括请求参数、响应结构等

get_api_list

获取YApi中特定分类下的接口列表，返回接口详情链接

• 参数:
  • yapiUrl - YApi分类页面的URL，格式如：https://yapi.example.com/project/1234/interface/api/cat_10001
  • limit - 可选，获取的接口数量限制，默认200
  • page - 可选，页码，默认第1页
• 返回:
  • 摘要信息（总数、分页等）
  • 快速访问的详情链接列表
  • 每个接口的详细信息和详情页面链接

create_api

创建新的API接口

• 参数: 接口名称、路径、请求方法、项目ID、分类ID等
• 返回: 创建成功的接口信息

update_api

更新已有的API接口

• 参数: 接口ID和需要更新的字段
• 返回: 更新后的接口信息

快速使用

使用用户名和密码

{
  "mcpServers": {
    "yapi-devloper-mcp": {
      "command": "npx",
      "args": ["-y", "yapi-devloper-mcp@latest", "--stdio"],
      "env": {
        "YAPI_BASE_URL": "https://yapi.example.com",
        "YAPI_USERNAME": "your-username", 
        "YAPI_PASSWORD": "your-password"
      }
    }
  }
}

使用token的方式

{
  "mcpServers": {
    "yapi-devloper-mcp": {
      "command": "npx",
      "args": ["-y", "yapi-devloper-mcp@latest", "--stdio"],
      "env": {
        "YAPI_BASE_URL": "https://yapi.example.com",
        "YAPI_TOKEN": "your-token"
      }
    }
  }
}

使用示例

获取接口列表

使用 get_api_list 工具获取特定分类下的所有接口：

{
  "tool": "get_api_list",
  "yapiUrl": "https://yapi.example.com/project/1234/interface/api/cat_10001",
  "limit": 100,
  "page": 1
}

返回结果示例：

{
  "摘要信息": {
    "总接口数量": 7,
    "当前页接口": 7,
    "分页信息": {
      "当前页": 1,
      "每页数量": 100,
      "总页数": 1
    }
  },
  "快速访问": {
    "详情链接列表": [
      "https://yapi.example.com/project/1234/interface/api/12001",
      "https://yapi.example.com/project/1234/interface/api/12002",
      "https://yapi.example.com/project/1234/interface/api/12003"
    ],
    "使用说明": "点击上面任意链接可直接访问接口详情页面"
  },
  "详细接口信息": [
    {
      "接口基本信息": {
        "ID": 12001,
        "名称": "示例接口",
        "方法": "GET",
        "路径": "/api/demo",
        "状态": "undone"
      },
      "YApi详情页面": "https://yapi.example.com/project/1234/interface/api/12001",
      "接口详情链接": "https://yapi.example.com/project/1234/interface/api/12001"
    }
  ]
}

获取接口详情

使用 get_api_desc 工具获取特定接口的详细信息：

{
  "tool": "get_api_desc",
  "apiId": "12001"
}

最佳实践

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

YApi 接口开发规范

规则说明

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

规则定义

POST 接口模板

{
  "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 接口模板

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

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

PUT 接口模板

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