AI导哈

Swagger MCP 桥接器

Swagger MCP Bridge 是一个将 SpringDoc 驱动的 Spring Boot API 转换为生产级 MCP 网关的工具，支持 API 发现、验证、响应整形和多步骤工作流编排。

  • by Neo1228
  • Java
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 Neo1228/spring-boot-starter-swagger-mcp

使用说明

Swagger MCP桥

将任何SpringDoc驱动的SpringBoot API转换为可用于生产的MCP网关。

Swagger MCP Bridge可发现您的OpenAPI操作，将其发布为安全的MCP工具，并为API发现、验证、响应成形和多步骤工作流编排添加智能网关层。

命名和坐标

该存储库有意将公共表面分开，以便每个表面在自己的生态系统中自然读取：

表面 名称
项目/文档 Swagger MCP桥
Maven依赖关系 io.github.neo1228:openapi-mcp-spring-boot-starter
官方MCP注册服务器 io.github.Neo1228/swagger-mcp-bridge
可运行的示例图像 ghcr.io/neo1228/swagger-mcp-bridge-example:<version>
Spring配置前缀 swagger.mcp.*

项目名称保留了已建立的桥接品牌，而Maven工件使用Java消费者所期望的中性OpenAPI/Spring Boot启动器坐标。注册表服务器和GHCR映像标识MCP目录使用的打包可运行示例。

为什么选择Swagger MCP桥

大多数MCP API桥接器在薄的工具包装器处停止。Swagger MCP Bridge被设计为运行时网关：它将现有的Spring控制器暴露给LLM客户端，同时保留合约、护栏和操作可见性。

所得

  • 从正在运行的Spring应用程序中零发现SpringDoc OpenAPI操作的样板
  • 发现API操作的MCP工具自动注册
  • 智能上下文网关工具： meta_get_api_capabilities, meta_validate_api_call, meta_discover_api_tools, meta_describe_api_tool, meta_list_api_groups, meta_plan_api_workflow, meta_invoke_api_workflow, meta_invoke_api_by_intent
  • API目录和工作流程层，用于能力检查、飞行前验证、分组探索、干式运行计划和顺序执行
  • 从OpenAPI约束生成的丰富MCP输入模式：必填字段、枚举、数字/字符串/对象限制、示例和弃用提示
  • 使用JSONPath投影和摘要控件进行响应整形
  • 执行护栏：必需的参数验证、未解析的路径模板保护和安全 _headers 过滤
  • 具有稳定代码的结构化MCP错误响应，例如 INVALID_ARGUMENT, SECURITY_DENIED, WORKFLOW_ERROR，以及 HTTP_DISPATCH_FAILED
  • Java 17字节码，在Java 17、21和25上具有CI覆盖率
  • Java 21+运行时上的可选虚拟线程HTTP调度，Java 17上的自动平台线程回退
  • 危险作业生产护栏： _confirm、阻塞路径、角色检查、审核日志和结构化客户端错误

建筑

graph TD
    User([User / LLM Client]) <--> MCP[MCP Client / Claude Desktop]
    MCP <--> Bridge[Swagger MCP Bridge /starter/]
    Bridge --> Catalog[Operation Catalog /groups + contracts/]
    Bridge --> Workflow[Workflow Orchestrator /plan + dry-run + execute/]
    Bridge <--> Docs[SpringDoc OpenAPI /v3/api-docs]
    Bridge <--> API[Your Spring Controller /hello]

快速开始

1.创建Spring Boot应用程序

用途：

  • Java 17+
  • 弹簧靴3.5.x
  • 春季网络

2.添加依赖项

Gradle(build.gradle.kts):

plugins {
    id("org.springframework.boot") version "3.5.14"
    id("io.spring.dependency-management") version "1.1.7"
    java
}

java {
    sourceCompatibility = JavaVersion.VERSION_17
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springdoc:springdoc-openapi-starter-webmvc-api:2.8.17")
    implementation("io.github.neo1228:openapi-mcp-spring-boot-starter:<version>")
}

Maven工件有意使用中性的OpenAPI名称，而不是Swagger品牌：

io.github.neo1228:openapi-mcp-spring-boot-starter

Maven(pom.xml):

<properties>
  <openapi-mcp.version>0.1.0-SNAPSHOT</openapi-mcp.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.8.17</version>
  </dependency>
  <dependency>
    <groupId>io.github.neo1228</groupId>
    <artifactId>openapi-mcp-spring-boot-starter</artifactId>
    <version>${openapi-mcp.version}</version>
  </dependency>
</dependencies>

使用发布版本（例如 0.1.0)当从远程工件存储库消费时。

3.添加一个控制器

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
public class HelloController {

