@enzo.qian/yapi-mcp

v0.1.6

Published

20 days ago

MCP server for creating YApi interfaces and schema-driven advanced mock scripts

0High
0Medium
0Low

enzo.qian

ZT3000 YApi MCP

一个独立的 YApi MCP 服务，用于读取 YApi 接口定义、创建或更新接口，以及根据 JSON Schema 生成高级 Mock 脚本。

功能能力

写入前校验 projectId 和 catId 是否有效及其归属关系。
查询项目、分类、完整接口详情和分类下的全部分页接口。
按照 HTTP 请求方法和接口路径精确检测冲突。
在不写入数据的情况下预览 YApi 请求体和高级 Mock 脚本。
创建或更新请求参数、JSON 请求 Schema 和 JSON 响应 Schema。
根据枚举、格式、约束和字段名称生成 YApi 1.9.2 Random 高级 Mock 脚本，普通业务字段不会因文档示例而变成固定值。
通过官方高级 Mock 插件保存源码，并从插件数据源回读校验。
写入脚本时自动开启高级 Mock；已有脚本时按 interface_id 整段覆盖，不追加、不合并。
单独更新已有接口的高级 Mock 脚本。
单次顺序处理最多 100 个接口，并逐项返回处理结果。
接口写入成功但 Mock 写入失败时，返回部分成功结果。
支持项目 Token、全局 Token 和 YApi 用户会话认证。

安装和构建

cd yapi-mcp
npm install
npm run build
npm test
npm run smoke

要求使用 Node.js 20 或更高版本。请将 .env.example 中的配置填写到 MCP 客户端的环境变量中。本服务不会主动加载仓库中的 .env 文件，避免凭证被意外读取。

通过 npx 使用

将包发布到公司内部 npm registry 后，每台电脑都可以通过 npx 启动 MCP，YApi 凭证继续保存在各自的 Trae 配置中。

发布前先登录公司 registry，然后执行：

cd yapi-mcp
npm test
npm publish --registry=https://your-npm-registry.example.com

如果公司 registry 需要显式发布 scoped 私有包，增加 --access restricted。每次发布前需要更新 package.json 中的版本号，例如：

npm version patch
npm publish --registry=https://your-npm-registry.example.com

Trae 的 mcp.json 配置：

{
  "mcpServers": {
    "zt3000-yapi": {
      "command": "npx",
      "args": [
        "--yes",
        "--registry=https://your-npm-registry.example.com",
        "@enzo.qian/yapi-mcp@latest"
      ],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi.example.com",
        "YAPI_PROJECT_TOKENS": "123:project-token",
        "YAPI_EMAIL": "your-login-account",
        "YAPI_PASSWORD": "your-login-password"
      }
    }
  }
}

固定版本可以避免某次发布后所有电脑在未验证的情况下自动升级。确认新版本可用后，再统一修改版本号。若已经在用户级 .npmrc 中配置了 @enzo.qian scope 的 registry，args 中可以删除 --registry 参数。

MCP 配置

{
  "mcpServers": {
    "zt3000-yapi": {
      "command": "node",
      "args": ["/absolute/path/to/zt3000fe-optimus/yapi-mcp/dist/index.js"],
      "env": {
        "YAPI_BASE_URL": "http://your-yapi.example.com",
        "YAPI_PROJECT_TOKENS": "123:project-token",
        "YAPI_EMAIL": "your-login-account",
        "YAPI_PASSWORD": "your-login-password"
      }
    }
  }
}

不要在提示词或 MCP 工具参数中传递 Token、邮箱或密码。MCP 进程只从环境变量读取认证信息。

线上部署（Streamable HTTP）

当前服务同时支持本地 stdio 和线上 Streamable HTTP。线上模式适合多台电脑共用一份 MCP 服务：YApi 凭证只配置在服务器，客户端只保存 MCP 地址和访问 Token。

Docker 启动

cd yapi-mcp
docker build -t zt3000-yapi-mcp .
docker run -d --name zt3000-yapi-mcp --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e YAPI_BASE_URL=https://your-yapi.example.com \
  -e YAPI_PROJECT_TOKENS='122:project-token' \
  -e YAPI_EMAIL='your-login-account' \
  -e YAPI_PASSWORD='your-login-password' \
  -e MCP_HTTP_AUTH_TOKEN='replace-with-a-long-random-token' \
  zt3000-yapi-mcp

建议在服务器前面使用 HTTPS 反向代理，将 /mcp 转发到 127.0.0.1:3000/mcp，并在安全组中只开放 443。不要把 YApi Token、密码或 MCP 访问 Token 提交到 Git，也不要直接暴露 HTTP 端口。

