Neo1228/spring-boot-starter-swagger-mcp

**Turn any SpringDoc-powered Spring Boot API into a production-ready MCP gateway.**
Swagger MCP Bridge discovers your OpenAPI operations, publishes them as safe MCP tools, and adds a smart gateway layer for API discovery, validation, response shaping, and multi-step workflow orchestration.
Naming and Coordinates
This repository intentionally separates the public surfaces so each one reads naturally in its own ecosystem:
| Surface | Name |
|---|---|
| Project / docs | Swagger MCP Bridge |
| Maven dependency | io.github.neo1228:openapi-mcp-spring-boot-starter |
| Official MCP Registry server | io.github.Neo1228/swagger-mcp-bridge |
| Runnable example image | ghcr.io/neo1228/swagger-mcp-bridge-example: |
| Spring configuration prefix | swagger.mcp.* |
The project name keeps the established bridge branding, while the Maven artifact uses the neutral OpenAPI/Spring Boot starter coordinate expected by Java consumers. The registry server and GHCR image identify the packaged runnable example used by MCP directories.
Why Swagger MCP Bridge
Most MCP API bridges stop at a thin tool wrapper. Swagger MCP Bridge is designed as a runtime gateway: it exposes your existing Spring controllers to LLM clients while preserving contracts, guardrails, and operational visibility.
What You Get
- Zero-boilerplate discovery of SpringDoc OpenAPI operations from your running Spring app
- Automatic MCP tool registration for discovered API operations
- Smart-context gateway tools: 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 catalog and workflow layer for capability inspection, preflight validation, grouped exploration, dry-run planning, and sequential execution
- Rich MCP input schemas generated from OpenAPI constraints: required fields, enums, numeric/string/object limits, examples, and deprecation hints
- Response shaping with JSONPath projection and summarization controls
- Execution guardrails: required argument validation, unresolved path-template protection, and safe _headers filtering
- Structured MCP error responses with stable codes such as INVALID_ARGUMENT, SECURITY_DENIED, WORKFLOW_ERROR, and HTTP_DISPATCH_FAILED
- Java 17 bytecode with CI coverage on Java 17, 21, and 25
- Optional virtual-thread HTTP dispatch on Java 21+ runtimes, with automatic platform-thread fallback on Java 17
- Production guardrails for dangerous operations: _confirm, blocked paths, role checks, audit logs, and structured client errors
Architecture
Quick Start
1. Create a Spring Boot app
Use:
- Java 17+
- Spring Boot 3.5.x
- Spring Web
2. Add dependencies
Gradle (build.gradle.kts):
The Maven artifact intentionally uses the neutral OpenAPI name rather than Swagger branding:
Maven (pom.xml):
Use a release version (for example 0.1.0) when consuming from a remote artifact repository.
3. Add one controller
4. Add configuration (application.yml)
5. Run and verify
1. Start app: ./gradlew bootRun or ./mvnw spring-boot:run
2. Verify OpenAPI: http://localhost:8080/v3/api-docs
3. Verify MCP endpoint: http://localhost:8080/mcp
4. Connect from an MCP client
Generated tool names follow (example: api_gethello).
MCP Client Workflow
This starter exposes direct API tools and a meta-tool layer so general MCP clients can work with large APIs without guessing tool names upfront:
1. meta_get_api_capabilities returns API catalog stats, available gateway tools, orchestration features, safety policy, and response controls.
2. meta_list_api_groups summarizes the exposed API catalog by OpenAPI tag/group.
3. meta_discover_api_tools finds relevant operations for a natural-language request.
4. meta_describe_api_tool returns the selected tool's method/path, parameters, required arguments, request body schema, risk flags, and full MCP input schema.