    @Operation(operationId = "getHello", summary = "Get greeting message")
    @GetMapping("/hello")
    public Map<String, Object> hello(@RequestParam(defaultValue = "world") String name) {
        return Map.of("message", "Hello " + name);
    }
}

4.添加配置(application.yml)

spring:
  ai:
    mcp:
      server:
        protocol: STREAMABLE_HTTP
        streamable-http:
          mcp-endpoint: /mcp

swagger:
  mcp:
    enabled: true
    api-docs-path: /v3/api-docs
    tool-name-prefix: api_

5.运行并验证

  1. 启动应用程序： ./gradlew bootRun 或 ./mvnw spring-boot:run
  2. 验证OpenAPI： http://localhost:8080/v3/api-docs
  3. 验证MCP端点： http://localhost:8080/mcp
  4. 从MCP客户端连接

生成的工具名称如下 <tool-name-prefix><operation-id> （例如： api_gethello).

MCP客户端工作流

此启动器公开了直接的API工具和元工具层，因此一般的MCP客户端可以使用大型API，而无需事先猜测工具名称：

  1. meta_get_api_capabilities 返回API目录统计信息、可用网关工具、编排功能、安全策略和响应控件。
  2. meta_list_api_groups 按OpenAPI标记/组汇总公开的API目录。
  3. meta_discover_api_tools 查找自然语言请求的相关操作。
  4. meta_describe_api_tool 返回所选工具的方法/路径、参数、必需参数、请求体模式、风险标志和完整的MCP输入模式。
  5. meta_validate_api_call 在不调度HTTP的情况下验证一个生成的API工具调用，包括所需的参数、风险操作确认和调度预览。
  6. meta_plan_api_workflow 将工作流目标转化为具有合同和风险标志的确定性候选步骤计划。
  7. meta_invoke_api_workflow 顺序干式运行或执行多个生成的API工具。
  8. meta_invoke_api_by_intent 当客户端已经有足够的参数时，可以选择并调用最佳匹配操作。

已配置 tool-name-prefix 仍然应用，因此默认生成的名称为 api_meta_get_api_capabilities, api_meta_validate_api_call, api_meta_list_api_groups, api_meta_discover_api_tools, api_meta_describe_api_tool, api_meta_plan_api_workflow, api_meta_invoke_api_workflow，以及 api_meta_invoke_api_by_intent.

当工具调用被拒绝时，文本内容仍然是人类可读的 structuredContent.error 为客户提供稳定的机器合同：

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Missing required argument(s): path parameter: orderId",
    "status": 400,
    "retryable": false,
    "details": { "toolName": "api_getorder" }
  }
}

推荐客户端循环：

  1. 呼叫 api_meta_get_api_capabilities 了解网关功能和安全策略。
  2. 使用 api_meta_discover_api_tools 或 api_meta_list_api_groups 以找到候选操作。
  3. 使用 api_meta_describe_api_tool 用于精确的参数模式。
  4. 使用 api_meta_validate_api_call 在有风险或产生呼叫之前。
  5. 对于多步骤工作，请致电 api_meta_plan_api_workflow那么 api_meta_invoke_api_workflow 和 dryRun=true，然后执行 dryRun=false 只有在验证后才是干净的。

默认情况下，工作流执行是有意安全的：

  • meta_validate_api_call 和 meta_invoke_api_workflow 在分派HTTP之前，模拟运行会验证工具名称、参数、必填字段、分派路径和风险标志。
  • 工作流步骤具有 { "id": "...", "toolName": "...", "arguments": { ... } }.
  • 后续步骤可以使用JSONPath插值读取之前的结构化结果： ${create:$.order.id}.
  • 如果整个参数值是一个模板，则传递解析的原始值。如果模板嵌入到较长的字符串中，则值将被字符串化。
  • 递归元工具编排被阻止；工作流步骤只能调用生成的API操作工具。
  • 有风险的HTTP方法仍然需要配置 _confirm 令牌，甚至在工作流中。

验证有效载荷示例：

{
  "toolName": "api_getorder",
  "arguments": {
    "orderId": "order-1"
  }
}

工作流负载示例：

{
  "dryRun": false,
  "steps": [
    {
      "id": "create",
      "toolName": "api_createorder",
      "arguments": {
        "body": { "id": "order-1", "item": "shoe" },
        "_confirm": "CONFIRM"
      }
    },
    {
      "id": "read",
      "toolName": "api_getorder",
      "arguments": {
        "orderId": "${create:$.order.id}"
      }
    }
  ]
}

对于较大的API，设置 swagger.mcp.smart-context.gateway-only=true 仅公开此网关/元层，而不是将每个操作注册为顶级MCP工具。

