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: |
| 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:")
}Maven工件有意使用中性的OpenAPI名称，而不是Swagger品牌：
io.github.neo1228:openapi-mcp-spring-boot-starterMaven(pom.xml):
0.1.0-SNAPSHOT
org.springframework.boot
spring-boot-starter-web
org.springdoc
springdoc-openapi-starter-webmvc-api
2.8.17
io.github.neo1228
openapi-mcp-spring-boot-starter
${openapi-mcp.version}
使用发布版本（例如 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 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.运行并验证
- 启动应用程序：
./gradlew bootRun或./mvnw spring-boot:run - 验证OpenAPI：
http://localhost:8080/v3/api-docs - 验证MCP端点：
http://localhost:8080/mcp - 从MCP客户端连接
生成的工具名称如下 ` （例如： api_gethello`).
MCP客户端工作流
此启动器公开了直接的API工具和元工具层，因此一般的MCP客户端可以使用大型API，而无需事先猜测工具名称：
meta_get_api_capabilities返回API目录统计信息、可用网关工具、编排功能、安全策略和响应控件。meta_list_api_groups按OpenAPI标记/组汇总公开的API目录。meta_discover_api_tools查找自然语言请求的相关操作。meta_describe_api_tool返回所选工具的方法/路径、参数、必需参数、请求体模式、风险标志和完整的MCP输入模式。meta_validate_api_call在不调度HTTP的情况下验证一个生成的API工具调用，包括所需的参数、风险操作确认和调度预览。meta_plan_api_workflow将工作流目标转化为具有合同和风险标志的确定性候选步骤计划。meta_invoke_api_workflow顺序干式运行或执行多个生成的API工具。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" }
}
}推荐客户端循环：
- 呼叫
api_meta_get_api_capabilities了解网关功能和安全策略。 - 使用
api_meta_discover_api_tools或api_meta_list_api_groups以找到候选操作。 - 使用
api_meta_describe_api_tool用于精确的参数模式。 - 使用
api_meta_validate_api_call在有风险或产生呼叫之前。 - 对于多步骤工作，请致电
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工具。
本地开发安装
如果工件尚未发布到远程注册表：
- 构建并发布到本地Maven缓存：
- ./gradlew publishToMavenLocal
- 在您的消费者应用程序中：
- 添加 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-Encodingswagger.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)