knife4j-mcp

一个基于 Node.js + TypeScript 的标准 MCP server（stdio），用于读取 Knife4j / Swagger 多模块接口文档，并为 Agent 提供结构化接口查询能力。

它适合这样的场景：

• 文档入口不是单个 OpenAPI spec，而是 Knife4j 聚合页

• 需要先从 /swagger-resources 获取模块列表

• 每个模块再去拉自己的 /v2/api-docs

• 文档可能受 Basic Auth 或自定义 Header 保护

• Agent 需要根据路径、关键词、tag、字段线索快速定位接口

使用方式

SWAGGER_RESOURCES_URL=http://127.0.0.1:3301/swagger-resources \
npx -y @chaselen/knife4j-mcp

如果文档受保护，也可以一起传认证信息：

SWAGGER_RESOURCES_URL=http://127.0.0.1:3301/swagger-resources \
SWAGGER_BASIC_AUTH=demo:demo \
npx -y @chaselen/knife4j-mcp

说明：

• 已发布到 npm，可直接通过 npx 启动

• 要求 Node.js >= 20

• 这是一个 stdio MCP server，通常由 MCP Client 拉起，而不是手动长期在终端里交互运行

Related MCP server: swagger-json-mcp

MCP Client 接入

这个包不只支持 Codex，也支持 Claude Code、OpenCode，以及其他支持本地 stdio MCP 的客户端。

本质上都可以抽象成下面这组启动参数：

{
  "command": "npx",
  "args": ["-y", "@chaselen/knife4j-mcp"],
  "env": {
    "SWAGGER_RESOURCES_URL": "http://127.0.0.1:3301/swagger-resources",
    "SWAGGER_BASIC_AUTH": "demo:demo"
  }
}

Codex CLI

codex mcp add knife4j-swagger \
  --env SWAGGER_RESOURCES_URL=http://127.0.0.1:3301/swagger-resources \
  --env SWAGGER_BASIC_AUTH=demo:demo \
  -- npx -y @chaselen/knife4j-mcp

Claude Code

CLI 添加方式：

claude mcp add knife4j-swagger \
  --env SWAGGER_RESOURCES_URL=http://127.0.0.1:3301/swagger-resources \
  --env SWAGGER_BASIC_AUTH=demo:demo \
  -- npx -y @chaselen/knife4j-mcp

如果你偏好项目级配置，也可以在项目根目录放一个 .mcp.json：

{
  "mcpServers": {
    "knife4j-swagger": {
      "command": "npx",
      "args": ["-y", "@chaselen/knife4j-mcp"],
      "env": {
        "SWAGGER_RESOURCES_URL": "http://127.0.0.1:3301/swagger-resources",
        "SWAGGER_BASIC_AUTH": "demo:demo"
      }
    }
  }
}

OpenCode

在 opencode.json 或 opencode.jsonc 中加入：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "knife4j-swagger": {
      "type": "local",
      "command": ["npx", "-y", "@chaselen/knife4j-mcp"],
      "enabled": true,
      "environment": {
        "SWAGGER_RESOURCES_URL": "http://127.0.0.1:3301/swagger-resources",
        "SWAGGER_BASIC_AUTH": "demo:demo"
      }
    }
  }
}

其他客户端

如果你的 MCP 客户端支持本地 stdio server，通常只要把下面三类信息按它自己的格式填进去即可：

• command: npx

• args: ["-y", "@chaselen/knife4j-mcp"]

• env: SWAGGER_RESOURCES_URL、SWAGGER_BASIC_AUTH、SWAGGER_HEADERS 等环境变量

环境变量

必填

• SWAGGER_RESOURCES_URL

  • Knife4j / Swagger 聚合入口地址，用来读取模块列表。

  • 这个地址通常就是平台暴露出来的 /swagger-resources，例如：http://127.0.0.1:3301/swagger-resources

  • server 启动后会先请求它，再根据返回结果继续拉取每个模块自己的 Swagger / OpenAPI 文档。

  • 注意：这里填的不是某个单独模块的 /v2/api-docs 或 /v3/api-docs，而是“模块目录入口”。