本地开发安装

如果工件尚未发布到远程注册表：

  1. 构建并发布到本地Maven缓存：
    • ./gradlew publishToMavenLocal
  2. 在您的消费者应用程序中：
    • 添加 mavenLocal() 仓库
    • 使用版本 0.1.0-SNAPSHOT （或您选择的本地版本）

密钥配置

  • swagger.mcp.enabled：启用/禁用网桥（默认 true)
  • swagger.mcp.api-docs-path：OpenAPI文档路径（默认 /v3/api-docs)
  • swagger.mcp.tool-name-prefix：工具名称前缀（默认值 api_)
  • swagger.mcp.smart-context.gateway-only：仅公开元工具
  • swagger.mcp.execution.virtual-threads-enabled：当当前运行时支持虚拟线程时，通过虚拟线程运行出站API调度（默认 true；安全地回到Java 17）
  • swagger.mcp.execution.allowed-argument-headers：动态的可选allowlist _headers 由MCP客户端传递
  • swagger.mcp.execution.blocked-argument-headers：denylist for动态 _headers；默认情况下，逐跳阻止/传输敏感标头，如 Host, Content-Length, Connection，以及 Transfer-Encoding
  • swagger.mcp.security.require-confirmation-for-risky-operations：要求 _confirm 风险方法的标记

对于有风险的HTTP方法(POST, PUT, PATCH, DELETE)，默认策略要求 _confirm=CONFIRM.适配器还在调度HTTP之前验证缺少所需的路径/查询/头/主体参数，因此MCP客户端会得到一个明确的工具错误，而不是格式错误的API调用。

兼容性矩阵

初学者 Java Spring Boot springdoc openapi Spring AI BOM
0.1.x 17,21,25测试；Java 17字节码 3.5.x 2.8.17 1.1.5

Spring Boot 4.x在0.1.x行中故意不受支持。请继续使用Spring Boot 3.5.x和springdoc openapi 2.8.x，除非此存储库删除了新的主要/次要兼容行。构建使用 --release 17，因此在CI验证包括Java 25在内的较新运行时时，工件在Java 17上仍然是可消费的。

消费者项目示例

看 examples/minimal-webmvc-gradle 对于使用Swagger MCP Bridge的最小Spring Boot应用程序。

该示例也可以构建为可运行的MCP服务器映像，用于注册表和市场提交：

docker build \
  -f examples/minimal-webmvc-gradle/Dockerfile \
  -t ghcr.io/neo1228/swagger-mcp-bridge-example:local \
  .

docker run --rm -p 8080:8080 ghcr.io/neo1228/swagger-mcp-bridge-example:local

启动后手动烟雾检查：

  • OpenAPI： http://localhost:8080/v3/api-docs
  • API样本： http://localhost:8080/hello?name=Bridge
  • MCP可流式HTTP端点： http://localhost:8080/mcp
  • Smithery/服务器卡元数据： http://localhost:8080/.well-known/mcp/server-card.json
  • MCP注册表服务器元数据： http://localhost:8080/.well-known/mcp/server.json

代理/市场安装指南

  • 代理安装说明： llms-install.md
  • 市场准备指南： docs/marketplace-readiness.md
  • 市场徽标： docs/assets/swagger-mcp-bridge-logo.png

注册和发布准备就绪

  • Maven Central发布包工作流： .github/workflows/release-central.yml
  • GHCR示例服务器映像工作流： .github/workflows/publish-example-server.yml
  • MCP注册表元数据： registry/server.json
  • 静态发现元数据： examples/minimal-webmvc-gradle/src/main/resources/static/.well-known/mcp/
  • 元数据验证脚本： scripts/verify-marketplace-metadata.sh
  • 中央捆绑包帮助程序： scripts/build-central-bundle.sh

官方MCP注册表接受Docker/OCI元数据，因此发布的示例映像包含所需的 io.modelcontextprotocol.server.name=io.github.Neo1228/swagger-mcp-bridge 标签和用途 registry/server.json 作为提交源。启动器工件仍然是具有坐标的正常Maven依赖项 io.github.neo1228:openapi-mcp-spring-boot-starter.Smithery URL发布在示例服务器托管在公共HTTPS后兼容 /mcp 终点；在此之前，存储库提供所需的静态服务器卡和本地/上行链路验证路径。

发布和版本控制

  • 发布流程： RELEASING.md
  • 版本控制策略： VERSIONING.md
  • 变更日志： CHANGELOG.md

发展

  • 运行测试： ./gradlew test
  • 贡献指南： CONTRIBUTING.md
  • 安全报告： SECURITY.md

许可证

Apache许可证2.0(LICENSE)

相关 MCP