@miku39r/knife4j-mcp 1.0.0

package/PROJECT_STRUCTURE.md

@@ -0,0 +1,213 @@
+# Knife4j MCP 项目结构
+
+## 📁 目录结构
+
+```
+knife4j-mcp/
+├── src/                          # 源代码目录
+│   ├── index.ts                  # MCP 服务器入口文件
+│   ├── knife4j-fetcher.ts        # Knife4j API 文档获取工具类
+│   ├── types.ts                  # TypeScript 类型定义
+│   └── test.ts                   # 测试脚本
+│
+├── dist/                         # 编译后的 JavaScript 代码
+│   ├── index.js                  # MCP 服务器主文件
+│   ├── knife4j-fetcher.js        # 获取工具类
+│   └── types.js                  # 类型定义
+│
+├── package.json                  # 项目配置和依赖
+├── tsconfig.json                 # TypeScript 配置
+├── mcp-config.example.json       # MCP 配置示例
+├── README.md                     # 完整使用说明
+├── QUICKSTART.md                 # 快速开始指南
+├── EXAMPLES.md                   # 详细使用示例
+└── .gitignore                    # Git 忽略文件
+```
+
+## 📄 文件说明
+
+### 核心文件
+
+#### `src/index.ts`
+- **作用**: MCP 服务器的主要入口
+- **功能**: 
+  - 创建 MCP Server 实例
+  - 注册 `fetch_api_documentation` 工具
+  - 处理客户端请求
+  - 格式化输出结果
+- **运行方式**: 通过 MCP 协议与 AI 客户端通信
+
+#### `src/knife4j-fetcher.ts`
+- **作用**: API 文档获取和解析工具类
+- **功能**:
+  - 发送 HTTP 请求获取 Swagger/OpenAPI 文档
+  - 解析不同格式的文档（Swagger 2.0、OpenAPI 3.0）
+  - 提取接口信息（路径、方法、参数、响应）
+  - 数据格式转换
+- **关键方法**: `fetchApiDocument()`
+
+#### `src/types.ts`
+- **作用**: TypeScript 类型定义
+- **包含接口**:
+  - `Knife4jDocument`: 完整的 API 文档结构
+  - `Knife4jApiInfo`: 单个 API 接口信息
+  - `ApiParameter`: 请求参数
+  - `ApiResponse`: 响应信息
+  - `FetchOptions`: 请求配置选项
+
+#### `src/test.ts`
+- **作用**: 独立测试脚本
+- **用途**: 在不启动 MCP 服务的情况下测试获取功能
+
+### 配置文件
+
+#### `package.json`
+```json
+{
+  "scripts": {
+    "build": "tsc",      // 编译 TypeScript
+    "start": "node dist/index.js",  // 启动 MCP 服务
+    "dev": "tsx src/index.ts",      // 开发模式
+    "test": "tsx src/test.ts"       // 运行测试
+  }
+}
+```
+
+#### `tsconfig.json`
+- TypeScript 编译配置
+- 输出目录：`dist/`
+- 模块系统：ESNext
+- 目标环境：ES2022
+
+#### `mcp-config.example.json`
+- MCP 客户端配置模板
+- 包含服务器路径、工作目录等配置
+
+### 文档文件
+
+#### `README.md`
+- 完整的功能说明
+- 详细的参数解释
+- 输出格式示例
+- 故障排查指南
+
+#### `QUICKSTART.md`
+- 5 分钟快速上手指南
+- 分步骤安装说明
+- 常见使用场景
+- 简化的问题排查
+
+#### `EXAMPLES.md`
+- 实际使用场景示例
+- 不同客户端的配置方法
+- 高级用法说明
+- 输出解读指南
+
+## 🔧 工作流程
+
+### 1. AI 调用流程
+
+```
+用户请求 → AI 理解意图 → MCP 客户端 → MCP 服务器 → Knife4jFetcher 
+→ HTTP 请求 → Swagger JSON → 解析 → 格式化 → 返回给 AI
+```
+
+### 2. 数据处理流程
+
+```
+输入 URL 
+↓
+HTTP GET 请求
+↓
+Swagger/OpenAPI JSON
+↓
+解析文档结构
+↓
+提取接口信息
+↓
+格式化输出
+↓
+Markdown 文本
+```
+
+## 🎯 关键技术点
+
+### MCP 协议实现
+- 使用 `@modelcontextprotocol/sdk`
+- 实现 `ListTools` 和 `CallTool` 处理器
+- 通过 `StdioServerTransport` 通信
+
+### API 文档解析
+- 支持 Swagger 2.0
+- 支持 OpenAPI 3.0+
+- 自动识别文档格式
+- 统一数据结构
+
+### 错误处理
+- 参数验证（Zod）
+- HTTP 错误捕获
+- 超时控制
+- 友好的错误消息
+
+### 输出优化
+- Markdown 格式化
+- 按标签分组显示
+- 可视化方法徽章
+- 结构化参数表格
+
+## 🚀 扩展性
+
+### 添加新工具
+在 `index.ts` 的 `setupToolHandlers()` 中添加：
+
+```typescript
+{
+  name: 'new_tool',
+  description: '新工具描述',
+  inputSchema: { /* 参数定义 */ }
+}
+```
+
+### 支持更多格式
+在 `knife4j-fetcher.ts` 中添加新的解析器：
+
+```typescript
+private parseCustomFormat(data: any): Knife4jDocument {
+  // 自定义解析逻辑
+}
+```
+
+### 增强输出格式
+修改 `formatApiDocument()` 方法，添加更多信息：
+- 认证方式说明
+- 速率限制信息
+- 版本变更记录
+
+## 📊 性能考虑
+
+- 使用 axios 的 HTTP 连接池
+- 可配置的超时时间
+- 异步非阻塞 I/O
+- 内存高效的流式处理
+
+## 🔒 安全特性
+
+- URL 验证（防止 SSRF）
+- 超时控制（防止 hangs）
+- 错误隔离（防止崩溃）
+- 无敏感信息存储
+
+## 🎨 设计模式
+
+- **单一职责**: 每个类有明确的职责
+- **依赖注入**: Fetcher 可独立替换
+- **策略模式**: 支持多种文档格式解析
+- **工厂模式**: 统一的对象创建
+
+---
+
+这个结构设计使得项目：
+✅ 易于理解和维护
+✅ 易于测试和调试  
+✅ 易于扩展和升级
+✅ 符合 TypeScript 最佳实践

