Swagger Prompts MCP

Swagger Prompts MCP

](https://badge.fury.io/js/swagger-prompts-mcp)   

一个专业的 Swagger/OpenAPI 接口解析工具，支持 MCP 服务器和 CLI 两种使用方式。

✨ 特性

• 🚀 快速解析 - 秒级解析大型 Swagger/OpenAPI 文档
• 📝 中文提示 - 生成完整的中文 API 文档提示词
• 🔗 引用解析 - 自动解析所有 $ref 引用
• 🌍 路径前缀 - 自动识别并添加 servers[0].url 路径前缀
• 📦 双重模式 - 支持 MCP 服务器和独立 CLI 工具
• 🎯 智能提示 - 生成适合 AI 模型的 JSON Schema 格式
• 🔐 认证支持 - 支持 Bearer Token 和基本认证（用户名/密码）
• 💾 本地下载 - 一键下载 Swagger JSON 到本地文件

📦 安装

全局安装（推荐）

pnpm add -g swagger-prompts-mcp
npm install -g swagger-prompts-mcp

项目内安装

pnpm add swagger-prompts-mcp
npm install swagger-prompts-mcp

🚀 快速开始

1. CLI 命令行工具

解析 API 接口

# 基础用法
swagger-prompts parse-endpoint \
  -u https://petstore.swagger.io/v2/swagger.json \
  -p /pet/{petId} \
  -m get

# 带认证
swagger-prompts parse-endpoint \
  -u https://api.example.com/swagger.json \
  -p /users \
  -m get \
  -h "Authorization=Bearer token"

# 保存到文件
swagger-prompts parse-endpoint \
  -u https://petstore.swagger.io/v2/swagger.json \
  -p /pet \
  -m post \
  -o pet-api.md

解析 Schema

swagger-prompts parse-schema \
  -u https://petstore.swagger.io/v2/swagger.json \
  -s Pet

下载 Swagger JSON

# 基础下载（自动生成文件名）
swagger-prompts download \
  -u https://petstore.swagger.io/v2/swagger.json

# 指定保存路径
swagger-prompts download \
  -u https://petstore.swagger.io/v2/swagger.json \
  -o ./api-docs.json

# 带认证下载
swagger-prompts download \
  -u https://api.example.com/swagger.json \
  --username admin \
  --password secret123 \
  -o ./private-api.json

2. MCP 服务器

Claude Code 配置

编辑 MCP 客户端配置文件：

{
  "mcpServers": {
    "swagger-prompts": {
      "command": "node",
      "args": ["/path/to/swagger-prompts-mcp/dist/index.js"]
    }
  }
}

在 Claude Code 中使用

解析 https://petstore.swagger.io/v2/swagger.json 中的 GET /pet/{petId} 接口

解析 https://petstore.swagger.io/v2/swagger.json 中的 Pet Schema

下载 https://petstore.swagger.io/v2/swagger.json 到本地文件

📖 使用指南

CLI 命令详解

parse-endpoint - 解析 API 接口

swagger-prompts parse-endpoint [options]

选项：
  -u, --url           Swagger/OpenAPI 文档 URL（必需）
  -p, --path 
        API 接口路径（必需）
  -m, --method     HTTP 方法：get|post|put|patch|delete|head|options（必需）
  -o, --output       输出文件路径（可选，默认输出到控制台）
  -h, --header  自定义请求头，格式：Key=Value（可选）
  -t, --timeout        请求超时时间，毫秒（默认：30000）

parse-schema - 解析 Schema

swagger-prompts parse-schema [options]

选项：
  -u, --url           Swagger/OpenAPI 文档 URL（必需）
  -s, --schema       Schema 名称（必需）
  -o, --output       输出文件路径（可选）
  -h, --header  自定义请求头（可选）
  -t, --timeout        请求超时时间，毫秒（默认：30000）

download - 下载 Swagger JSON

swagger-prompts download [options]

选项：
  -u, --url           Swagger/OpenAPI 文档 URL（必需）
  -o, --output       保存文件路径（可选，不提供则自动生成）
  --username     认证用户名（可选）
  --password 
    认证密码（可选）
  -h, --header  自定义请求头（可选）
  -t, --timeout        请求超时时间，毫秒（默认：30000）

路径前缀处理

工具会自动处理路径前缀：

• OpenAPI 3.0 - 从 servers[0].url 提取路径前缀
• Swagger 2.0 - 从 basePath 提取路径前缀

例如：

• servers[0].url: http://test.com/api/v1
• 用户请求路径：/users
• 生成路径：/api/v1/users

MCP 工具调用

parseApiEndpoint

{
  "name": "parseApiEndpoint",
  "arguments": {
    "url": "https://petstore.swagger.io/v2/swagger.json",
    "path": "/pet/{petId}",
    "method": "get",
    "headers": {
      "Authorization": "Bearer token"
    }
  }
}

parseSchema

{
  "name": "parseSchema",
  "arguments": {
    "url": "https://petstore.swagger.io/v2/swagger.json",
    "schemaName": "Pet"
  }
}

downloadSwaggerJson

{
  "name": "downloadSwaggerJson",
  "arguments": {
    "url": "https://petstore.swagger.io/v2/swagger.json",
    "savePath": "./api-docs.json"
  }
}

带认证的下载

{
  "name": "downloadSwaggerJson",
  "arguments": {
    "url": "https://api.example.com/swagger.json",
    "username": "admin",
    "password": "secret123",
    "savePath": "./private-api.json"
  }
}

📋 示例

示例 1：解析宠物商店 API

# 获取宠物信息接口
swagger-prompts parse-endpoint \
  -u https://petstore.swagger.io/v2/swagger.json \
  -p /pet/{petId} \
  -m get

# 添加新宠物接口
swagger-prompts parse-endpoint \
  -u https://petstore.swagger.io/v2/swagger.json \
  -p /pet \
  -m post \
  -o add-pet.md

示例 2：带认证的 API

# 使用 API Key
swagger-prompts parse-endpoint \
  -u https://api.example.com/v1/swagger.json \
  -p /protected/data \
  -m get \
  -h "X-API-Key=your-api-key"

# 使用 Bearer Token
swagger-prompts parse-endpoint \
  -u https://api.example.com/v1/swagger.json \
  -p /user/profile \
  -m get \
  -h "Authorization=Bearer your-token"

示例 3：批量处理

#!/bin/bash
# 批量解析多个接口

URL="https://api.example.com/swagger.json"

# 解析多个接口
swagger-prompts parse-endpoint -u $URL -p /users -m get -o users-get.md
swagger-prompts parse-endpoint -u $URL -p /users -m post -o users-post.md
swagger-prompts parse-endpoint -u $URL -p /users/{id} -m get -o users-get-by-id.md

# 解析常用 Schema
swagger-prompts parse-schema -u $URL -s User -o user-schema.md
swagger-prompts parse-schema -u $URL -s Error -o error-schema.md

🔧 开发

环境要求

• Node.js >= 18
• pnpm >= 10

开发设置

# 克隆仓库
git clone git@github.com:SublimeCT/swagger-prompts-mcp.git
cd swagger-prompts-mcp

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 测试
pnpm test

# 代码格式化
pnpm lint

项目结构

src/
├── index.ts              # MCP 服务器入口
├── cli.ts                # CLI 工具入口
├── core/                 # 核心模块
│   ├── api-parser.ts     # API 解析器
│   └── prompt-generator.ts # 提示词生成器
├── types/                # 类型定义
│   ├── api.ts            # API 相关类型
│   ├── openapi.ts        # OpenAPI 类型
│   ├── prompt.ts         # 提示词类型
│   ├── swagger.ts        # Swagger 类型
│   └── index.ts          # 类型导出
└── utils/                # 工具函数
    ├── downloadSwagger.ts # 下载 Swagger JSON
    ├── fetchSwagger.ts   # 获取文档
    ├── parseApiEndpoints.ts # 解析 API 接口
    ├── parseOpenApiEndpoints.ts # 解析 OpenAPI 接口
    ├── parseSchema.ts    # 解析 Schema
    └── schema-utils.ts   # Schema 工具

🤝 贡献

欢迎贡献代码！请查看 贡献指南 了解详情。

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

• FastMCP - MCP 服务器框架
• json-schema-ref-parser - JSON Schema 引用解析
• Commander.js - CLI 框架

🔗 相关链接

• OpenAPI 规范
• MCP 协议
• Claude Code

Made with ❤️ by the community

📝 文档 | 🐛 问题反馈 | 💬 讨论 | 🔗 源码