客户端配置

支持远程 MCP URL 的客户端配置为：

{
  "mcpServers": {
    "zt3000-yapi": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer replace-with-a-long-random-token"
      }
    }
  }
}

如果客户端只支持 command/args，它不能直接连接远程 URL，需要客户端升级，或者在每台电脑本地运行一个 stdio 网关。线上服务使用内存会话；单机多进程或多副本部署时，需要保持会话粘性，或后续接入共享会话存储。

MCP 工具

`yapi_get_project`

查询项目定位信息，只返回 projectId、projectName、基础路径 basepath、绝对地址 mockBaseUrl、相对前缀 mockPathPrefix 和代理相对地址 mockProxyBaseUrl。mockBaseUrl 的格式为 ${YAPI_BASE_URL}/mock/${projectId}；mockPathPrefix 的格式为 mock/${projectId}/，供只维护相对请求路径的项目使用；mockProxyBaseUrl 的格式为 /mock/${projectId}，供通过本地代理访问 YApi Mock 的项目使用。

`yapi_get_categories`

查询指定 YApi 项目下的接口分类，用于确认 catId 是否属于指定 projectId。分类只保留 catId 和 name，响应同时包含 projectName、basepath、mockBaseUrl、mockPathPrefix、mockProxyBaseUrl 和分类总数。

`yapi_list_interfaces`

查询指定分类下的全部接口，自动处理分页。响应只保留 projectId、catId、projectName、basepath、mockBaseUrl、mockPathPrefix、mockProxyBaseUrl、total，以及每个接口的 apiId、title、method、path；完整定义通过 yapi_get_interface 按需读取。

`yapi_get_interface`

查询单个接口的完整定义，包括请求字段、响应 Schema、mockBaseUrl、mockPathPrefix、mockProxyBaseUrl 和完整 mockUrl。完整地址按 mockBaseUrl + projectBasepath + interface.path 生成，并自动去除重复的项目基础路径。高级 Mock 属于插件数据，不在普通接口详情中。

`yapi_get_advanced_mock`

从 YApi 高级 Mock 插件读取指定接口的启用状态和脚本，数据源与网页“高级 Mock -> 脚本”一致。

真实只读测试

在 .env 中配置 YAPI_BASE_URL、YAPI_PROJECT_TOKENS、YAPI_TEST_PROJECT_ID 和 YAPI_TEST_CAT_ID 后执行：

npm run test:live

测试通过 stdio 启动当前 dist/index.js，真实调用项目、分类、接口列表和接口详情工具，并校验紧凑响应字段、分类归属和接口归属。测试只读取 YApi，不写入接口或高级 Mock，也不会输出 Token。

`yapi_preview_api_with_mock`

校验接口定义、检查冲突并生成高级 Mock 脚本，但不写入 YApi。

`yapi_upsert_api_with_mock`

创建或更新接口，同时生成和保存高级 Mock，最后重新读取接口进行校验。

`yapi_update_advanced_mock`

只更新已有接口的高级 Mock，不修改接口请求和响应定义。

`yapi_batch_upsert_apis_with_mock`

顺序处理多个接口，每个接口独立返回创建、更新、跳过、部分成功或失败结果。

核心写入工具

yapi_upsert_api_with_mock 接收标准化接口定义：

