MCP Runner

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

特性

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

安装

# 安装依赖
npm install

# 构建项目
npm run build

# 全局链接（可选）
npm link

使用

基本用法

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

示例

# 从本地Swagger文档生成MCP服务器
node dist/cli.js --doc api-spec.json --output my-api-server

# 从远程URL生成
node dist/cli.js --doc https://petstore.swagger.io/v2/swagger.json --output petstore-server

# 使用默认输出目录（./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工具：

• 工具名称: 使用Swagger中的operationId，或者根据方法+路径生成一个
• 描述: 使用端点的summary或description
• 输入模式: 结合查询参数、路径参数、头部和请求主体
• HTTP处理: 正确构造带有所有参数和头部的HTTP请求

参数支持

• 查询参数: 添加到请求URL中
• 路径参数: 替换在URL路径中
• 头部参数: 添加到请求头部
• 请求主体: 作为JSON发送在请求主体中
• 响应处理: 返回完整的HTTP响应，包括状态码、头部和数据

示例

输入Swagger文档

{
  "openapi": "3.0.0",
  "info": {
    "title": "用户API",
    "version": "1.0.0"
  },
  "paths": {
    "/users/{id}": {
      "get": {
        "operationId": "getUserById",
        "summary": "通过ID获取用户",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ]
      }
    }
  }
}

生成的MCP工具

上述端点会变成名为getUserById的MCP工具：

• 描述："通过ID获取用户"
• 输入模式需要一个id字符串参数
• HTTP GET请求到/users/{id}，替换路径参数

开发

项目结构

mcpr/
├── src/
│   ├── cli.ts           # CLI入口点
│   ├── parser.ts        # Swagger文档解析器
│   ├── generator.ts     # MCP服务器生成器
│   ├── type-generator.ts # TypeScript类型生成器
│   └── templates.ts     # 代码模板
├── dist/                # 编译后的JavaScript
├── package.json
├── tsconfig.json
└── README.md

脚本

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

要求

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

待办事项

• 添加初始化git仓库的可选参数
• 添加指定传输类型的可选参数（stdio, http等）
• 为CLI添加测试
• 添加对认证的支持（例如API密钥，OAuth）