可选

• SWAGGER_BASE_URL

  • 用于补全 swagger-resources 里返回的相对路径。

  • 如果模块文档地址是 /api/user/v2/api-docs 这种相对路径，server 会拿它和 SWAGGER_BASE_URL 进行拼接。

  • 未设置时，默认回退到 SWAGGER_RESOURCES_URL 的基址。

  • 常见场景是：swagger-resources 和真实文档地址不在同一个基址下，或者经过了网关改写。

• SWAGGER_BASIC_AUTH

  • 访问 Swagger 文档时使用的 HTTP Basic Auth 账号密码。

  • 这个值会同时用于请求 SWAGGER_RESOURCES_URL 和每个模块的 spec 文档。

  • 格式是 username:password，例如：demo:demo

  • 不需要带 Basic 前缀，程序会自动转成 Authorization: Basic ... 请求头。

  • 如果你的文档地址本身不需要登录认证，可以不填。

• SWAGGER_HEADERS

  • 额外附带到所有文档请求上的自定义 HTTP Header。

  • 适合需要 Token、租户标识、环境标识这类网关头的场景。

  • 格式是 JSON 字符串，例如：{"X-Env":"dev","X-Token":"abc"}

  • 这些 Header 会和 Basic Auth 一起生效；如果两者都配置了，请求会同时带上。

• SWAGGER_MODULE_ALLOWLIST

  • 只加载指定模块，其他模块会被忽略。

  • 适合模块很多、只想给 Agent 暴露其中一部分接口时使用。

  • 格式为逗号分隔，例如：sample-account,sample-auth

  • 这里填写的名称应与 swagger-resources 返回的模块名一致。

• CACHE_TTL_MS

  • 内存缓存有效期，单位是毫秒。

  • 默认值是 300000，也就是 5 分钟。

  • 在缓存有效期内，查询会直接复用已加载的索引；过期后会在下次刷新时重新拉取远端文档。

• SWAGGER_REQUEST_TIMEOUT_MS

  • 单次请求 swagger-resources 或模块 spec 的超时时间，单位是毫秒。

  • 默认值是 15000，也就是 15 秒；必须是大于 0 的数字。

• SWAGGER_FETCH_CONCURRENCY

  • 同时拉取模块 spec 的最大请求数。

  • 默认值是 8，允许设置为 1 到 100 之间的整数。

  • 模块很多或上游网关有连接数限制时，可以适当调低。

• SWAGGER_EXTERNAL_REF_LIMIT

  • 单个模块最多自动加载的外部 $ref JSON 文档数。

  • 默认值是 32，允许设置为 0 到 200；设置为 0 可关闭外部引用加载。

  • 外部文档使用与主 spec 相同的 Basic Auth、自定义 Header 和请求超时配置。

• SWAGGER_EXTERNAL_REF_ORIGINS

  • 允许加载跨 origin 外部 $ref 的白名单，使用逗号分隔，例如：https://schemas.example.com,http://localhost:8080。

  • 默认只允许与当前模块 spec 同 origin 的外部引用，避免把认证 Header 转发到未授权地址。

  • 白名单按 origin 匹配，配置中的路径会被忽略；只支持 HTTP 和 HTTPS。

• LOG_LEVEL

  • 日志级别。

  • 当前设为 debug 时会输出更多拉取和解析过程日志，便于排查文档地址、认证或 JSON 格式问题。

一个更完整的例子

SWAGGER_RESOURCES_URL=https://gateway.example.com/swagger-resources \
SWAGGER_BASIC_AUTH=swagger_user:swagger_password \
SWAGGER_HEADERS='{"X-Env":"prod","X-Tenant":"platform"}' \
SWAGGER_MODULE_ALLOWLIST=system-user,system-auth \
npx -y @chaselen/knife4j-mcp