package/QUICKSTART.md

@@ -0,0 +1,148 @@
+# 快速开始指南
+
+## 🚀 5 分钟快速上手
+
+### 1. 安装依赖
+
+```bash
+npm install
+```
+
+### 2. 编译项目
+
+```bash
+npm run build
+```
+
+### 3. 配置到 MCP 客户端
+
+#### Windows 用户
+
+编辑 `%APPDATA%\Claude\claude_desktop_config.json`，添加：
+
+```json
+{
+  "mcpServers": {
+    "knife4j-mcp": {
+      "command": "node",
+      "args": ["d:/front-end/gitee/knife4j-mcp/dist/index.js"],
+      "cwd": "d:/front-end/gitee/knife4j-mcp"
+    }
+  }
+}
+```
+
+#### macOS/Linux 用户
+
+编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`，添加：
+
+```json
+{
+  "mcpServers": {
+    "knife4j-mcp": {
+      "command": "node",
+      "args": ["/absolute/path/to/knife4j-mcp/dist/index.js"],
+      "cwd": "/absolute/path/to/knife4j-mcp"
+    }
+  }
+}
+```
+
+### 4. 重启 Claude Desktop
+
+关闭并重新打开 Claude Desktop。
+
+### 5. 开始使用
+
+在对话框中输入：
+
+```
+帮我获取这个接口文档的信息：http://api.example.com/v2/api-docs
+```
+
+或者：
+
+```
+我想看看我们内网服务的 API：http://192.168.1.100:8080/swagger-ui.html
+```
+
+## ✅ 验证安装
+
+运行测试命令（可选）：
+
+```bash
+npm run test http://petstore.swagger.io/v2/swagger.json
+```
+
+这会从 Swagger Petstore 获取示例 API 文档。
+
+## 📝 典型使用场景
+
+### 场景 1: 查看接口列表
+
+```
+这个 API 文档里有哪些接口？
+http://localhost:8080/v2/api-docs
+```
+
+### 场景 2: 查找特定接口
+
+```
+找一下跟用户相关的接口
+http://user-service.example.com/v2/api-docs
+```
+
+### 场景 3: 生成调用代码
+
+```
+帮我生成调用登录接口的 Python 代码
+http://auth-service.example.com/v2/api-docs
+```
+
+## 🔧 常见问题
+
+### Q: 配置后没有反应？
+
+A: 检查以下几点：
+1. 路径是否正确（使用绝对路径）
+2. 是否已执行 `npm install` 和 `npm run build`
+3. 重启 Claude Desktop
+4. 查看控制台错误信息
+
+### Q: 访问内网接口超时？
+
+A: 确认网络连通性，或增加 timeout 参数：
+```json
+{
+  "url": "http://internal-api/v2/api-docs",
+  "timeout": 30000
+}
+```
+
+### Q: 如何自定义请求头？
+
+A: 在请求时提供 headers 参数：
+```json
+{
+  "url": "http://api.example.com/v2/api-docs",
+  "headers": {
+    "Authorization": "Bearer token123"
+  }
+}
+```
+
+## 📖 更多文档
+
+- [README.md](./README.md) - 完整使用说明
+- [EXAMPLES.md](./EXAMPLES.md) - 详细使用示例
+- [test.ts](./src/test.ts) - 测试脚本源码
+
+## 🎉 开始使用
+
+现在你已经配置好了 Knife4j MCP 服务，可以开始让 AI 帮你：
+- 快速获取接口文档信息
+- 理解 API 结构
+- 生成接口调用代码
+- 分析接口依赖关系
+
+祝你使用愉快！🚀

package/README.md

@@ -0,0 +1,198 @@
+# Knife4j MCP Server
+
+一个用于获取 Knife4j 接口文档的 MCP（Model Context Protocol）服务。
+
+## 功能特性
+
+- ✅ 支持从内网/外网的 Knife4j 接口文档地址获取 API 信息
+- ✅ 自动解析 Swagger/OpenAPI 格式的接口文档
+- ✅ 提供结构化的接口信息（路径、方法、参数、响应等）
+- ✅ 友好的格式化输出，便于 AI 理解和使用
+
+## 安装步骤
+
+### 1. 安装依赖
+
+```bash
+npm install
+```
+
+### 2. 编译项目
+
+```bash
+npm run build
+```
+
+### 3. 配置到 MCP 客户端
+
+将 `mcp-config.example.json` 复制到你的 MCP 配置目录，并根据实际情况修改路径：
+
+```json
+{
+  "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：带超时设置
+
+```json
+{
+  "url": "http://api.example.com/doc.html",
+  "timeout": 15000
+}
+```
+
+#### 示例 3：需要认证的接口
+
+```json
+{
+  "url": "http://internal-api/doc.html",
+  "headers": {
+    "Authorization": "Bearer your_token_here"
+  }
+}
+```
+
+## 输出格式
+
+MCP 服务会返回格式化的 Markdown 文本，包含：
+
+- 📚 文档基本信息（标题、版本、描述）
+- 🔢 接口总数统计
+- 📁 按标签分组的接口列表
+- 📝 每个接口的详细信息：
+  - HTTP 方法和路径
+  - 接口描述
+  - 请求参数表格（参数名、类型、位置、是否必填、描述）
+  - 响应状态码和说明
+
+### 输出示例
+
+```markdown
+# 📚 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** - 参数验证
+
+## 开发调试
+
+### 开发模式
+
+```bash
+npm run dev
+```
+
+### 构建生产版本
+
+```bash
+npm run build
+```
+
+### 启动服务
+
+```bash
+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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { GetApiDocumentTool } from "./tools/get-doc";
+// Main function
+function main() {
+    // Create server instance
+    const server = new McpServer({
+        name: "ApiDocMcpServer",
+        version: "0.0.1",
+    });
+    // Register tools
+    new GetApiDocumentTool().register(server);
+    // Connect to standard input/output
+    server.connect(new StdioServerTransport());
+}
+// Start the program
+main();

package/dist/knife4j-fetcher.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Knife4j API 文档获取工具类
+ */
+import type { Knife4jDocument, FetchOptions } from './types.js';
+export declare class Knife4jFetcher {
+    /**
+     * 从 Knife4j 接口文档地址获取 API 信息
+     * @param options 请求配置选项
+     * @returns Promise<Knife4jDocument> 接口文档信息
+     */
+    fetchApiDocument(options: FetchOptions): Promise<Knife4jDocument>;
+    /**
+     * 解析 Swagger/OpenAPI 文档
+     * @param data Swagger 数据
+     * @param originalUrl 原始 URL
+     * @returns Knife4jDocument
+     */
+    private parseSwaggerDocument;
+    /**
+     * 解析单个 API 操作
+     */
+    private parseApiOperation;
+    /**
+     * 解析请求参数
+     */
+    private parseParameters;
+    /**
+     * 获取参数类型
+     */
+    private getParameterType;
+    /**
+     * 解析响应
+     */
+    private parseResponses;
+    /**
+     * 从 URL 提取基础路径
+     */
+    private extractBaseUrl;
+}