MCP 服务器

yapi-mcp

A Model Context Protocol server for YApi that enables developers to search, view, create, and update API definitions directly from MCP-compatible IDEs.

README

YApi MCP Server

基于 YApi 1.12.0 接口管理平台的 Model Context Protocol (MCP) 服务器。

使开发者能够在支持 MCP 的 IDE 和编辑器(Claude Code、Cursor 等)中直接搜索、查看、创建和更新 YApi 接口定义,无需离开开发环境。

功能特性

🔍 搜索接口: 通过标题、路径或描述查找 API 端点
📖 查看定义: 获取完整的接口规范,包括请求/响应结构
➕ 创建接口: 向 YApi 项目添加新的 API 定义
✏️ 更新接口: 增量更新现有接口配置(先读后写,仅修改传入字段)
🔐 Cookie 认证: 基于会话的安全认证
⚡ 异步性能: 基于 httpx 实现高效的并发操作
🛡️ 启动验证: 服务启动时自动校验 Cookie 有效性,失效时立即报错退出
📝 Markdown 支持: 接口描述支持 Markdown 格式,自动转换为 HTML

MCP 工具

`yapi_search_interfaces` — 搜索接口

在指定项目中通过关键词搜索接口(匹配标题/路径/描述)。

参数	类型	必需	说明
`project_id`	int	✅	YApi 项目 ID
`keyword`	str	✅	搜索关键词

返回: 接口摘要数组 JSON(_id, title, path, method)

`yapi_get_interface` — 获取接口详情

获取单个接口的完整定义,包括请求/响应结构、描述等。

参数	类型	必需	说明
`interface_id`	int	✅	接口 ID

返回: 完整接口对象 JSON

`yapi_create_interface` — 创建接口

在 YApi 项目中创建新接口。

参数	类型	必需	说明
`project_id`	int	✅	项目 ID
`catid`	int	✅	分类 ID
`title`	str	✅	接口标题
`path`	str	✅	接口路径(以 `/` 开头)
`method`	str	✅	HTTP 方法(GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS)
`req_body`	str	—	请求体(JSON Schema 字符串)
`req_body_type`	str	—	请求体类型(`form`/`json`/`raw`/`file`)
`req_body_is_json_schema`	bool	—	请求体是否为 JSON Schema 格式
`req_body_form`	str	—	表单字段(JSON 数组),示例: `[{"name":"x","type":"text","required":"1","desc":"说明"}]`
`req_query`	str	—	Query 参数(JSON 数组),示例: `[{"name":"page","required":"1","desc":"页码"}]`
`req_headers`	str	—	请求头(JSON 数组),示例: `[{"name":"Authorization","value":"Bearer token","required":"1"}]`
`req_params`	str	—	路径参数(JSON 数组),示例: `[{"name":"id","example":"123","desc":"用户ID"}]`
`res_body`	str	—	响应体(JSON Schema 字符串)
`res_body_type`	str	—	响应体类型(`json`/`raw`)
`res_body_is_json_schema`	bool	—	响应体是否为 JSON Schema 格式
`markdown`	str	—	接口描述(Markdown 格式,自动转 HTML)
`status`	str	—	接口状态(`undone`/`done`)
`tag`	str	—	标签(JSON 数组)
`api_opened`	bool	—	是否公开 API

返回: {"action": "created", "interface_id": <id>}

`yapi_update_interface` — 更新接口

增量更新接口定义。仅需传入要修改的字段,其余字段自动保留原值(先读后写)。

参数	类型	必需	说明
`interface_id`	int	✅	接口 ID
`title`	str	—	新标题
`path`	str	—	新路径(以 `/` 开头)
`method`	str	—	新 HTTP 方法
`catid`	int	—	新分类 ID
`req_body`	str	—	请求体(JSON Schema)
`req_body_type`	str	—	请求体类型
`req_body_is_json_schema`	bool	—	请求体是否为 JSON Schema 格式
`req_body_form`	str	—	表单字段(JSON 数组),示例: `[{"name":"x","type":"text","required":"1","desc":"说明"}]`
`req_query`	str	—	Query 参数(JSON 数组),示例: `[{"name":"page","required":"1","desc":"页码"}]`
`req_headers`	str	—	请求头(JSON 数组),示例: `[{"name":"Authorization","value":"Bearer token","required":"1"}]`
`req_params`	str	—	路径参数(JSON 数组),示例: `[{"name":"id","example":"123","desc":"用户ID"}]`
`res_body`	str	—	响应体(JSON Schema)
`res_body_type`	str	—	响应体类型
`res_body_is_json_schema`	bool	—	响应体是否为 JSON Schema 格式
`markdown`	str	—	接口描述(Markdown 格式)
`status`	str	—	接口状态
`tag`	str	—	标签(JSON 数组)
`api_opened`	bool	—	是否公开 API
`switch_notice`	bool	—	是否通知团队成员
`message`	str	—	变更说明

返回: {"action": "updated", "interface_id": <id>}

环境要求

Python 3.11 或更高版本
YApi 1.12.0 实例(可通过 HTTP/HTTPS 访问)
有效的 YApi 认证 cookies

配置

1. 获取 YApi Cookies

在浏览器中登录 YApi 实例
打开开发者工具(F12)
导航到 Application → Cookies(Chrome) 或 Storage → Cookies(Firefox)
复制以下 cookie 值:
- _yapi_token (必需)
- _yapi_uid (必需)
- ZYBIPSCAS (可选，仅某些自定义部署需要)

2. 配置 MCP

推荐直接在 MCP 配置的 env 中传入所需环境变量:

{
  "mcpServers": {
    "yapi": {
      "command": "uvx",
      "args": ["yapi-mcp"],
      "env": {
        "YAPI_SERVER_URL": "https://your-yapi-instance.com",
        "YAPI_TOKEN": "your_token",
        "YAPI_UID": "your_uid"
      }
    }
  }
}

注意: 如果你的 YApi 部署需要额外的 CAS 认证，添加 "YAPI_CAS": "your_cas_value" 到 env 中。

如果你希望从文件加载配置，可以先参考 .env.example 创建一个专用 .env 文件，然后显式设置 YAPI_ENV_FILE:

{
  "mcpServers": {
    "yapi": {
      "command": "uvx",
      "args": ["yapi-mcp"],
      "env": {
        "YAPI_ENV_FILE": "/absolute/path/to/yapi.env"
      }
    }
  }
}

未配置 YAPI_ENV_FILE 时，程序不会自动读取当前目录下的 .env。
.env.example 只是模板文件，不会被自动加载。
YAPI_ENV_FILE 必须由外部环境传入；不要把它写在目标 .env 文件里指望自举生效。

开发

运行测试

# 安装开发依赖
pip install -e ".[dev]"

# 运行所有测试
pytest

# 运行并显示覆盖率
pytest --cov=src --cov-report=term-missing

# 运行特定测试文件
pytest tests/test_config.py

代码质量

# 格式化代码
ruff format

# 代码检查
ruff check

# 自动修复检查问题
ruff check --fix

项目结构

yapi-mcp/
├── src/
│   └── yapi_mcp/          # Python 包
│       ├── server.py      # MCP 服务器入口 + 工具定义
│       ├── config.py      # 配置模型
│       └── yapi/
│           ├── client.py  # YApi API 客户端
│           ├── models.py  # Pydantic 数据模型
│           └── errors.py  # 错误映射
├── tests/                 # 测试套件
├── pyproject.toml         # 项目配置
├── .env.example           # 环境变量模板
└── README.md              # 本文件