MCP Swagger Server(mss)

1# MCP Swagger Server(mss)
2 
3<div align="center">
4 
5[![TypeScript](https://img.shields.io/badge/TypeScript-5+-blue.svg)](https://www.typescriptlang.org/)
6[![Node.js](https://img.shields.io/badge/Node.js-16+-green.svg)](https://nodejs.org/)
7[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/zaizaizhao/mcp-swagger-server)](https://archestra.ai/mcp-catalog/zaizaizhao__mcp-swagger-server)
9 
10**一个将 OpenAPI/Swagger 规范转换为 Model Context Protocol (MCP) 格式的工具**
11 
12零配置将您的 REST API 转换为 AI 可调用的工具
13 
14[🚀 快速开始](#快速开始) • [📖 使用指南](#使用指南) • [🛠️ 开发](#开发)
15 
16**Languages**: [English](README_EN.md) | 中文
17 
18</div>
19 
20---
21## 🎯 项目截图
22 
23![项目截图](./docs/img/mss.png)
24![项目截图](./docs/img/ui.png)
25## 🎯 项目简介
26 
27MCP Swagger Server 是一个将 OpenAPI/Swagger 规范转换为 Model Context Protocol (MCP) 格式的工具。
28 
29### 📦 项目结构
30 
31```
32mcp-swagger-server/
33├── packages/
34│   ├── mcp-swagger-server/     # 🔧 核心 MCP 服务器 (可用)
35│   ├── mcp-swagger-parser/     # 📝 OpenAPI 解析器 (可用)
36│   ├── mcp-swagger-ui/         # 🎨 Web 界面 (开发中)
37│   └── mcp-swagger-api/        # 🔗 REST API 后端 (可用)
38└── scripts/                    # 🔨 构建脚本
39```
40 
41### ✨ 核心特性
42 
43- **🔄 零配置转换**: 输入 OpenAPI 规范，立即获得 MCP 工具
44- **🎯 渐进式命令行**: 提供逐步引导的命令行界面，方便用户配置
45- **🔌 多传输协议**: 支持 SSE、Streamable 和 Stdio 传输
46- **🔐 安全认证**: 支持 Bearer Token 认证保护 API 访问
47 
48## 🚀 快速开始
49 
50### 环境要求
51 
52- Node.js ≥ 20.0.0
53- pnpm ≥ 8.0.0 (推荐)
54 
55### 安装
56 
57```bash
58npm i mcp-swagger-server -g
59```
60 
61### 快速启动
62#### 自定义启动
63```bash 
64mss
65```
66#### 一键启动
67```bash 
68mss --openapi https://api.example.com/openapi.json --operation-filter-methods GET,POST --transport streamable -auth-type bearer --bearer-token "your-token-here"
69 
70# 使用配置文件
71mcp-swagger-server --config config.json
72```
73 
74#### 命令行选项
75 
76```bash
77# 基本用法
78mss [选项]
79 
80# 选项：
81--openapi, -o       OpenAPI 规范的 URL 或文件路径
82--transport, -t     传输协议 (stdio|sse|streamable)
83--port, -p          端口号
84--watch, -w         监控文件变化
85--verbose           详细日志输出
86 
87# Bearer Token 认证选项：
88--auth-type         认证类型 (bearer)
89--bearer-token      直接指定 Bearer Token
90--bearer-env        从环境变量读取 Token
91--config, -c        配置文件路径
92 
93# 操作过滤选项：
94--operation-filter-methods <methods>        HTTP方法过滤 (可重复) [示例: GET,POST]
95--operation-filter-paths <paths>            路径过滤 (支持通配符, 可重复) [示例: /api/*]
96--operation-filter-operation-ids <ids>      操作ID过滤 (可重复) [示例: getUserById]
97--operation-filter-status-codes <codes>     状态码过滤 (可重复) [示例: 200,201]
98--operation-filter-parameters <params>      参数过滤 (可重复) [示例: userId,name]
99```
100 
101### 🔐 Bearer Token 认证
102 
103`mcp-swagger-server` 支持 Bearer Token 认证，可以保护需要身份验证的 API 访问。
104 
105#### 认证方式
106 
107**1. 直接指定 Token**
108```bash
109mss --auth-type bearer --bearer-token "your-token-here" --openapi https://api.example.com/openapi.json --transport streamable
110```
111 
112 
113 
114#### 环境变量配置
115 
116创建 `.env` 文件：
117```env
118# 基础配置
119MCP_PORT=3322
120MCP_TRANSPORT=stdio
121MCP_OPENAPI_URL=https://api.example.com/openapi.json
122 
123# 认证配置
124MCP_AUTH_TYPE=bearer
125API_TOKEN=your-bearer-token-here
126```
127 
128### 🤖 与 AI 助手集成
129 
130#### Claude Desktop 配置
131 
132```json
133{
134  "mcpServers": {
135    "swagger-converter": {
136      "command": "mss",
137      "args": [
138        "--openapi", "https://petstore.swagger.io/v2/swagger.json",
139        "--transport", "stdio"
140      ]
141    },
142    "secured-api": {
143      "command": "mss",
144      "args": [
145        "--openapi", "https://api.example.com/openapi.json",
146        "--transport", "stdio",
147        "--auth-type", "bearer",
148        "--bearer-env", "API_TOKEN"
149      ],
150      "env": {
151        "API_TOKEN": "your-bearer-token-here"
152      }
153    }
154  }
155}
156```
157 
158## 🛠️ 开发
159 
160### 构建系统
161 
162```bash
163# 构建所有包
164pnpm build
165 
166# 仅构建后端包
167pnpm build:packages
168 
169# 开发模式
170pnpm dev
171 
172# 清理构建产物
173pnpm clean
174```
175## 🤝 贡献
176 
177欢迎贡献！请先阅读 [贡献指南](CONTRIBUTING.md)。
178 
179## 📄 许可证
180 
181MIT License - 详见 [LICENSE](LICENSE) 文件。
182 
183---
184 
185<div align="center">
186 
187**Built with ❤️ by ZhaoYaNan(ZTE)**
188 
189[⭐ Star](../../stargazers) • [🐛 Issues](../../issues) • [💬 Discussions](../../discussions)
190 
191</div>
192