AI导哈

智能Swagger端点搜索服务

MCP Swagger Server是一个双模式服务器，能够加载OpenAPI/Swagger规范并提供智能端点搜索功能，适用于开发辅助和自动化流程。

  • by genideas-labs
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 genideas-labs/mcp-swagger

使用说明

MCP Swagger服务器

版本： 1.2.0 最后更新时间： 2026-01-18

安装指南（快速链接）

光标： docs/guides/cursor-mcp-setup.md
VS代码： docs/guides/vscode-mcp-setup.md
所有客户： docs/guides/clients.md

1.概述

该项目是一个双模服务器，从文档页面加载OpenAPI/Swagger规范，并提供智能端点搜索。它可以作为标准运行 MCP（元编程副驾驶）服务器 或作为a 独立HTTP服务器.

在MCP模式下，它公开了与开发人员助手和自动化管道集成的工具。在HTTP模式下，它提供REST端点用于加载规范和搜索端点。

2.核心特征

  • F1：加载OpenAPI规范： 获取Swagger/OpenAPI文档URL，解析规范URL，将其打包，并将简化的规范存储在多规范存储中(specs/).
  • F2：智能端点搜索：
    • 预过滤： 匹配路径、摘要、操作ID、模式名称和模式属性。
    • 法学硕士排名： 使用Gemini(gemini-2.5-flash)对候选人进行排名。
    • 自适应响应： 对于不明确的查询，返回单个最佳匹配或最多5个结果。
    • 架构丰富： 返回完整的端点操作及其引用的架构。
    • 多规格感知： 结果包括 spec 加载多个规格时的名称。
  • F3：双模式操作：
    • MCP服务器模式： 提供 load_spec 和 search_endpoints 工具。
    • HTTP服务器模式： 作为独立的REST API服务器运行。

3.入门

先决条件

  • Node.js（建议使用v18或更高版本）
  • npm

安装

  1. 克隆存储库：
    git clone https://github.com/genideas-labs/mcp-swagger.git
cd mcp-swagger
  2. 安装依赖项：
    npm install

配置

创建一个 .env 文件在项目根目录中，并添加您的Gemini API密钥（请向您的公司管理员索取密钥）：

GEMINI_API_KEY="YOUR_API_KEY_HERE"

可选：

PORT=3000
MCP_SWAGGER_SPEC_DIR="/abs/path/to/specs"
MCP_SWAGGER_SPEC_PATH="/abs/path/to/spec.json"
MCP_SWAGGER_TEST_MODE=1
MCP_SWAGGER_SEARCH_SCOPE=primary

对于具有专用env文件的烟雾测试：

# .env.development
GEMINI_API_KEY="YOUR_API_KEY_HERE"

4.使用方法

运行服务器

  • 运行HTTP开发服务器（自动重新加载）：

    npm run dev

    服务器运行在 http://localhost:3000.

  • 运行HTTP生产服务器：

    npm run start:http

  • 运行MCP服务器：

    npm start
# or
npm run start:mcp

  • 仅构建：

    npm run build

  • 加载配置的Swagger源：

    npm run spec:load

  • 使用以下命令运行脚本 .env.development:

    npm run dev:script -- testing/smoke/real-llm-smoke.cjs

MCP工具参考

  • load_spec

    • 输入： { "docsUrl": "https://...", "name"?: "spec-name", "setActive"?: true }
    • 输出：文本确认或错误

  • search_endpoints

    • 输入： { "query": "...", "spec"?: "spec-name" | ["spec-a","spec-b"], "all"?: true, "scope"?: "primary|fallback|all", "priorityDepth"?: 2 }
    • 输出：字符串化JSON（单个对象或数组）

  • 列表_规格

    • 输入： {}
    • 输出：已加载规格、主订单和活动规格的列表

HTTP API参考

  • 加载API规范（单个）：

    curl -X POST -H "Content-Type: application/json" \
  -d '{"docsUrl": "https://oq-api.fly.dev/docs", "name": "oq-api"}' \
  http://localhost:3000/api/v1/spec/load-from-url

    预期响应：

    {"message":"Specification loaded and saved successfully.","specName":"oq-api"}

  • 加载API规范（多个）：

    curl -X POST -H "Content-Type: application/json" \
  -d @swagger-sources.json \
  http://localhost:3000/api/v1/spec/load-many

  • 列出加载的规格：

    curl http://localhost:3000/api/v1/specs

  • 获取缓存规范（活动或按名称）：

    curl http://localhost:3000/api/v1/spec
