mcp-swagger-server/README.md

MCP Swagger Server(mss)

将 OpenAPI/Swagger 规范转换为 Model Context Protocol (MCP) 格式的工具

---

🚀 快速开始

环境要求

• Node.js ≥ 20.0.0
• pnpm ≥ 8.0.0

安装 OpenCode Skill

将项目中的 skill 安装到 OpenCode：

# 方式一：复制 skill 目录
cp -r .opencode/skills/mcp-swagger-server ~/.opencode/skills/

# 方式二：在 opencode 中使用 skill
# 在 opencode 对话中提及相关任务时会自动触发

安装 Node.js 和 pnpm（离线环境）

项目已预下载 Node.js 和 pnpm 工具，放在 tools/ 目录下：

tools/
├── node/
│   ├── node-v20.20.2-win-x64.zip      # Windows Node.js
│   └── node-v20.20.2-linux-x64.tar.xz  # Linux Node.js
└── pnpm/
    ├── pnpm-win-x64.exe                 # Windows pnpm
    └── pnpm-linux-x64                  # Linux pnpm

1. 安装 Node.js

Windows:

双击对应版本的msi文件进行安装

# 验证
node -v

Linux:

# 解压到 /opt/nodejs
sudo tar -xf tools/node/node-v20.20.2-linux-x64.tar.xz -C /opt

# 添加到 PATH
export PATH=/opt/nodejs/node-v20.20.2-linux-x64/bin:$PATH

# 验证
node -v

2. 安装 pnpm

Windows:

# 将 pnpm.exe 拷贝到 Node.js 安装目录
copy tools\pnpm\pnpm-win-x64.exe C:\nodejs\node-v20.20.2-win-x64\pnpm.exe

# 验证
C:\nodejs\node-v20.20.2-win-x64\pnpm.exe -v

Linux:

# 拷贝到 /usr/local/bin
sudo cp tools/pnpm/pnpm-linux-x64 /usr/local/bin/pnpm
sudo chmod +x /usr/local/bin/pnpm

# 验证
pnpm -v

安装步骤

1. 将以下目录拷贝到离线环境：

• dist-offline/ - MCP Swagger Server 及源码
• tools/ - Node.js 和 pnpm 工具

2. 在离线环境安装依赖：

cd dist-offline
node scripts/offline-install.js
pnpm mss --help

---

🤖 OpenCode SKILL 使用流程

方式一：通过配置文件（推荐批量使用）

1. 准备 API 配置文件

创建 my-apis.json：

{
  "startDelay": 1,
  "apis": [
    {
      "name": "user-api",
      "openapi": "https://api.example.com/user/swagger.json",
      "transport": "streamable",
      "port": 3322,
      "authType": "bearer",
      "bearerToken": "your-user-api-key"
    },
    {
      "name": "order-api",
      "openapi": "https://api.example.com/order/swagger.json",
      "transport": "streamable",
      "port": 3323,
      "authType": "none"
    }
  ]
}

2. 在 OpenCode 中调用

告诉用户：

请使用 mcp-swagger-server skill 来启动这些 API。我把 API 配置放在了 my-apis.json 文件中。

OpenCode 会：

1. 读取配置文件
2. 启动所有配置的 API 服务
3. 告知每个服务的端口和状态

---

方式二：直接在对话中指定

单个 API：

请帮我把 https://api.example.com/user/swagger.json 这个 OpenAPI 文档转成 MCP 服务，使用 STDIO 模式。

带认证：

请帮我把 https://api.example.com/user/swagger.json 转成 MCP 服务，认证方式是 bearer token: sk-xxxxxx

带路径过滤：

请把 https://api.example.com/swagger.json 转成 MCP，只转换 /users/* 和 /orders/* 路径的接口。

---

Claude Desktop 集成

将 MCP 服务添加到 Claude Desktop 配置：

{
  "mcpServers": {
    "user-api": {
      "command": "node",
      "args": [
        "/path/to/dist-offline/packages/mcp-swagger-server/dist/cli.js",
        "--transport", "stdio",
        "--openapi", "https://api.example.com/user/swagger.json",
        "--auth-type", "bearer",
        "--bearer-env", "USER_API_TOKEN"
      ]
    }
  }
}

---

📦 批量管理多个 API 服务

配置多个 API

编辑 scripts/apis-config.json：

