YApi MCP

Yapi-Mcp

从粘贴的 YApi 项目地址拉取接口文档（JSON 请求 / JSON 响应），供编码 Agent 自动理解并对接客户端项目的 MCP Server。

English

功能

• 解析 YApi 页面 URL → base_url / project_id / interface_id
• 列出 / 搜索接口，导出目录
• 拉取归一化后的请求与响应 JSON（JSON Schema / 示例）
• 鉴权：登录 JWT（Cookie _yapi_token + _yapi_uid）或项目 open token
• 动态凭证：环境变量、.env、.yapi-mcp.json、运行时 yapi_configure、或工具参数

快速接入

Cursor / Claude Desktop MCP

{
  "mcpServers": {
    "yapi": {
      "command": "uvx",
      "args": ["--from", "contextdong-yapi-mcp", "yapi-mcp"],
      "env": {
        "YAPI_BASE_URL": "https://yapi.example.com",
        "YAPI_TOKEN": "YOUR_LOGIN_JWT_OR_PROJECT_OPEN_TOKEN"
      }
    }
  }
}

从 Git 安装（不经 PyPI）：

{
  "mcpServers": {
    "yapi": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ContextDong/Yapi-Mcp",
        "yapi-mcp"
      ],
      "env": {
        "YAPI_BASE_URL": "https://yapi.example.com",
        "YAPI_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

或使用 pip：

pip install contextdong-yapi-mcp
# 或: pip install git+https://github.com/ContextDong/Yapi-Mcp

配置凭证（仓库内不存放密钥）

优先级从高到低：

1. 工具参数（token、base_url）
2. 运行时 yapi_configure（仅当前 MCP 进程内存）
3. 环境变量 / .env（YAPI_BASE_URL、YAPI_TOKEN、YAPI_UID、YAPI_COOKIE）
4. 配置文件 .yapi-mcp.json，或 YAPI_MCP_CONFIG 指向的路径

示例：

cp .env.example .env
cp .yapi-mcp.example.json .yapi-mcp.json

变量	说明
YAPI_BASE_URL	YApi 主机，如 https://yapi.example.com
YAPI_TOKEN	登录 JWT 或 项目 open token
YAPI_UID	可选；登录 JWT 一般会自动解析 uid
YAPI_COOKIE	可选；原始 Cookie 头覆盖
YAPI_MCP_CONFIG	可选；JSON 配置文件路径

切勿提交 .env、.yapi-mcp.json 或真实 token。

工具列表

工具	用途
yapi_configure / yapi_get_config	动态配置 / 查看非敏感配置
yapi_parse_url	从页面 URL 解析主机与 id
yapi_get_project	项目元信息
yapi_list_interfaces	可搜索的接口索引
yapi_get_interface	单个接口完整 JSON 定义（便于写客户端）
yapi_export_catalog	导出目录（可选详情）

Agent 用法

在对话中粘贴项目地址：

根据 https://yapi.example.com/project/123/interface/api/ 对接登录相关接口

Agent 应先配置凭证（如需要），再列表 / 拉详情，最后按目标工程现有风格实现客户端。

可选 Skill：.cursor/skills/yapi-api-client/SKILL.md

本地开发

python -m pip install -e ".[dev]"
python -m pytest
python -m yapi_mcp.server

MCP Registry

• 官方名：io.github.ContextDong/yapi-mcp
• PyPI 包：contextdong-yapi-mcp（uvx / 命令 yapi-mcp）
• 说明：短名 yapi-mcp 在 PyPI 上已被其他项目占用

License

MIT