MCP Tools

对外只提供 4 个核心 tools：

• list_specs：列出模块、spec 地址、加载状态和接口数量

• find_api：按关键词、path、tag、module、method、接口类型和弃用状态搜索接口

  • 支持 offset + limit 分页

  • total 表示全部命中数，returned 表示本页数量，hasMore 表示是否还有后续结果

  • 相同相关性分数下使用稳定排序，便于可靠翻页

• get_api_detail：获取单个接口的完整详情，并递归展开请求/响应 schema

  • 默认保持完整兼容输出

  • 传入 includeRaw: false 可省略递归结果中的 raw 和顶层 rawOperation，减少 Agent 上下文占用

• refresh_specs：强制刷新 swagger-resources 和所有模块 spec

功能

• 支持读取 Knife4j / Swagger 多模块聚合文档

• 支持 Basic Auth 和自定义 Header

• 支持 Swagger 2.0，并尽量兼容 OpenAPI 3

• 支持按路径、关键词、tag、method 等条件搜索接口

• 在刷新阶段预计算路径别名和全文搜索文本，减少查询时的重复解析

• get_api_detail 可使用原始短路径、规范化路径或可唯一匹配的完整网关路径

• 支持通过 get_api_detail 获取完整接口详情，并递归展开请求/响应 schema

• 详情会显式返回 operationId、弃用状态、认证要求、servers、externalDocs、callbacks 和 security schemes

• 请求与响应详情支持 examples、encoding、响应 headers 与 links

• Schema 展开支持 OpenAPI 3.1 nullable 类型、default、const、examples、读写属性、discriminator 和常用校验约束

• 支持自动加载并打包跨文件 $ref，同时限制外部文档数量

• OpenAPI 3.1 webhooks 会作为 kind: "webhook" 的接口参与搜索

• 支持模块 allowlist、缓存 TTL 和手动刷新

• 单个模块加载失败不会影响其他模块可用

• 刷新发生临时失败时保留该模块上一次成功的索引，并在模块状态中标记 stale

• 聚合入口刷新失败时继续提供上一次成功的完整索引，并标记整体与模块状态为 stale

• 模块 spec 使用可配置的并发上限拉取，避免刷新时瞬间压高网关连接数

• 无效 spec 和重复模块名会被隔离并显示为失败状态

兼容性边界

• 支持 Swagger 2.x、OpenAPI 3.0 和常用 OpenAPI 3.1 JSON Schema 字段。

• 本地 JSON Pointer 与 HTTP(S) JSON 外部 $ref 可以递归展开；不解析 YAML、file: 或其他协议。

• 循环引用会保留为带 ref / refName 的节点，避免无限递归。

• callbacks、links、securitySchemes 等复杂扩展会保留结构化原始定义；请求和响应的主要 Schema 会进一步展开。

开发与验证

npm install
npm test
npm pack --dry-run

• npm test 会构建项目并运行 parser、registry、HTTP 配置和 MCP 内存传输集成测试。

最小可运行示例

仓库自带一个 mock 的多模块 Swagger 服务。

1. 启动 mock 文档服务

MOCK_SWAGGER_BASIC_AUTH=demo:demo npm run mock:swagger

默认地址：

• http://127.0.0.1:3301/swagger-resources

• http://127.0.0.1:3301/sample-account/v2/api-docs

• http://127.0.0.1:3301/sample-auth/v2/api-docs

• http://127.0.0.1:3301/demo/sample-notify/v3/api-docs

2. 构建 MCP server

npm run build

3. 运行 smoke test

SWAGGER_RESOURCES_URL=http://127.0.0.1:3301/swagger-resources \
SWAGGER_BASIC_AUTH=demo:demo \
npm run test:smoke

这个脚本会通过 MCP stdio client 依次调用：

• tools/list

• list_specs

• find_api

• get_api_detail

它会自动完成一次 list_specs -> find_api -> get_api_detail 的最小联调验证。