convez.ai
MCP ServerIntegração & APIsIntermediário
yangshuaipeng126

Swagger MCP Server

yangshuaipeng126/swagger-mcp-server

Converta Swagger/OpenAPI em ferramentas IA chamáveis com debug e autenticação

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que transforma qualquer documentação Swagger/OpenAPI em ferramentas chamáveis por IA. Suporta Swagger 2.0 e OpenAPI 3.0, com recursos como busca inteligente de endpoints, debug de APIs, geração de cURL e exploração de DTO. Inclui autenticação automática, injeção de tokens e cache de documentos.

Instalação

$npx convez-ai yangshuaipeng126/swagger-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integração de APIs REST em agentes Claude via MCP
  • Debug e teste de endpoints diretamente no fluxo de trabalho IA
  • Exploração automática de esquemas e DTOs de documentações Swagger

Veredito

Solução robusta e bem-pensada para expor APIs REST como ferramentas MCP. O suporte automático a autenticação, caching inteligente e padronização entre Swagger 2.0 e OpenAPI 3.0 torna a integração prática. Recomendado para equipes que querem dar aos seus agentes acesso direto a APIs documentadas.

README

A tradução para o português deste README ainda está na fila.

Swagger MCP Server

将任意 Swagger/OpenAPI 文档转化为 AI 可调用的 MCP 工具集,支持文档查询、接口调试、cURL 生成和 DTO 字段探查。

兼容 Swagger 2.0 和 OpenAPI 3.0,自动标准化文档格式。


快速开始

安装与构建

npm install
npm run build

配置 MCP

编辑 MCP 配置文件(Claude Desktop、Cursor、Windsurf 等):

{
  "mcpServers": {
    "swagger": {
      "command": "node",
      "args": [
        "/path/to/swagger-mcp-server/build/index.js",
        "http://your-api-host/v2/api-docs"
      ]
    }
  }
}

配置参数

格式示例说明
Swagger 文档地址http://localhost:8090/v3/api-docs直接填入 URL,注册为 default 服务
命名服务order=http://localhost:8091/v3/api-docsname=url 格式,支持多服务
Cookie 认证cookie=token=abc123注入 Cookie,适用于已有 Token 的场景
账号密码auth=admin:123456预设凭证,接口返回 401 时会自动提示 AI 登录
自动登录auth=/auth/login:admin:123456指定登录路径,401 时自动完成登录并重试

多参数组合示例:

{
  "mcpServers": {
    "swagger": {
      "command": "node",
      "args": [
        "/path/to/swagger-mcp-server/build/index.js",
        "user=http://api.example.com/v2/api-docs",
        "order=http://api.example.com/order/v3/api-docs",
        "cookie=token=abc123;uid=456",
        "auth=/api/login:admin:123456"
      ]
    }
  }
}

工具列表

工具说明必填参数
list_services列出所有已配置的服务—
refresh_docs强制刷新文档缓存service_name(可选)
list_endpoints列出所有接口摘要service_name(可选)
search_apis按关键词搜索接口(加权匹配)query
get_endpoint_details获取接口完整定义(参数、请求体、响应)path, method
get_dto_definition获取 DTO 的完整字段定义(含嵌套展开)dto_name
list_all_dtos列出所有可用 DTO 及其字段摘要—
debug_endpoint发送真实 HTTP 请求调试接口path, method
generate_curl生成 cURL 命令path, method

工具详解

search_apis — 智能搜索

支持多关键词加权匹配:路径匹配权重最高,其次是摘要,最后是描述。按评分降序排列,返回 Top 20。

> 搜索 "创建用户"
→ POST /user/create  (路径命中 + 摘要命中 = 高分)
→ POST /account/add  (仅描述命中 = 低分)

get_endpoint_details — 接口详情

返回接口的完整结构:

  • parameters — 路径参数、查询参数的名称、类型、是否必填、描述
  • requestBody — 请求体的完整 JSON Schema
  • requestBodyFields — 请求体字段的人类可读描述(含嵌套结构)
  • responses — 各状态码的响应结构及字段描述

get_dto_definition — DTO 字段探查

递归展开 DTO 的所有字段,包括嵌套对象和数组。输出:

  • description — 结构化字段树(含必填标记、类型、注释)
  • typescriptDefinition — 自动生成的 TypeScript 接口定义
  • rawSchema — 完整的解析后 JSON Schema

debug_endpoint — 接口调试

发送真实 HTTP 请求,支持:

  • 自动 Token 注入 — 如果之前登录过,自动携带缓存的 Token
  • 自动 Cookie 注入 — 使用配置中的 Cookie
  • 参数自动补齐 — POST/PUT/PATCH 请求的必填字段会用默认值填充,避免 400
  • 401 自动登录 — 如果配置了 auth=/path:user:pass,遇到 401 会自动登录并重试;如果仅配置了 auth=user:pass,会提示 AI 调用登录接口
  • Token 自动捕获 — 从响应的 token/accessToken/access_token 或 Authorization 头自动缓存 Token
  • localhost 纠错 — Node 17+ 环境下自动将 localhost 切换为 127.0.0.1

generate_curl — cURL 生成

根据接口定义生成标准的 cURL 命令,自动拼接 Base URL、Headers 和 Body。


DTO 探查工作流

推荐的两步流程,快速了解接口的请求/响应结构:

1. list_all_dtos           → 浏览可用的 DTO 列表,找到目标
2. get_dto_definition      → 展开某个 DTO 的完整字段定义
3. get_endpoint_details    → 查看接口使用的具体 DTO 及参数

架构与缓存

  • 文档缓存 — 首次加载后缓存 5 分钟,过期自动刷新,refresh_docs 可强制刷新
  • Token 缓存 — 登录后 Token 常驻内存,后续请求自动注入
  • Swagger 2.0 兼容 — 获取文档时自动标准化为 OpenAPI 3.0 格式(definitions → components.schemas、in: body → requestBody、host+basePath → servers)

项目结构

src/
├── index.ts              # 服务入口
├── services/
│   └── loader.ts         # 文档加载、缓存、标准化、认证管理
├── tools/
│   └── index.ts          # MCP 工具实现
├── utils/
│   └── schema.ts         # $ref 解析、JSON Schema → TS 类型生成
└── types/
    └── swagger.ts        # 类型定义

常见问题

Q: 本地服务连接报错 ECONNREFUSED ::1:8090?

A: 已内置自动纠错,会切换到 127.0.0.1 重试,无需手动处理。

Q: list_all_dtos 返回空列表?

A: 可能你的 Swagger 是 2.0 版本(/v2/api-docs)。V2 已支持 Swagger 2.0 的 definitions 自动兼容,确保使用最新版本。

Q: 登录接口的 Token 不在 data.token 中?

A: 支持自动识别 token、accessToken、access_token 及 Authorization 响应头。如果结构特殊,可修改 src/tools/index.ts 中 debug_endpoint 的 Token 提取逻辑。

Q: 请求一直返回参数错误?

A: 使用 get_endpoint_details 确认参数结构,或直接用 debug_endpoint 让 MCP 自动补齐必填字段。

Ver o original no GitHub

Bom para

Relacionados