AI导哈

MCP服务器生成工具

一个从Swagger/OpenAPI文档生成Model Context Protocol (MCP)服务器的CLI工具，支持自动创建TypeScript API类型和完整的项目结构。

  • by Ngineer101
  • TypeScript
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 Ngineer101/lightning-mcp

使用说明

MCP转轮

一个CLI工具，从Swagger/OpenAPI文档生成模型上下文协议（MCP）服务器。

特性

  • 🚀 从Swagger/OpenAPI JSON文档生成功能齐全的MCP服务器
  • 📝 从架构自动创建TypeScript API类型
  • 🔧 支持所有HTTP方法和参数类型（查询、路径、标头、正文）
  • 📡 用于MCP通信的内置stdio传输
  • 🎯 每个API端点都成为一个具有正确描述和输入模式的MCP工具
  • 📦 使用构建配置生成完整的项目结构

安装

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

用法

基本用法

node dist/cli.js --doc <swagger-json-path-or-url> [--output <output-directory>]

例子

# Generate MCP server from a local Swagger document
node dist/cli.js --doc api-spec.json --output my-api-server

# Generate from a remote URL
node dist/cli.js --doc https://petstore.swagger.io/v2/swagger.json --output petstore-server

# Use default output directory (./generated-mcp-server)
node dist/cli.js --doc api-spec.json

选项

  • --doc <path>：Swagger/OpenAPI JSON文档的路径或URL（必填）
  • --output <path>：生成的MCP服务器的输出目录（默认： ./generated-mcp-server)
  • --help：显示帮助信息
  • --version：显示版本信息

生成的MCP服务器

生成的MCP服务器包括：

  • src/index.ts：主要MCP服务器实现，每个API端点都有工具
  • src/types.ts：从Swagger模式生成的TypeScript类型
  • package.json：带依赖项的Node.js包配置
  • tsconfig.json：TypeScript编译配置
  • README.md：生成的服务器的文档

运行生成的服务器

cd <output-directory>
npm install
npm run build
npm start

服务器在stdio传输上运行，可以与任何兼容MCP的客户端一起使用。

运作原理

  1. 解析Swagger：读取并验证提供的Swagger/OpenAPI文档
  2. 提取端点：标识所有API终结点及其方法、参数和架构
  3. 生成类型：从Swagger模式创建TypeScript接口和类型
  4. 创建工具：将每个API端点映射到具有正确输入验证的MCP工具
  5. 构建服务器：生成具有stdio传输的完整MCP服务器
  6. 包装工程：创建一个包含所有必要文件的可构建Node.js项目

API端点映射

Swagger文档中的每个API端点都成为MCP工具：

  • 工具名称：使用 operationId 从Swagger生成，或从方法+路径生成
  • 描述：使用 summary 或 description 从端点
  • 输入架构：组合查询参数、路径参数、标头和请求正文
  • HTTP处理：使用所有参数和标头正确构造HTTP请求

参数支持

  • 查询参数：添加到请求URL中
  • 路径参数：在URL路径中替换
  • 标题参数：添加到请求标头中
  • 请求正文：在请求正文中以JSON格式发送
  • 响应处理：返回完整的HTTP响应，包括状态、标头和数据

例子

输入Swagger文档

{
  "openapi": "3.0.0",
  "info": {
    "title": "User API",
    "version": "1.0.0"
  },
  "paths": {
    "/users/{id}": {
      "get": {
        "operationId": "getUserById",
        "summary": "Get user by ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ]
      }
    }
  }
}

生成的MCP工具

上述端点将成为名为的MCP工具 getUserById 与：

  • 说明：“按ID获取用户”
  • 输入架构需要 id 字符串参数
  • HTTP GET请求 /users/{id} 带路径参数替换

发展

项目结构

mcpr/
├── src/
│   ├── cli.ts           # CLI entry point
│   ├── parser.ts        # Swagger document parser
│   ├── generator.ts     # MCP server generator
│   ├── type-generator.ts # TypeScript type generator
│   └── templates.ts     # Code templates
├── dist/                # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

脚本

  • npm run build：将TypeScript编译为JavaScript
  • npm run dev：使用tsx在开发模式下运行CLI
  • npm run lint：运行ESLint
  • npm run typecheck：运行TypeScript类型检查

需求

  • Node.js 18+
  • TypeScript 5+
  • Swagger/OpenAPI 3.0+文档

全部

  • 在输出目录中添加用于初始化git存储库的可选参数
  • 添加可选参数以指定传输类型（stdio、http等）
  • 为CLI添加测试
  • 添加对身份验证的支持（例如，API密钥、OAuth）

相关 MCP