Swagger MCP Bridge

Swagger MCP Bridge

将任何基于 SpringDoc 的 Spring Boot API 转换为可用于生产环境的 MCP 网关。

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

名称与坐标

此代码库有意将各个公共入口分开命名，使其在各自的生态系统中都更加自然：

入口	名称
项目 / 文档	Swagger MCP Bridge
Maven 依赖项	io.github.neo1228:openapi-mcp-spring-boot-starter
官方 MCP Registry 服务	io.github.Neo1228/swagger-mcp-bridge
可运行示例镜像	ghcr.io/neo1228/swagger-mcp-bridge-example:<version>
Spring 配置前缀	swagger.mcp.*

项目名称沿用既有的 Bridge 品牌，而 Maven 构件使用 Java 用户所需的通用 OpenAPI/Spring Boot starter 坐标。Registry 服务和 GHCR 镜像则标识供 MCP 目录使用的打包可运行示例。

为什么选择 Swagger MCP Bridge

大多数 MCP API Bridge 止步于简单的工具封装。Swagger MCP Bridge 被设计为运行时网关：它向大模型客户端开放现有的 Spring 控制器，同时保留契约、防护机制和运行可见性。

你将获得

• 无需样板代码，即可从正在运行的 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+
• Spring Boot 3.5.x
• Spring Web

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 验证一次生成的 API 工具调用，而不分发 HTTP 请求；验证内容包括必需参数、风险操作确认和分发预览。
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，然后使用 dryRun=true 调用 api_meta_invoke_api_workflow；只有验证通过后，才使用 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：动态 _headers 的可选允许列表，供 MCP 客户端传入
• swagger.mcp.execution.blocked-argument-headers：动态 _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 调用。

兼容性矩阵

Starter	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

有意不在 0.1.x 系列中支持 Spring Boot 4.x。请使用 Spring Boot 3.5.x 和 springdoc-openapi 2.8.x，除非此仓库发布新的主要/次要版本兼容系列。构建使用 --release 17，因此该构件仍可在 Java 17 上使用，同时 CI 会验证包括 Java 25 在内的更新运行时。

示例使用方项目

请参阅 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 Streamable HTTP 端点：http://localhost:8080/mcp
• Smithery/服务卡元数据：http://localhost:8080/.well-known/mcp/server-card.json
• MCP Registry 服务元数据：http://localhost:8080/.well-known/mcp/server.json

Agent / 市场安装指南

• Agent 安装说明：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 元数据：registry/server.json
• 静态发现元数据：examples/minimal-webmvc-gradle/src/main/resources/static/.well-known/mcp/
• 元数据验证脚本：scripts/verify-marketplace-metadata.sh
• Central 包辅助脚本：scripts/build-central-bundle.sh

官方 MCP Registry 接受 Docker/OCI 元数据，因此已发布的示例镜像带有必需的 io.modelcontextprotocol.server.name=io.github.Neo1228/swagger-mcp-bridge 标签，并使用 registry/server.json 作为提交来源。Starter 构件仍是坐标为 io.github.neo1228:openapi-mcp-spring-boot-starter 的普通 Maven 依赖。示例服务托管在公开的 HTTPS /mcp 端点后，即可兼容通过 Smithery URL 发布；在此之前，仓库提供所需的静态服务卡和本地/Uplink 验证流程。

发布与版本控制

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

开发

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

许可证

Apache License 2.0（LICENSE）