curl http://localhost:3000/api/v1/spec?name=oq-payment

  • 智能搜索（模糊查询，多规格）：

    curl -G "http://localhost:3000/api/v1/endpoints/search" \
  --data-urlencode "q=health" \
  --data-urlencode "spec=oq-api,oq-payment"
# or --data-urlencode "all=true"

    示例响应：

    [
  {
    "spec": "oq-api",
    "endpoint": {
      "summary": "Public Calculate Calories",
      "operationId": "public_calculate_calories_public_calories_post"
    },
    "schemas": { "...": "..." }
  }
]

  • 智能搜索（特定查询）：

    curl -G "http://localhost:3000/api/v1/endpoints/search" \
  --data-urlencode "q=Update Current User" \
  --data-urlencode "spec=oq-api"

    示例响应：

    {
  "spec": "oq-api",
  "endpoint": {
    "summary": "Update Current User",
    "operationId": "update_current_user_auth_me_put"
  },
  "schemas": { "...": "..." }
}

  • Gemini测试端点（调试）：

    curl http://localhost:3000/api/v1/test/gemini

5.搜索行为（详细信息）

  • 查询与端点元数据和模式名称/属性不区分大小写地匹配。
  • Gemini返回一个最佳匹配（小候选集）或最多5个匹配。
  • 响应包括完整的OpenAPI操作对象和所有引用的模式。
  • 每个结果包括 spec 当使用多规格时。
  • 搜索范围支持 primary, fallback，或 all （通过查询或 MCP_SWAGGER_SEARCH_SCOPE).

6.规格储存

  • 规格存储在 specs/ 带着一个 index.json 注册表。
  • 存储的规格减少到 info, paths，以及 components.schemas.
  • 用以下命令覆盖规范目录 MCP_SWAGGER_SPEC_DIR.
  • 第一个主要规范镜像到 src/spec.json （用覆盖 MCP_SWAGGER_SPEC_PATH).

7.Swagger源（多规格指南）

  1. 编辑 swagger-sources.json 并添加条目和优先级顺序：
    {
  "primary": ["oq-api", "oq-payment"],
  "specs": [
    { "name": "oq-api", "docsUrl": "https://oq-api.fly.dev/docs" },
    { "name": "oq-payment", "docsUrl": "https://oq-payment.fly.dev/docs" }
  ]
}
  2. 加载它们：
    npm run spec:load
  3. 按名称搜索：
    curl -G "http://localhost:3000/api/v1/endpoints/search" \
  --data-urlencode "q=health" \
  --data-urlencode "spec=oq-payment"
  4. 优先级搜索（主->回退）：
    curl -G "http://localhost:3000/api/v1/endpoints/search" \
  --data-urlencode "q=health" \
  --data-urlencode "scope=fallback" \
  --data-urlencode "depth=2"

8.测试

npm test

确定性测试在以下情况下使用存根LLM和直接规范获取 MCP_SWAGGER_TEST_MODE=1.

真实LLM烟雾测试（要求 .env.development 随着 GEMINI_API_KEY):

npm run test:smoke

9.客户端设置

看 docs/guides/clients.md 用于MCP客户端设置（游标、VS代码、Codex CLI、Claude CLI、Gemini CLI）。 仅光标快速指南： docs/guides/cursor-mcp-setup.md. VS Code快速指南： docs/guides/vscode-mcp-setup.md.

如何提问（总结）：

  • 在IDE聊天中用自然语言提问。（示例：“登录API在哪里？”）
  • 如果您有多个规格，请提及服务/规格名称以确保准确性。
  • 如果你需要模式，可以说“包括请求/响应模式”。

它是如何工作的（摘要）：

  • 首先加载Swagger文档。
  • IDE调用MCP search_endpoints.
  • 服务器使用LLM对候选人进行预筛选和排名。
  • 返回最佳端点和引用的模式。

10.限制

  • 规范发现针对Swagger UI进行了调整，可能不适用于其他文档框架。
  • 本地规范缓存之外没有身份验证、速率限制或持久存储。

11.贡献

欢迎投稿！请打开问题以报告错误或请求功能。对于代码更改，请使用标准的GitHub工作流（fork->branch->PR）。

12.赞助商

如果你喜欢这个项目，请考虑赞助，以帮助支持其持续开发和维护。

相关 MCP