Spring Boot Starter Swagger MCP

1# spring-boot-starter-swagger-mcp
2 
3[![CI](https://github.com/Neo1228/spring-boot-starter-swagger-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Neo1228/spring-boot-starter-swagger-mcp/actions/workflows/ci.yml)
4[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
5[![Java](https://img.shields.io/badge/Java-17%2B-orange.svg)](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
6[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.x-brightgreen.svg)](https://spring.io/projects/spring-boot)
7 
8Spring Boot starter that automatically exposes SpringDoc OpenAPI operations as MCP tools.
9 
10## What You Get
11 
12- Auto-discovery of OpenAPI operations from your running Spring app
13- Auto-registration of MCP tools for discovered API operations
14- Smart-context tools: `meta_discover_api_tools`, `meta_invoke_api_by_intent`
15- Response optimization with projection/summarization controls
16- Risk controls for dangerous operations (`_confirm`, blocked paths, role checks, audit logs)
17 
18## Architecture
19 
20```mermaid
21graph TD
22    User([User / LLM Client]) <--> MCP[MCP Client / Claude Desktop]
23    MCP <--> Bridge[Swagger MCP Bridge /starter/]
24    Bridge <--> Docs[SpringDoc OpenAPI /v3/api-docs]
25    Bridge <--> API[Your Spring Controller /hello]
26```
27 
28## Quick Start (New Empty Spring Boot Project)
29 
30### 1. Create a Spring Boot app
31 
32Use:
33 
34- Java 17+
35- Spring Boot 3.5.x
36- Spring Web
37 
38### 2. Add dependencies
39 
40Gradle (`build.gradle.kts`):
41 
42```kotlin
43plugins {
44    id("org.springframework.boot") version "3.5.9"
45    id("io.spring.dependency-management") version "1.1.7"
46    java
47}
48 
49java {
50    sourceCompatibility = JavaVersion.VERSION_17
51}
52 
53repositories {
54    mavenCentral()
55}
56 
57dependencies {
58    implementation("org.springframework.boot:spring-boot-starter-web")
59    implementation("org.springdoc:springdoc-openapi-starter-webmvc-api:2.8.3")
60    implementation("io.github.neo1228:spring-boot-starter-swagger-mcp:<version>")
61}
62```
63 
64Maven (`pom.xml`):
65 
66```xml
67<properties>
68  <swagger-mcp.version>0.1.0-SNAPSHOT</swagger-mcp.version>
69</properties>
70 
71<dependencies>
72  <dependency>
73    <groupId>org.springframework.boot</groupId>
74    <artifactId>spring-boot-starter-web</artifactId>
75  </dependency>
76  <dependency>
77    <groupId>org.springdoc</groupId>
78    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
79    <version>2.8.3</version>
80  </dependency>
81  <dependency>
82    <groupId>io.github.neo1228</groupId>
83    <artifactId>spring-boot-starter-swagger-mcp</artifactId>
84    <version>${swagger-mcp.version}</version>
85  </dependency>
86</dependencies>
87```
88 
89Use a release version (for example `0.1.0`) when consuming from a remote artifact repository.
90 
91### 3. Add one controller
92 
93```java
94import io.swagger.v3.oas.annotations.Operation;
95import org.springframework.web.bind.annotation.GetMapping;
96import org.springframework.web.bind.annotation.RequestParam;
97import org.springframework.web.bind.annotation.RestController;
98 
99import java.util.Map;
100 
101@RestController
102public class HelloController {
103 
104    @Operation(operationId = "getHello", summary = "Get greeting message")
105    @GetMapping("/hello")
106    public Map<String, Object> hello(@RequestParam(defaultValue = "world") String name) {
107        return Map.of("message", "Hello " + name);
108    }
109}
110```
111 
112### 4. Add configuration (`application.yml`)
113 
114```yaml
115spring:
116  ai:
117    mcp:
118      server:
119        protocol: STREAMABLE_HTTP
120        streamable-http:
121          mcp-endpoint: /mcp
122 
123swagger:
124  mcp:
125    enabled: true
126    api-docs-path: /v3/api-docs
127    tool-name-prefix: api_
128```
129 
130### 5. Run and verify
131 
1321. Start app: `./gradlew bootRun` or `./mvnw spring-boot:run`
1332. Verify OpenAPI: `http://localhost:8080/v3/api-docs`
1343. Verify MCP endpoint: `http://localhost:8080/mcp`
1354. Connect from an MCP client
136 
137Generated tool names follow `<tool-name-prefix><operation-id>` (example: `api_gethello`).
138 
139## Use It Before Public Release (Local Development Install)
140 
141If the artifact is not published to a remote registry yet:
142 
1431. Build and publish to local Maven cache:
144   - `./gradlew publishToMavenLocal`
1452. In your consumer app:
146   - add `mavenLocal()` repository
147   - use version `0.1.0-SNAPSHOT` (or your chosen local version)
148 
149## Key Configuration
150 
151- `swagger.mcp.enabled`: enable/disable bridge (default `true`)
152- `swagger.mcp.api-docs-path`: OpenAPI docs path (default `/v3/api-docs`)
153- `swagger.mcp.tool-name-prefix`: tool name prefix (default `api_`)
154- `swagger.mcp.smart-context.gateway-only`: expose only meta tools
155- `swagger.mcp.security.require-confirmation-for-risky-operations`: require `_confirm` token for risky methods
156 
157For risky HTTP methods (`POST`, `PUT`, `PATCH`, `DELETE`), default policy requires `_confirm=CONFIRM`.
158 
159## Compatibility Matrix
160 
161| Starter | Java | Spring Boot | springdoc-openapi | Spring AI BOM |
162|---|---|---|---|---|
163| 0.1.x | 17+ | 3.5.x | 2.8.3 | 1.1.2 |
164 
165Spring Boot 4.x is not supported in this repository.
166 
167## Example Consumer Project
168 
169See `examples/minimal-webmvc-gradle` for a minimal app using this starter.
170 
171## Release And Versioning
172 
173- Release process: `RELEASING.md`
174- Versioning policy: `VERSIONING.md`
175- Changelog: `CHANGELOG.md`
176 
177## Development
178 
179- Run tests: `./gradlew test`
180- Contribution guide: `CONTRIBUTING.md`
181- Security reporting: `SECURITY.md`
182 
183## License
184 
185Apache License 2.0 (`LICENSE`)
186