AI导哈

Swagger MCP工具生成器

Swagger-mcp是一个工具，能够读取Swagger 2.0或OpenAPI 3.0规范，并动态生成MCP工具，用于LLM驱动的API交互。

  • by danishjsheikh
  • Go
  • 本地部署
  • 83 星标
  • 更新于
在 GitHub 查看 danishjsheikh/swagger-mcp

使用说明

马大伟

概述

swagger-mcp 是一种读取Swagger 2.0或OpenAPI 3.0规范并在运行时动态生成MCP工具的工具-每个API端点一个工具。任何MCP客户端都可以使用这些工具进行LLM驱动的API交互。

支持的规范格式：

  • Swagger 2.0 (swagger: "2.0")--路径/查询/标头参数和 in: body 请求机构
  • OpenAPI 3.0 (openapi: "3.0.x")--路径/查询/标头参数和 requestBody 与内联或 $ref 模式

从架构中读取必填和可选字段 required 数组，并在生成的工具定义中得到尊重。

📽️ 演示视频

查看演示视频，展示项目的实际情况：

🙌 支持

如果你觉得这个项目很有价值，请支持我 领英 通过：

  • 👍 喜欢并分享我们的演示帖子
  • 💬 在评论中留下你的想法和反馈
  • 🔗 与我联系以获取未来的更新

您在LinkedIn上的支持将帮助我接触到更多的人，并改进项目！

先决条件

使用 swagger-mcp，确保您具有以下依赖关系：

  1. LLM模型API密钥/本地LLM：需要访问OpenAI、Claude或Ollama模型。
  2. 任何MCP客户端：（已使用 mark3labs-mcphost)

安装和设置

go install github.com/danishjsheikh/swagger-mcp@latest

运行配置

标准模式（默认）

swagger-mcp --specUrl=https://your_swagger_api_docs.json

SSE模式

swagger-mcp --specUrl=https://your_swagger_api_docs.json --sse --sseAddr=:8080

流式HTTP模式

swagger-mcp --specUrl=https://your_swagger_api_docs.json --http --httpAddr=:8080

所有旗帜

标志 描述
--specUrl URL或 file:// Swagger/OpenAPI JSON规范的路径（必需）
--baseUrl 覆盖API请求的基本URL
--sse 以SSE模式而不是stdio运行
--sseAddr SSE监听地址， :Port 或 IP:Port
--sseUrl SSE基本URL（自动派生自 --sseAddr 如果省略）
--sseHeaders 从SSE转发到API的逗号分隔请求头（例如。 Authorization,X-Tenant)
--http 以StreamableHTTP模式而不是stdio运行
--httpAddr 流式HTTP侦听地址， :Port 或 IP:Port
--httpPath StreamableHTTP端点路径（默认 /mcp)
--httpHeaders 用逗号分隔的请求头从HTTP转发到API
--includePaths 要包含的逗号分隔路径或正则表达式模式
--excludePaths 要排除的逗号分隔路径或正则表达式模式
--includeMethods 包含逗号分隔的HTTP方法（例如。 GET,POST)
--excludeMethods 要排除的逗号分隔的HTTP方法
--security 身份验证类型： basic, bearer，或 apiKey
--basicAuth 中的基本身份验证凭据 user:password 格式
--bearerAuth 持有者代币 Authorization 头球
--apiKeyAuth API密钥： passAs:name=value — passAs 是 header, query，或 cookie；多个条目逗号分隔（例如。 header:token=abc,query:user=foo)
--headers 每个请求都有额外的静态标头， name1=value1,name2=value2

Xquik OpenAPI示例

Xquik为其X/Twitter自动化API发布了一个远程OpenAPI文档。 因为它使用API密钥头，所以使用 --security=apiKey 和 --apiKeyAuth:

export XQUIK_API_KEY="your-xquik-api-key"

swagger-mcp \
  --specUrl=https://xquik.com/openapi.json \
  --baseUrl=https://xquik.com \
  --security=apiKey \
  --apiKeyAuth=header:x-api-key=$XQUIK_API_KEY

MCP客户端配置中可以使用相同的参数：

{
  "mcpServers": {
    "xquik": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=https://xquik.com/openapi.json",
        "--baseUrl=https://xquik.com",
        "--security=apiKey",
        "--apiKeyAuth=header:x-api-key=<XQUIK_API_KEY>"
      ]
    }
  }
}

MCP配置

与整合 mcphost，包括以下配置 .mcp.json:

{
    "mcpServers": {
        "swagger_loader": {
            "command": "swagger-mcp",
            "args": ["--specUrl=<swagger/doc.json_url>"]
        }
    }
}

使用承载身份验证和路径过滤：

{
    "mcpServers": {
        "swagger_loader": {
            "command": "swagger-mcp",
            "args": [
                "--specUrl=https://api.example.com/openapi.json",
                "--security=bearer",
                "--bearerAuth=your-token-here",
                "--includeMethods=GET,POST"
            ]
        }
    }
}

请求身体支持

Swagger 2.0和OpenAPI 3.0都支持请求体：

  • Swagger 2.0: parameters 与 in: body 和一个 $ref 或内联模式 definitions
  • OpenAPI 3.0: requestBody.content.<media-type>.schema --已解决 components/schemas 如果A $ref，如果是对象架构，则内联使用

架构中列出的字段 required 阵列在MCP工具中按要求标记。所有其他字段都是可选的，如果没有提供，则从请求中省略。

演示流程

  1. 一些后端：

    go install github.com/danishjsheikh/go-backend-demo@latest 
go-backend-demo

  2. Ollama

    ollama run llama3.2

  3. MCP客户端

    go install github.com/mark3labs/mcphost@latest
mcphost -m ollama:llama3.2 --config <.mcp.json_file_path>

流程图

🛠️ 需要帮助

我正在处理 改进工具定义 增强：
✅ 更好的错误处理 以获得更准确的响应
✅ LLM行为控制 以确保其依赖 仅针对API响应 并且不使用自己的内存
✅ 预防幻觉 和 随机数据生成 通过从API强制执行严格的数据检索

如果您对改进这些方面有见解或建议，请通过以下方式做出贡献：

  • 分享您的经验 具有类似的实现
  • 建议修改 工具定义
  • 提供反馈 关于当前的局限性

您的意见对于使此工具更加可靠和有效将是无价的！ 🚀

相关 MCP