你写 OpenAPI 文档           →    SwaggerWatcher 自动读取
                                  ↓
后端新增/修改接口            →    轮询检测到变更 + 增量 Diff
                                  ↓
AI Agent 自动获得新工具      ←    热重载通知

pip install git+https://github.com/huixiaheyu/swagger-mcp.git

git clone https://github.com/huixiaheyu/swagger-mcp.git
cd swagger-mcp
pip install -e .

servers:
  - name: petstore
    openapi_url: "https://petstore3.swagger.io/api/v3/openapi.json"
    base_url: "https://petstore3.swagger.io/api/v3"
    poll_interval: 300  # 秒

swagger-mcp config.yaml
# 或通过环境变量
export SWAGGER_MCP_CONFIG=config.yaml
swagger-mcp

swagger-mcp config.yaml --list-tags

servers:
  - name: my-api                # 服务名（工具名前缀）
    openapi_url: "https://..."  # OpenAPI 文档 URL
    # openapi_file: "./spec.yaml"  # 或本地文件路径
    base_url: "https://..."     # API 调用基础 URL
    mode: dynamic               # static（默认）| dynamic
    # --- 过滤选项（全部可选） ---
    max_tools: 150              # 自动选接口最多的标签组，不超过此数
    # include_tags:             # 白名单
    #   - sys-user
    # exclude_tags:             # 黑名单
    #   - gen-controller
    spec_headers:               # 拉取文档时的认证头
      Authorization: "Bearer xxx"
    api_headers:                # 每次 API 调用自动注入
      api-key: "sk-xxx"
      X-Tenant-Id: "tenant-01"
    poll_interval: 300          # 轮询间隔（秒），0 关闭

servers:
  - name: ruoyi
    openapi_url: "https://..."
    mode: dynamic

你：查一下 admin 这个用户
AI：
  1. 看到当前工具不覆盖用户管理模块
  2. 调用 _list_groups() → sys-user-controller(14), auth-controller(7)
  3. 调用 _activate_groups(["sys-user-controller"])
  4. 收到 tool_list_changed → 工具列表刷新
  5. 调用 ruoyi_list({...}) → 查到用户信息

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "python",
      "args": ["-m", "swagger_mcp", "/path/to/config.yaml"]
    }
  }
}

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "swagger_mcp", "/path/to/config.yaml"]
    }
  }
}

python -m swagger_mcp /path/to/config.yaml

┌──────────┐     ┌──────────────────────────────────────┐
│   MCP    │     │          SwaggerWatcher              │
│  Client  │────▶│                                      │
│ (Cursor, │     │  ┌─────────┐  ┌──────────┐          │
│  AI IDE) │     │  │  Spec   │──▶  Tools   │          │
│          │     │  │ Loader  │  │ Registry │          │
│          │     │  │(URL/文件)│  │($ref 展开)│         │
│          │     │  └────┬────┘  └────┬─────┘          │
│          │     │       │            │                 │
│          │     │  ┌────▼────────────▼──────┐          │
│          │     │  │    Change Detector      │          │
│          │     │  │  (SHA-256 哈希 + Diff)   │          │
│          │     │  └───────────┬────────────┘          │
│          │     │              │ 热重载通知             │
│          │     │  ┌───────────▼──────────┐            │
│          │     │  │     API Proxy        │            │
│          │◀────│  │  (httpx → 后端)      │            │
└──────────┘     └──────────────────────────────────────┘

<服务名>_<operationId>
<服务名>_<方法>__<路径分段>

[INFO] + added tools: petstore_createUser, petstore_deleteOrder
[INFO] - removed tools: petstore_deprecatedMethod
[INFO] ~ changed tools: petstore_getPetById

git clone https://github.com/huixiaheyu/swagger-mcp.git
cd swagger-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# 端到端测试
python test_e2e.py

swagger-mcp/
├── pyproject.toml              # 项目元信息 + 依赖
├── config.yaml                 # 默认配置示例
├── config.local.yaml           # 本地开发配置（不进 Git）
├── mcp-config.json             # WorkBuddy 集成模板
├── test_e2e.py                 # 端到端测试
├── README.md                   # 本文档
├── README.en.md                # 英文文档
└── src/swagger_mcp/
    ├── __init__.py
    ├── __main__.py             # CLI 入口
    ├── server.py               # MCP 服务器 + 轮询
    ├── loader.py               # 文档加载器
    ├── registry.py             # OpenAPI → MCP 工具 + Diff
    └── proxy.py                # HTTP 代理