{
  "api": {
    "projectId": "123",
    "catId": "456",
    "title": "获取审核任务列表",
    "path": "/api/audit/tasks",
    "method": "GET",
    "request": {
      "query": [
        {
          "name": "pageNum",
          "type": "integer",
          "description": "当前页码",
          "required": true,
          "example": 1
        }
      ]
    },
    "response": {
      "schema": {
        "type": "object",
        "properties": {
          "code": { "type": "integer", "description": "响应码", "example": 0 },
          "data": {
            "type": "object",
            "properties": {
              "total": { "type": "integer", "minimum": 0, "maximum": 1000 },
              "list": {
                "type": "array",
                "minItems": 1,
                "maxItems": 5,
                "items": {
                  "type": "object",
                  "properties": {
                    "taskId": { "type": "integer", "description": "任务ID" },
                    "reviewerName": { "type": "string", "description": "审核人员姓名" },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "创建时间"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "mock": {
    "enabled": true,
    "customValues": {
      "code": 0
    }
  },
  "conflictPolicy": "update",
  "dryRun": false
}

无人值守批量生成前，建议先调用 yapi_preview_api_with_mock。conflictPolicy 支持以下策略：

error：存在相同请求方法和路径时返回失败。
update：更新匹配的已有接口。
skip：返回已有接口，不执行写入。

Mock 生成规则

字段模拟值按照以下优先级生成：

customValues
> enum
> 根响应字段 code/msg/message/success 的 example 或 default
> format
> 字段名称与 description/title 语义规则
> 字段类型默认规则

example 和 default 主要用于接口文档，不会固定普通业务字段的 Mock 值。只有根响应包装字段 code、msg、message、success 会保留其示例或默认值；确实需要固定其他字段时，必须显式配置 customValues。数组对象会生成 () => ({ ... })，确保每个数组元素都实际返回对象。

生成器会同时分析字段名称、description 和 title，选择语义相符的 Random 方法。例如人员姓名、企业名称、手机号、身份证号、普通业务 ID、结算中心、银行卡号、车牌号、地址、金额、经纬度、时间戳和备注会使用不同规则。字段备注比单纯的类型兜底更有意义，因此创建 Schema 时应尽量填写准确的 description；无法可靠识别语义时才按字段类型生成通用随机值。

当前支持：

对象和嵌套对象。
数组及 minItems、maxItems。
字符串、整数、数字、布尔值和空值。
date-time、date、time、email、uuid、url、ipv4 等格式。
ID、姓名、手机号、企业、金额、地址、时间等常见字段名称及中英文备注语义。
minimum、maximum、minLength 和 maxLength 等约束。
使用字段路径配置固定值，例如 data.list[].status。

生成脚本会检查危险模块、动态代码执行和明显的无限循环。

YApi 1.9.2 高级 Mock 使用页面运行环境提供的 Random，生成结果示例：

mockJson = {
  code: 0,
  msg: 'success',
  data: {
    id: Random.id(),
    name: Random.cname(),
    email: Random.email(),
    avatar: Random.image('200x200')
  }
};

脚本不会引入 mockjs，也不会调用 Mock.mock()。

高级 Mock 适配器

默认适配器遵循官方 yapi-plugin-advanced-mock 协议：

写入：POST /api/plugin/advmock/save
读取：GET /api/plugin/advmock/get?interface_id=...
写入字段：project_id、interface_id、mock_script、enable

高级 Mock 插件接口不属于 YApi 项目 Token 的开放接口白名单，因此默认使用 YAPI_EMAIL 和 YAPI_PASSWORD 建立用户会话。YAPI_PROJECT_TOKENS 仍用于项目、分类和普通接口的读写。这里的 YAPI_EMAIL 是 YApi 登录接口的字段名，内部系统使用账号登录时也把登录账号填入该变量。

内部 YApi 分支修改过插件协议时，可以覆盖以下配置：

YAPI_ADVANCED_MOCK_ENDPOINT=/api/plugin/advmock/save
YAPI_ADVANCED_MOCK_METHOD=POST
YAPI_ADVANCED_MOCK_FIELD=mock_script
YAPI_ADVANCED_MOCK_ID_FIELD=interface_id
YAPI_ADVANCED_MOCK_PROJECT_ID_FIELD=project_id
YAPI_ADVANCED_MOCK_ENABLE_FIELD=enable
YAPI_ADVANCED_MOCK_READ_ENDPOINT=/api/plugin/advmock/get
YAPI_ADVANCED_MOCK_READ_ID_FIELD=interface_id
YAPI_ADVANCED_MOCK_READ_FIELD=mock_script
YAPI_ADVANCED_MOCK_AUTH=session

YAPI_ADVANCED_MOCK_AUTH 可选 session 或 token，官方插件必须使用 session。只有返回状态为 created 或 updated，且 verification.interfaceSaved、verification.mockSaved、verification.mockEnabled 都为 true 时，才能认为完整写入成功。接口已创建但高级 Mock 保存、启用或回读失败时，服务返回 status: "partial"，调用方不得描述为成功。

mock 配置未传时默认生成并写入脚本。显式传入 mock.enabled: false 才会跳过 Mock；只要生成了脚本，保存时就会开启高级 Mock，并直接替换该接口原有脚本。

与前端生成 Skill 的边界

本 MCP 负责 YApi 通信、接口写入和确定性的 Mock 生成。本地前端 service 代码生成仍由 yapi-service-generator Skill 负责，因为该过程需要读取当前仓库上下文、分析代码风格并受控地修改文件。

安装、配置、提示词和完整工作流见 YApi MCP 与 Skill 完整使用说明。

验证命令

# TypeScript 类型检查
npm run check

# 编译并运行全部测试
npm test

# 启动服务并通过 MCP 客户端执行 tools/list 握手
npm run smoke

# 检查 Markdown、JSON 和 TypeScript 格式
npm run format:check

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme