@chaselen/knife4j-mcp

v0.3.0

Published

15 days ago

MCP server for querying Knife4j / Swagger multi-module API docs

0High
0Medium
0Low

chaselen

mcp knife4j swagger openapi codex

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 拉起，而不是手动长期在终端里交互运行

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 分钟。
- 在缓存有效期内，查询会直接复用已加载的索引；过期后会在下次刷新时重新拉取远端文档。
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 搜索接口
get_api_detail：获取单个接口的完整详情，并递归展开请求/响应 schema
refresh_specs：强制刷新 swagger-resources 和所有模块 spec

功能

支持读取 Knife4j / Swagger 多模块聚合文档
支持 Basic Auth 和自定义 Header
支持 Swagger 2.0，并尽量兼容 OpenAPI 3
支持按路径、关键词、tag、method 等条件搜索接口
支持通过 get_api_detail 获取完整接口详情，并递归展开请求/响应 schema
支持模块 allowlist、缓存 TTL 和手动刷新
单个模块加载失败不会影响其他模块可用

最小可运行示例

仓库自带一个 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 的最小联调验证。