{
  "startDelay": 1,
  "apis": [
    {
      "name": "user-api",
      "openapi": "https://api.example.com/user/swagger.json",
      "transport": "streamable",
      "port": 3322,
      "baseUrl": "https://api.example.com/user/v1",
      "authType": "bearer",
      "bearerToken": "your-token"
    },
    {
      "name": "order-api",
      "openapi": "./specs/order.json",
      "transport": "streamable",
      "port": 3323,
      "authType": "bearer",
      "bearerEnv": "ORDER_TOKEN"
    }
  ]
}

批量管理命令

node scripts/batch-run.js start   # 启动所有服务
node scripts/batch-run.js status  # 查看状态
node scripts/batch-run.js stop    # 停止所有服务

支持的配置项

配置项	说明
name	服务名称
openapi	OpenAPI 文档 URL 或本地文件路径
transport	传输协议：stdio / sse / streamable
port	端口号（stdio 模式不需要）
baseUrl	API 基础 URL
authType	认证类型：bearer / none
bearerToken	Bearer Token 静态值
bearerEnv	环境变量名
operationFilterMethods	HTTP 方法过滤，如 ["GET", "POST"]
operationFilterPaths	路径过滤（支持通配符），如 ["/users/*"]
customHeaders	自定义请求头

---

📦 批量管理多个 API 服务

文本配置文件

创建 openapis.txt，每行一个 OpenAPI 路径：

http://localhost:3000/api-docs.json
http://localhost:8080/swagger.json
./my-api/openapi.yaml

批量启动命令

node scripts/multi-mss.js start
node scripts/multi-mss.js start --file ./my-openapis.txt  # 指定文件
node scripts/multi-mss.js stop   # 停止所有服务

功能特点

• 自动检查 RESTful 服务是否运行
• 只启动健康服务的 MCP Server
• 详细日志输出
• 重新运行可启动剩余服务
• 输出 OpenCode MCP 配置示例

手动配置 OpenCode MCP

MCP Server 启动后会输出 OpenCode MCP 配置，程序会自动检测配置文件位置并生成完整配置。

常见配置文件位置：

• ~/.opencode/mcp-config.json (Linux/Mac/Windows)

程序会检查上述路径，如果文件已存在会合并配置，如果不存在会提示用户创建。

配置输出示例：

📁 配置文件路径: C:\Users\xxx\.opencode\mcp-config.json

请将以下配置复制到上述配置文件中（可覆盖原有内容）:

{
  "mcpServers": {
    "localhost-3000": {
      "command": "node",
      "args": [
        "C:\\path\\to\\cli.js",
        "--transport",
        "stdio",
        "--openapi",
        "http://localhost:3000/api-docs.json"
      ]
    }
  }
}

---

📖 使用指南

单个服务启动

# STDIO 模式（适用于 AI 客户端集成）
pnpm mss --transport stdio --openapi https://api.example.com/swagger.json

# Streamable 模式
pnpm mss --transport streamable --port 3322 --openapi https://api.example.com/swagger.json

# SSE 模式
pnpm mss --transport sse --port 3322 --openapi https://api.example.com/swagger.json

命令行选项

--openapi, -o       OpenAPI 规范的 URL 或文件路径
--transport, -t     传输协议 (stdio|sse|streamable)
--port, -p          端口号
--endpoint, -e      自定义端点路径 (默认 sse:/sse, streamable:/mcp)
--base-url          覆盖 API 基础 URL（优先级最高）
--watch, -w         监控文件变化
--env               环境变量文件路径 (.env)

# 认证选项：
--auth-type         认证类型 (bearer)
--bearer-token      直接指定 Bearer Token
--bearer-env        从环境变量读取 Token
--custom-header     自定义请求头 "Key=Value" (可重复)

# 操作过滤选项：
--operation-filter-methods <method>   HTTP方法过滤 (可重复)
--operation-filter-paths <path>       路径过滤 (支持通配符, 可重复)

🔐 Bearer Token 认证

1. 直接指定 Token

pnpm mss --auth-type bearer --bearer-token "your-token" --openapi https://api.example.com/openapi.json --transport streamable

2. 环境变量配置

创建 .env 文件：

MCP_PORT=3322
MCP_TRANSPORT=streamable
MCP_OPENAPI_URL=https://api.example.com/openapi.json
MCP_BASE_URL=https://api.example.com/v1
MCP_AUTH_TYPE=bearer
API_TOKEN=your-bearer-token-here

🛠️ 开发

构建命令

# 创建离线安装包
node scripts/create-offline-package.js

# 清理构建产物
node scripts/clean.js

---

📄 许可证

MIT License

---