Knife4j MCP Server

一个用于获取 Knife4j 接口文档的 MCP（Model Context Protocol）服务。

功能特性

• ✅ 支持从内网/外网的 Knife4j 接口文档地址获取 API 信息
• ✅ 自动解析 Swagger/OpenAPI 格式的接口文档
• ✅ 提供结构化的接口信息（路径、方法、参数、响应等）
• ✅ 友好的格式化输出，便于 AI 理解和使用

安装步骤

1. 安装依赖

npm install

2. 编译项目

npm run build

3. 配置到 MCP 客户端

将 mcp-config.example.json 复制到你的 MCP 配置目录，并根据实际情况修改路径：

{
  "mcpServers": {
    "knife4j-mcp": {
      "command": "node",
      "args": ["你的路径/knife4j-mcp/dist/index.js"],
      "cwd": "你的路径/knife4j-mcp",
      "env": {}
    }
  }
}

使用方法

工具名称

fetch_api_documentation

参数说明

| 参数名 | 类型 | 必填 | 默认值 | 描述 | |--------|------|------|--------|------| | url | string | ✅ 是 | - | Knife4j 接口文档的 URL 地址 | | timeout | number | ⭕ 否 | 10000 | 请求超时时间（毫秒） | | headers | object | ⭕ 否 | - | 自定义请求头 |

使用示例

示例 1：基本使用

请帮我获取这个接口文档的信息：http://localhost:8080/doc.html

AI 会自动调用 MCP 服务，返回所有接口的详细信息。

示例 2：带超时设置

{
  "url": "http://api.example.com/doc.html",
  "timeout": 15000
}

示例 3：需要认证的接口

{
  "url": "http://internal-api/doc.html",
  "headers": {
    "Authorization": "Bearer your_token_here"
  }
}

输出格式

MCP 服务会返回格式化的 Markdown 文本，包含：

• 📚 文档基本信息（标题、版本、描述）
• 🔢 接口总数统计
• 📁 按标签分组的接口列表
• 📝 每个接口的详细信息：
  • HTTP 方法和路径
  • 接口描述
  • 请求参数表格（参数名、类型、位置、是否必填、描述）
  • 响应状态码和说明

输出示例

# 📚 API 文档：用户管理系统

**版本**: 1.0.0
**描述**: 用户管理相关的 RESTful API
**基础 URL**: http://api.example.com

**接口总数**: 5

## 📁 User Controller

### 🟢 GET `http://api.example.com/api/users`

获取用户列表

**请求参数:**

| 参数名 | 类型 | 位置 | 必填 | 描述 |
|--------|------|------|------|------|
| page | integer | query | ⭕ | 页码 |
| size | integer | query | ⭕ | 每页数量 |

**响应:**

- **200**: 成功
- **404**: 未找到

### 🔵 POST `http://api.example.com/api/users`

创建新用户

**请求参数:**

| 参数名 | 类型 | 位置 | 必填 | 描述 |
|--------|------|------|------|------|
| body | object | body | ✅ | 用户信息 |

...

技术栈

• TypeScript - 类型安全
• @modelcontextprotocol/sdk - MCP 官方 SDK
• axios - HTTP 请求库
• zod - 参数验证

开发调试

开发模式

npm run dev

构建生产版本

npm run build

启动服务

npm start

支持的文档格式

• ✅ Swagger 2.0
• ✅ OpenAPI 3.0+
• ✅ Knife4j 增强的 Swagger 文档

注意事项

1. 确保提供的 URL 可以访问（内网地址需要在同一网络环境）
2. 如果接口文档需要认证，请通过 headers 参数提供必要的认证信息
3. 默认超时时间为 10 秒，可根据网络情况调整
4. 仅支持 JSON 格式的 Swagger/OpenAPI 文档

常见问题

Q: 无法访问内网接口文档？

A: 确保运行 MCP 服务的机器与内网在同一网络环境，或者通过代理访问。

Q: 返回的数据格式不对？

A: 检查目标 URL 是否返回标准的 Swagger/OpenAPI JSON 格式数据。

Q: 如何查看详细的错误信息？

A: 查看控制台输出，MCP 服务会记录详细的错误日志。

License

MIT