Skip to content
Back to search

api2mcp4j

Spring Boot Starter: Auto-convert existing REST APIs (@RestController) to MCP Server with zero/low-code. Expose controllers as MCP Tools instantly.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/theeterna--api2mcp4j/badge.svg)](/listings/theeterna--api2mcp4j)

HTML

<a href="/listings/theeterna--api2mcp4j"><img src="/api/listings/theeterna--api2mcp4j/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Clone & build

git clone https://github.com/TheEterna/api2mcp4j.git
cd api2mcp4j
mvn clean install -DskipTests

2. Add to your Spring Boot project

<dependency>
  <groupId>com.ai.plug</groupId>
  <artifactId>server2mcp-starter-webmvc</artifactId>
  <version>1.1.4-SNAPSHOT</version>
</dependency>

3. Configure

plugin:
  mcp:
    enabled: true
    scope: interface   # 'interface' = auto-register all controllers; 'custom' = @ToolScan only
    parser:
      des:    SWAGGER3, JAVADOC, TOOL, JACKSON, SWAGGER2
      param:  MCPTOOL, JAVADOC, TOOL, SpringMVC, JACKSON, SWAGGER2, SWAGGER3

4. Start & test

mvn spring-boot:run

Your MCP server is live on `http://localhost:8080/mcp/jsonrpc` (and HTTP fallbacks on `/mcp/discover`, `/mcp/tasks`, `/mcp/sse`).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 341 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # api2mcp4j
  2. **Turn your existing Spring Boot REST controllers into MCP (Model Context Protocol) tools — no rewrites, no `@Tool` everywhere.**
  3. ```xml
  4. <dependency>
  5. <groupId>io.github.theeterna</groupId>
  6. <artifactId>server2mcp-starter-webmvc</artifactId>
  7. <version>1.2.0</version>
  8. </dependency>
  9. ```
  10. <!-- Reactive (WebFlux) users swap the artifactId to `server2mcp-starter-webflux` — same protocol surface. -->
  11. [![Java](https://img.shields.io/badge/Java-17%2B-blue)](https://www.java.com)
  12. [![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.1.0-brightgreen)](https://spring.io/projects/spring-boot)
  13. [![Spring AI](https://img.shields.io/badge/Spring%20AI-2.0.0-green)](https://spring.io/projects/spring-ai)
  14. [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-2.0.0-orange)](https://modelcontextprotocol.io)
  15. [![MCP Protocol](https://img.shields.io/badge/MCP%20Protocol-2026--07--28-100%25-success)](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md)
  16. [![Tests](https://img.shields.io/badge/Tests-600%20passing-brightgreen)](#-testing--verification)
  17. [![End-to-End](https://img.shields.io/badge/Curl%20verify-21%2F21-success)](#-one-line-verification)
  18. [![License](https://img.shields.io/badge/License-Apache%202.0-blue)](LICENSE)
  19. [English](README.md) · [中文](README_zh.md) · [Docs](https://docs.xiaohan.chat/) · [Integration Matrix](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md)
  20. ---
  21. ## Why api2mcp4j?
  22. Most MCP integrations force you to:
  23. - Add `@Tool` / `@McpTool` to every method
  24. - Duplicate business logic into a parallel "MCP" code path
  25. - Maintain separate tool descriptions
  26. **api2mcp4j** scans your existing `@RestController` beans and exposes their methods as MCP tools — **zero changes to business code**. Like MyBatis-Plus enhances MyBatis, api2mcp4j enhances Spring AI MCP.
  27. ```java
  28. // Your existing controller — unchanged
  29. @RestController
  30. public class OrderController {
  31. @GetMapping("/orders/{id}")
  32. public Order getOrder(@PathVariable Long id) { ... }
  33. }
  34. // Becomes an MCP tool: OrderController_getOrder
  35. // With auto-generated description from Swagger / Javadoc / Spring MVC / Jackson / Spring AI
  36. ```
  37. ---
  38. ## ✨ Key Features
  39. | | |
  40. |---|---|
  41. | 🎯 **Non-intrusive** | `interface` scope auto-registers all controllers; no `@Tool` annotation needed |
  42. | 🔍 **5-parser chain** | Swagger v3 / Swagger v2 / Javadoc / Spring MVC / Jackson / Spring AI — best description wins |
  43. | 🛠️ **Full MCP coverage** | Tools / Resources / Prompts / Completions / Elicitation / Sampling / Roots |
  44. | 🆕 **Protocol 2026-07-28** | Wire schema + JSON-RPC routing + SSE long-poll + MRTR + OTel traceparent — 100% |
  45. | 🔌 **Custom parsers** | Implement `AbstractDesParser` / `AbstractParamParser`, plug into the chain |
  46. | 🧪 **TDD discipline** | JUnit5, double commit `[RED]` then `[GREEN]`, 600 tests all green |
  47. | 🚀 **Quick start** | `mvn spring-boot:run` → MCP endpoint ready |
  48. ---
  49. ## 🚀 Quick Start (≈ 3 minutes)
  50. ### 1. Clone & build
  51. ```bash
  52. git clone https://github.com/TheEterna/api2mcp4j.git
  53. cd api2mcp4j
  54. mvn clean install -DskipTests
  55. ```
  56. ### 2. Add to your Spring Boot project
  57. ```xml
  58. <dependency>
  59. <groupId>io.github.theeterna</groupId>
  60. <artifactId>server2mcp-starter-webmvc</artifactId>
  61. <version>1.2.0</version>
  62. </dependency>
  63. ```
  64. Reactive (Spring WebFlux) applications use the WebFlux starter instead — identical protocol surface, reactive transport:
  65. ```xml
  66. <dependency>
  67. <groupId>io.github.theeterna</groupId>
  68. <artifactId>server2mcp-starter-webflux</artifactId>
  69. <version>1.2.0</version>
  70. </dependency>
  71. ```
  72. ### 3. Configure
  73. ```yaml
  74. plugin:
  75. mcp:
  76. enabled: true
  77. scope: interface # 'interface' = auto-register all controllers; 'custom' = @ToolScan only
  78. parser:
  79. des: MCPTOOL, JAVADOC, TOOL, JACKSON, SWAGGER3, SWAGGER2
  80. param: MCPTOOL, JAVADOC, TOOL, SpringMVC, JACKSON, SWAGGER2, SWAGGER3
  81. strict: false # true = a misspelled parser name aborts startup (default: warn only)
  82. ```
  83. ### 4. Start & test
  84. ```bash
  85. mvn spring-boot:run
  86. ```
  87. Your MCP server is live on `http://localhost:8080/mcp/jsonrpc` (and HTTP fallbacks on `/mcp/discover`, `/mcp/tasks`, `/mcp/sse`).
  88. ---
  89. ## 📡 MCP Protocol 2026-07-28 — 100% Compatible
  90. api2mcp4j is **the first Java MCP framework to ship full 2026-07-28 support**, even though Java MCP SDK 2.0 only implements the 2025-11-25 wire. We bypassed SDK limitations with a custom JSON-RPC router, SSE controller, and wire schema — **all without breaking SDK upgrade compatibility** (controllers stay as fallbacks when SDK ≥ 3.0.0 lands).
  91. ### 8 RPC routes, all real (not HTTP simulations)
  92. | RPC | JSON-RPC endpoint | SSE long-poll | Source |
  93. |---|---|---|---|
  94. | `server/discover` | ✅ `POST /mcp/jsonrpc` | — | [`DiscoverEndpoint`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#二servercapabilities握手声明) |
  95. | `tasks/create` | ✅ | — | [`TaskStore`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#五新增-rpc-方法) |
  96. | `tasks/get` / `list` / `cancel` | ✅ | — | [`TasksEndpoint`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#五新增-rpc-方法) |
  97. | `tasks/augmented-prompt` | ✅ | — | [`AugmentedPromptEndpoint`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#五新增-rpc-方法) |
  98. | `subscriptions/listen` | ✅ (poll) | ✅ `GET /mcp/sse` + Last-Event-ID + 15s heartbeat | [`SseNotificationsController`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#五新增-rpc-方法) |
  99. | `input_required/respond` (MRTR) | ✅ envelope | — | [`MrtrToolCallbackWrapper`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#五新增-rpc-方法) |
  100. ### Wire JSON fields — 100% reachable
  101. | 2026-07-28 field | Status | Where |
  102. |---|---|---|
  103. | `tools.listChanged` / `resources.listChanged` / `prompts.listChanged` | ✅ SDK native | `WireSchemaExporter.syncAll()` |
  104. | `tools.subscription` / `completions.listChanged` *(new in 2026-07-28)* | ✅ Custom wire | [`WireServerCapabilities`](server2mcp-core/src/main/java/com/ai/plug/core/spec/capabilities/WireServerCapabilities.java) |
  105. | `experimental.io.modelcontextprotocol/tasks` *(new)* | ✅ Custom wire | Same |
  106. | `_meta.resultType` / `ttlMs` / `cacheScope` / `cacheWrapperKey` | ✅ Auto-injected via meta map | `@McpTool(...)` + `McpCallToolResultConverter` |
  107. | `_meta.taskHandle` / `inputRequests` / `requestState` | ✅ Auto-recognized | `InputRequiredResult` / `TaskHandle` return values |
  108. | `_meta.traceparent` / `tracestate` / `baggage` (W3C SEP-414) | ✅ Auto-minted in JSON-RPC | [`MetaUtils`](server2mcp-core/src/main/java/com/ai/plug/core/spec/meta/MetaUtils.java) |
  109. | MRTR state machine (cross-round merge + 8-round guard) | ✅ | [`MrtrDriver`](server2mcp-core/src/main/java/com/ai/plug/core/spec/mrtr/MrtrDriver.java) |
  110. | `outputSchema` | ✅ SDK field | `McpSchema.Tool.builder().outputSchema()` |
  111. | Capabilities health / diff / wire validation | ✅ | `CapabilitiesHealth` + `SnapshotCompareTool` + `WireSchemaValidator` |
  112. **[Full integration matrix →](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md)**
  113. ---
  114. ## ✅ One-line verification
  115. The demo app boots with H2 in-memory DB (zero external dependencies) and validates every 2026-07-28 feature against a real HTTP/SSE wire:
  116. ```bash
  117. cd server2mcp-test && mvn spring-boot:run # starts on :8888 (H2 in-memory)
  118. # In another shell:
  119. bash scripts/verify-protocol-2026-07-28.sh http://localhost:8888
  120. ```
  121. ```
  122. == 0. liveness == ✓ actuator reachable
  123. == 1. server/discover (JSON-RPC) == ✓×7 (jsonrpc=2.0, preferredVersion=2026-07-28,
  124. tools.listChanged, tools.subscription,
  125. completions.listChanged, experimental.tasks,
  126. _meta.traceparent)
  127. == 2. tasks/* (JSON-RPC) == ✓×5 (create, get, list, cancel full lifecycle)
  128. == 3. tasks/augmented-prompt == ✓×1
  129. == 4. subscriptions/listen == ✓×3 (HTTP poll + text/event-stream + connected)
  130. == 5. input_required/respond == ✓×2 (accepted + state echo)
  131. == 6. HTTP legacy endpoints == ✓×2 (/mcp/discover + /mcp/notifications)
  132. == summary == passed: 21 / failed: 0
  133. ALL ASSERTIONS PASSED — protocol 2026-07-28 wire verified
  134. ```
  135. **[Evidence log →](docs/logs/2026-08-03_ceo_demo-end-to-end-21of21.md)**
  136. ---
  137. ## 🧪 Testing & Verification
  138. | Layer | Count | Status |
  139. |---|---|---|
  140. | Unit tests (`server2mcp-core`) | 575 | ✅ all green |
  141. | Integration tests (`server2mcp-starter-webmvc`) | 22 | ✅ all green |
  142. | Demo tests (`server2mcp-test`) | 3 | ✅ all green |
  143. | **End-to-end curl verification** | **21/21** | **✅** |
  144. | Total | **600+ tests, 21/21 e2e** | **✅** |
  145. Test philosophy: **TDD double-commit** — `[RED]` test first, then `[GREEN]` implementation. See [`docs/specs/TEST_SPEC.md`](docs/specs/TEST_SPEC.md).
  146. ---
  147. ## 🏗️ Architecture
  148. ```
  149. ┌─────────────────────────────────────────────────────────────┐
  150. │ Spring Boot Application │
  151. │ │
  152. │ ┌─── Your existing code (unchanged) ───┐ │
  153. │ │ @RestController │ │
  154. │ │ @Service │ │
  155. │ │ @Component │ │
  156. │ └────────────────┬─────────────────────┘ │
  157. │ │ │
  158. │ ┌────────────────▼─────────────────────┐ │
  159. │ │ api2mcp4j framework │ │
  160. │ │ │ │
  161. │ │ Scanner ──→ Parser chain ──→ Provider │
  162. │ │ │ │ │ │
  163. │ │ Spring MVC 5 parsers SyncMcpToolMethodCallback │
  164. │ │ discovery (Swagger2/3, (template method) │
  165. │ │ Javadoc, │
  166. │ │ Jackson, │
  167. │ │ Spring AI) │
  168. │ │ │ │
  169. │ │ ── 2026-07-28 layer (new) ── │
  170. │ │ • JsonRpcRouter + JsonRpcRoutes │
  171. │ │ • WireServerCapabilities + JsonExporter │
  172. │ │ • SseNotificationsController │
  173. │ │ • MrtrDriver + MrtrSessionStore │
  174. │ │ • MrtrToolCallbackWrapper │
  175. │ │ • MetaUtils (W3C traceparent mint) │
  176. │ └────────────────┬─────────────────────┘ │
  177. │ │ │
  178. │ ┌────────────────▼─────────────────────┐ │
  179. │ │ Spring AI MCP SDK 2.0 │ │
  180. │ │ (McpSyncServer / McpAsyncServer) │ │
  181. │ └────────────────┬─────────────────────┘ │
  182. └────────────────────┼────────────────────────────────────────┘
  183. │ wire: JSON-RPC 2.0 + SSE
  184. ▼
  185. ┌────────────────────┐
  186. │ MCP Clients │
  187. │ • Claude Desktop │
  188. │ • Cursor / Cline │
  189. │ • Your BFF / Agent │
  190. └────────────────────┘
  191. ```
  192. **[Detailed architecture →](docs/reference/architecture.md)**
  193. ---
  194. ## 📦 Modules
  195. ```
  196. api2mcp4j/
  197. ├── server2mcp-common # Constants & utilities
  198. ├── server2mcp-core # Core engine: annotations, scanners, callbacks, providers
  199. │ ├── com.ai.plug.core.annotation.* # @McpTool, @McpResource, @McpPrompt, @McpArg
  200. │ ├── com.ai.plug.core.parser.* # 5-parser chain (des + param)
  201. │ ├── com.ai.plug.core.callback.* # Sync + Async template methods
  202. │ ├── com.ai.plug.core.spec.* # 2026-07-28 wire layer
  203. │ └── com.ai.plug.core.provider.* # Spring AI bridge
  204. ├── server2mcp-autoconfigure # Spring Boot auto-configuration
  205. ├── server2mcp-spring-boot-starters/
  206. │ ├── server2mcp-starter-webmvc # ✅ Full endpoint wiring (JSON-RPC + SSE + HTTP)
  207. │ └── server2mcp-starter-webflux # ✅ Reactive endpoint wiring — full protocol parity with WebMVC
  208. └── server2mcp-test # ✅ Demo app + 21/21 e2e verification
  209. ```
  210. ---
  211. ## 🤔 When to use api2mcp4j?
  212. | ✅ Use it for | ❌ Don't use it for |
  213. |---|---|
  214. | Exposing internal REST APIs to AI agents quickly | Greenfield MCP-first projects (use Spring AI MCP directly) |
  215. | Wrapping legacy controllers as MCP tools | Real-time streaming / SSE-only UIs |
  216. | Multi-agent systems sharing tool definitions | Apps that don't already use Spring Boot |
  217. | Prototyping AI features on production services | Tiny prototypes (overhead not worth it) |
  218. ---
  219. ## 🆚 Comparison
  220. | Feature | api2mcp4j | Spring AI MCP Official | Manual `@Tool` everywhere |
  221. |---|---|---|---|
  222. | Code changes required | **Minimal (config only)** | Medium–High | High |
  223. | Auto-discover from `@RestController` | ✅ | ❌ | ❌ |
  224. | 5-parser chain (Swagger + Javadoc + …) | ✅ | Limited | Manual |
  225. | Non-intrusive | ★★★★★ | ★★★ | ★☆ |
  226. | Protocol 2026-07-28 (RPC + wire) | ✅ 100% | 🟡 partial | ⚪ |
  227. | MRTR multi-round | ✅ with decorator | ⚪ | ⚪ |
  228. | SSE long-poll + Last-Event-ID | ✅ built-in | 🟡 via SDK | ❌ |
  229. | W3C traceparent (SEP-414) | ✅ auto-minted | ❌ | ❌ |
  230. | Best for existing projects | ✅ | New apps | Tiny demos |
  231. ---
  232. ## 📚 Documentation
  233. - 📘 **Full docs site** → https://theeterna.github.io/server2mcp-docs/
  234. - 📊 **Protocol 2026-07-28 integration matrix** → [docs/mcp-2026-07-28-INTEGRATION-MATRIX.md](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md)
  235. - 🏗️ **Architecture** → [docs/reference/architecture.md](docs/reference/architecture.md)
  236. - 🧩 **Extension points** (custom parsers / filters / context) → [docs/reference/extension-points.md](docs/reference/extension-points.md)
  237. - 🚶 **Onboarding (3-step)** → [docs/reference/onboarding.md](docs/reference/onboarding.md)
  238. - 📐 **Specs (registration / file header / test / work log)** → [docs/specs/](docs/specs/)
  239. - ⚖️ **Global rules** → [docs/rules/](docs/rules/)
  240. - 📜 **Work logs (audit trail)** → [docs/logs/](docs/logs/)
  241. ---
  242. ## 🤝 Contributing
  243. Issues, PRs, and ⭐ are very welcome.
  244. This is a young project — your feedback shapes its future.
  245. Before submitting a PR, please read:
  246. - [docs/specs/REGISTRATION_DISCIPLINE_SPEC.md](docs/specs/REGISTRATION_DISCIPLINE_SPEC.md) — the 6-dimension Rubric for new MCP entities
  247. - [docs/rules/global/destructive-deletion.md](docs/rules/global/destructive-deletion.md) — multi-source verification before deleting public APIs
  248. - [docs/rules/global/work-log.md](docs/rules/global/work-log.md) — reportable outputs land in `docs/logs/`
  249. ---
  250. ## 📄 License
  251. [Apache License 2.0](LICENSE)
  252. ---
  253. ## 🗓️ Roadmap
  254. - [x] Protocol 2026-07-28 wire & JSON-RPC routing (2026-08-03)
  255. - [x] MRTR multi-round state machine + 8-round guard
  256. - [x] SSE long-poll with Last-Event-ID resume
  257. - [x] W3C traceparent auto-mint
  258. - [x] WebFlux starter endpoint wiring (parity with WebMVC) (2026-10-27)
  259. - [ ] Publish to Maven Central — artifacts built, signed, and audited; awaiting Central Portal credentials
  260. - [ ] OTel SDK real instrumentation (currently wire-format only)
  261. - [ ] Multi-tenant isolation (`@McpTool(tenant = "...")`)
  262. - [ ] SDK ≥ 3.0.0 native router migration (tracked by `scripts/trigger-phase3.sh`)
  263. ---
  264. <p align="center">
  265. <sub>Built with care by <a href="https://github.com/TheEterna">Han</a> · Apache 2.0 · 100% protocol 2026-07-28 compatible</sub>
  266. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.