内容
<p>
<a href="https://github.com/mmadfox/swag2mcp/releases"><img src="https://img.shields.io/github/release/mmadfox/swag2mcp.svg" alt="最新版本"></a>
<a href="https://pkg.go.dev/github.com/mmadfox/swag2mcp?tab=doc"><img src="https://godoc.org/github.com/mmadfox/swag2mcp?status.svg" alt="GoDoc"></a>
<a href="https://github.com/mmadfox/swag2mcp/actions"><img src="https://github.com/mmadfox/swag2mcp/actions/workflows/test.yml/badge.svg?branch=main" alt="构建状态"></a>
<a href="https://coveralls.io/github/mmadfox/swag2mcp?branch=main"><img src="https://coveralls.io/repos/github/mmadfox/swag2mcp/badge.svg?branch=main&v=3" alt="覆盖率状态"></a>
<a href="https://mmadfox.github.io/swag2mcp"><img src="https://img.shields.io/badge/docs-mkdocs%20material-blue" alt="文档"></a>
</p>
> ⚠️ **进行中** — API 可能会更改，欢迎贡献。
**swag2mcp** 通过模型上下文协议（MCP）将 OpenAPI/Swagger/Postman API 规范与 LLM 代理连接起来。
- **16 种 MCP 工具**，用于发现、检查和调用 API
- **交互式 TUI 资源管理器**，支持全文搜索
- **零集成代码** — 只需指向您的规范并启动
---
## 目录
- [安装](#安装)
- [示例 LLM 查询](#示例-llm-查询)
- [文档](https://mmadfox.github.io/swag2mcp)
- [集成](#集成)
- [CLI 命令](#cli-命令)
- [模拟服务器](#模拟服务器)
- [配置示例](#配置示例)
- [许可证](#许可证)
---
## 安装
### 适用于 AI 代理
此路径适用于希望通过 AI 代理（Opencode、Cursor、Claude、Copilot、Crush 等）使用 swag2mcp 的用户。
**步骤 1 — 安装 `swag2mcp-cli` 技能**
该技能教您的代理所有命令、标志、配置格式和现实世界的例子。没有它，代理就不知道如何使用 swag2mcp。
您可以要求您的代理通过提供此链接来安装该技能：
**< 提示 >**
```bash
1. "从 https://github.com/mmadfox/swag2mcp/blob/main/.agents/skills/swag2mcp-cli/SKILL.md 添加 swag2mcp-cli 技能"
2. "从 https://github.com/mmadfox/swag2mcp/blob/main/.agents/skills/swag2mcp-format/SKILL.md 添加 swag2mcp-format 技能"
```
或者手动配置 — 参考您的 IDE 文档，了解如何添加自定义技能。
> **注意：**某些 IDE 需要在添加新技能后重启才能生效。
**步骤 2 — 选择设置方法**
**选项 A — 全自动（代理执行所有操作）**
**步骤 1** — 告诉您的代理：
**< 提示 >**
```bash
1. "加载 swag2mcp-cli 技能"
2. "加载 swag2mcp-format 技能"
3. "设置 swag2mcp"
```
代理将下载并安装 `swag2mcp`，然后创建一个带有预备规范的工作区。
> **注意：**如果 `swag2mcp` MCP 服务器已经运行，请重启它，以便代理可以获取新的工作区。否则，请继续执行下一步。
**步骤 2** — 配置您的 IDE（参见下面的[集成](#集成)）— IDE 将自动启动 `swag2mcp`。
**步骤 3** — 使用 MCP 工具发现和调用 API。
**选项 B — 您安装，代理连接**
```bash
# 从以下网址下载最新版本：
https://github.com/mmadfox/swag2mcp/releases/latest
```
然后配置您的 IDE（参见下面的[集成](#集成)）。
### 适用于人类
更喜欢命令行？以下是手动设置。
**选项 1 — 从 GitHub Releases 下载（推荐）**
1. 打开 [github.com/mmadfox/swag2mcp/releases/latest](https://github.com/mmadfox/swag2mcp/releases/latest)
2. 查找您所在系统的存档：
| 操作系统 | 架构 | 存档 |
|----|-------------|---------|
| Linux | x86_64 | `swag2mcp_<版本>_linux_amd64.tar.gz` |
| Linux | ARM64 | `swag2mcp_<版本>_linux_arm64.tar.gz` |
| macOS | Intel | `swag2mcp_<版本>_darwin_amd64.tar.gz` |
| macOS | Apple Silicon | `swag2mcp_<版本>_darwin_arm64.tar.gz` |
| Windows | x86_64 | `swag2mcp_<版本>_windows_amd64.zip` |
3. 下载并安装：
**Linux / macOS：**
```bash
tar -xzf swag2mcp_<版本>_<操作系统>_<架构>.tar.gz
sudo mv swag2mcp /usr/local/bin/
swag2mcp --version
```
**Windows (PowerShell)：**
```powershell
Expand-Archive swag2mcp_<版本>_windows_amd64.zip -DestinationPath .
move swag2mcp.exe C:\Windows\System32\
swag2mcp --version
```
4. （可选）重复模拟服务器 — 下载 `swag2mcp-mock_<版本>_<操作系统>_<架构>.tar.gz`
**选项 2 — 使用 Go 安装**
如果您已安装 Go：
```bash
go install github.com/mmadfox/swag2mcp/cmd/swag2mcp@latest
go install github.com/mmadfox/swag2mcp/cmd/swag2mcp-mock@latest
```
**安装后：**
```bash
swag2mcp init
通过 CLI：
swag2mcp add spec --yaml 'domain: binance
llm_title: Binance 市场数据 API
base_url: https://api.binance.com
collections:
- llm_title: 市场数据
location: https://raw.githubusercontent.com/mmadfox/swag2mcp/main/specs/binance.yaml
```
或手动编辑 `swag2mcp.yaml`:
```yaml
specs:
- domain: binance
llm_title: Binance 市场数据 API
base_url: https://api.binance.com
collections:
- llm_title: 市场数据
location: https://raw.githubusercontent.com/mmadfox/swag2mcp/main/specs/binance.yaml
```
```bash
# 4. 验证和更新
swag2mcp validate
swag2mcp update
# 5. 添加到您的 IDE
配置您的 IDE 以自动启动 swag2mcp（参见下面的[集成](#集成)）。IDE 将在需要时运行 `swag2mcp mcp`。
# 6. 交互式探索（可选）
swag2mcp run
```
---
## 示例 LLM 查询
在提问您的代理之前，请确保在您的 IDE 中连接了 swag2mcp MCP（参见上面的[集成](#集成)）。代理需要访问 MCP 工具来发现和调用 API。
建议始终从以下问题开始以验证 swag2mcp 是否已连接：
**< 提示 >**
```bash
"您支持哪些 MCP 工具？"
```
如果代理列出了 swag2mcp 工具（spec_list、search、invoke 等）— 所有功能正常。如果没有，请要求代理连接 swag2mcp：
**< 提示 >**
```bash
"加载 swag2mcp MCP"
```
设置完成后，尝试要求您的代理：
| < 提示 > | 会发生什么 |
|-------|-------------|
| "纽约的天气怎么样？" | `invoke` — 调用 Open-Meteo 预报 API |
| "当前的 BTC 价格是多少？" | `invoke` — 调用 Binance 报价 API |
| "给我讲个笑话。" | `invoke` — 调用 icanhazdadjoke API |
| "给我看皮卡丘。" | `invoke` — 调用 PokéAPI 按名称 |
| "瑞克·桑切斯是谁？" | `invoke` — 调用 Rick and Morty 角色 API |
| "北京的空气质量如何？" | `invoke` — 调用 Open-Meteo 空气质量 API |
| "葡萄牙附近的海浪有多高？" | `invoke` — 调用 Open-Meteo 海洋 API |
| "搜索关于狗的笑话。" | `invoke` — 调用 dadjoke 搜索端点 |
| "列出所有宝可梦。" | `invoke` — 调用 PokéAPI 列表端点 |
| "珠穆朗玛峰的海拔是多少？" | `invoke` — 调用 Open-Meteo 海拔 API |
---
### 代理技能
| 技能 | 描述 |
|-------|-------------|
| [swag2mcp-cli](.agents/skills/swag2mcp-cli/SKILL.md) | 完整的 CLI 参考 — 所有命令、标志、配置格式和现实世界的例子 |
| [swag2mcp-format](https://github.com/mmadfox/skills#swag2mcp-format) | 将 MCP 工具响应格式化为人类可读的 Markdown |
---
## 集成
swag2mcp 使用模型上下文协议（MCP）并与任何兼容的 MCP 客户端一起工作。所有设置（标签、传输、身份验证）都在 `swag2mcp.yaml` 中配置 — 请参阅[示例](examples/)。
> **注意：**如果您在自定义路径初始化工作区（例如 `swag2mcp init ./my-project`），则必须在启动 MCP 服务器时指定路径：`swag2mcp mcp ./my-project`。IDE 配置还必须使用到配置文件全路径。
### 本地（stdio）— 代理在同一台机器上
| 客户端 | 配置文件 | 内容 |
|--------|-------------|---------|
| **OpenCode** | `opencode.json` | `{"mcp":{"swag2mcp":{"type":"local","command":["swag2mcp","mcp"]}}}` |
| **Cursor** | `.cursor/mcp.json` | `{"mcpServers":{"swag2mcp":{"command":"swag2mcp","args":["mcp"]}}}` |
| **Claude Desktop** | `claude_desktop_config.json` | `{"mcpServers":{"swag2mcp":{"command":"swag2mcp","args":["mcp"]}}}` |
| **VS Code** | `.vscode/mcp.json` | `{"servers":{"swag2mcp":{"type":"stdio","command":"swag2mcp","args":["mcp"]}}}` |
| **Crush** | `crush.json` | `{"mcp":{"swag2mcp":{"type":"stdio","command":"swag2mcp","args":["mcp"]}}}` |
### 远程（HTTP）— 代理在云/不同机器上
使用 HTTP 传输启动服务器：
```bash
swag2mcp mcp --transport streamable-http --http-addr :8080 --auth-token my-secret
```
或在 `swag2mcp.yaml` 中配置：
```yaml
mcp:
transport: streamable-http
addr: ":8080"
path: "/mcp"
auth_token: $(MCP_AUTH_TOKEN)
```
| 客户端 | 配置文件 | 内容 |
|--------|-------------|---------|
| **OpenCode** | `opencode.json` | `{"mcp":{"swag2mcp":{"type":"remote","url":"http://localhost:8080/mcp","headers":{"Authorization":"Bearer ${MCP_AUTH_TOKEN}"}}}}` |
| **VS Code** | `.vscode/mcp.json` | `{"servers":{"swag2mcp":{"type":"http","url":"http://localhost:8080/mcp"}}}` |
> **健康检查**（无需 MCP 握手）：
> ```bash
> curl http://localhost:8080/health
> # → {"status":"ok","version":"v1.1.3"}
> ```
---
## CLI 命令
所有接受 `[path]` 的命令都使用相同的路径解析：
```
swag2mcp <command> → ~/.swag2mcp/
swag2mcp <command> ./ → {cwd}/.swag2mcp/
swag2mcp <command> path/to → {cwd}/path/to/.swag2mcp/
```
| 命令 | 描述 |
|---------|-------------|
| `init` | 初始化工作区和配置 |
| `add spec` / `add collection` | 添加规范或集合 |
| `delete spec` / `delete collection` | 删除规范或集合 |
| `ls` | 列出规范和集合 |
| `run` | 交互式 TUI API 资源管理器 |
| `validate` | 验证配置 |
| `clean` | 删除缓存和响应 |
| `update` | 验证、清除缓存、重新缓存所有规范 |
| `mcp` | 启动 MCP 服务器 |
| `version` / `--version` | 打印版本 |
| `info` | 显示运行时信息 |
| `import` | 导入规范文件 |
| `export` | 将工作区导出为 ZIP |
请参阅 [docs/guide.md](docs/guide.md) 以获取完整参考。
---
## 模拟服务器
**swag2mcp-mock** 是一个内置的模拟服务器，根据您的 OpenAPI/Swagger 模式生成随机 API 响应 — 无需真实后端。
在开发、测试或真实 API 不可用时使用。
```bash
# 安装
go install github.com/mmadfox/swag2mcp/cmd/swag2mcp-mock@latest
# 启动模拟服务器（读取与 swag2mcp 相同的配置）
swag2mcp-mock
# 将 swag2mcp 添加到您的 IDE（参见上面的集成）— 调用将使用模拟 URL
```
要在您的配置中启用，请添加：
```yaml
mock_enabled: true
specs:
- domain: meteo
collections:
- location: specs/meteo/forecast.yml
base_mock_url: localhost:8080
```
---
## 配置示例
浏览现成的配置示例：
| 类别 | 示例 | 描述 |
|----------|---------|-------------|
| **基础** | [minimal-config](examples/minimal-config) | 最小配置 — 一个规范，一个集合，无身份验证 |
| | [full-config](examples/full-config) | 具有所有功能的完整配置 |
| **身份验证** | [no-auth](examples/auth/no-auth) | 无身份验证 |
| | [basic-auth](examples/auth/basic-auth) | HTTP 基本身份验证 |
| | [bearer-auth](examples/auth/bearer-auth) | Bearer Token 身份验证 |
| | [digest-auth](examples/auth/digest-auth) | HTTP 摘要身份验证 |
| | [oauth2-client-credentials](examples/auth/oauth2-client-credentials) | OAuth2 客户端凭证授予 |
| | [oauth2-password](examples/auth/oauth2-password) | OAuth2 密码授予 |
| | [api-key-header](examples/auth/api-key-header) | HTTP 头中的 API 密钥 |
| | [api-key-query](examples/auth/api-key-query) | 查询参数中的 API 密钥 |
| | [script-auth](examples/auth/script-auth) | 基于脚本的身份验证 |
| | [hmac-auth](examples/auth/hmac-auth) | HMAC-SHA256 身份验证 |
| **规范功能** | [llm-metadata](examples/spec-features/llm-metadata) | LLM 标题和说明 |
| | [disable-spec](examples/spec-features/disable-spec) | 禁用规范和集合 |
| | [tags-filtering](examples/spec-features/tags-filtering) | 基于标签的过滤，带有 `--tags` |
| | [custom-headers](examples/spec-features/custom-headers) | 自定义 HTTP 头 |
| | [multiple-collections](examples/spec-features/multiple-collections) | 每个规范的多个集合 |
| | [collection-override](examples/spec-features/collection-override) | 集合级覆盖 |
| | [http-client-config](examples/spec-features/http-client-config) | HTTP 客户端配置（头、cookie、超时、重定向） |
| | [proxy-config](examples/spec-features/proxy-config) | 代理配置（SOCKS5、HTTP、HTTPS、绕过） |
| | [random-client](examples/spec-features/random-client) | 随机类似浏览器的头 |
| **MCP 传输** | [stdio](examples/mcp-transport/stdio) | 默认_stdio 传输 |
| | [sse](examples/mcp-transport/sse) | 带有 HTTP 和 bearer token 身份验证的 SSE 传输 |
| | [streamable-http](examples/mcp-transport/streamable-http) | 带有 HTTP 和 bearer token 身份验证的 Streamable HTTP 传输 |
| **模拟服务器** | [mock-server](examples/mock-server) | 模拟服务器，带有随机数据生成和身份验证模拟 |
---
## 许可证
MIT
