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.
Badge for your README
Markdown
[](/listings/theeterna--api2mcp4j)HTML
<a href="/listings/theeterna--api2mcp4j"><img src="/api/listings/theeterna--api2mcp4j/badge.svg" alt="findsafeskills safety rating" /></a>Install
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, SWAGGER34. 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.
- # api2mcp4j
- **Turn your existing Spring Boot REST controllers into MCP (Model Context Protocol) tools — no rewrites, no `@Tool` everywhere.**
- ```xml
- <dependency>
- <groupId>io.github.theeterna</groupId>
- <artifactId>server2mcp-starter-webmvc</artifactId>
- <version>1.2.0</version>
- </dependency>
- ```
- <!-- Reactive (WebFlux) users swap the artifactId to `server2mcp-starter-webflux` — same protocol surface. -->
- [](https://www.java.com)
- [](https://spring.io/projects/spring-boot)
- [](https://spring.io/projects/spring-ai)
- [](https://modelcontextprotocol.io)
- [](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md)
- [](#-testing--verification)
- [](#-one-line-verification)
- [](LICENSE)
- [English](README.md) · [中文](README_zh.md) · [Docs](https://docs.xiaohan.chat/) · [Integration Matrix](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md)
- ---
- ## Why api2mcp4j?
- Most MCP integrations force you to:
- - Add `@Tool` / `@McpTool` to every method
- - Duplicate business logic into a parallel "MCP" code path
- - Maintain separate tool descriptions
- **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.
- ```java
- // Your existing controller — unchanged
- @RestController
- public class OrderController {
- @GetMapping("/orders/{id}")
- public Order getOrder(@PathVariable Long id) { ... }
- }
- // Becomes an MCP tool: OrderController_getOrder
- // With auto-generated description from Swagger / Javadoc / Spring MVC / Jackson / Spring AI
- ```
- ---
- ## ✨ Key Features
- | | |
- |---|---|
- | 🎯 **Non-intrusive** | `interface` scope auto-registers all controllers; no `@Tool` annotation needed |
- | 🔍 **5-parser chain** | Swagger v3 / Swagger v2 / Javadoc / Spring MVC / Jackson / Spring AI — best description wins |
- | 🛠️ **Full MCP coverage** | Tools / Resources / Prompts / Completions / Elicitation / Sampling / Roots |
- | 🆕 **Protocol 2026-07-28** | Wire schema + JSON-RPC routing + SSE long-poll + MRTR + OTel traceparent — 100% |
- | 🔌 **Custom parsers** | Implement `AbstractDesParser` / `AbstractParamParser`, plug into the chain |
- | 🧪 **TDD discipline** | JUnit5, double commit `[RED]` then `[GREEN]`, 600 tests all green |
- | 🚀 **Quick start** | `mvn spring-boot:run` → MCP endpoint ready |
- ---
- ## 🚀 Quick Start (≈ 3 minutes)
- ### 1. Clone & build
- ```bash
- git clone https://github.com/TheEterna/api2mcp4j.git
- cd api2mcp4j
- mvn clean install -DskipTests
- ```
- ### 2. Add to your Spring Boot project
- ```xml
- <dependency>
- <groupId>io.github.theeterna</groupId>
- <artifactId>server2mcp-starter-webmvc</artifactId>
- <version>1.2.0</version>
- </dependency>
- ```
- Reactive (Spring WebFlux) applications use the WebFlux starter instead — identical protocol surface, reactive transport:
- ```xml
- <dependency>
- <groupId>io.github.theeterna</groupId>
- <artifactId>server2mcp-starter-webflux</artifactId>
- <version>1.2.0</version>
- </dependency>
- ```
- ### 3. Configure
- ```yaml
- plugin:
- mcp:
- enabled: true
- scope: interface # 'interface' = auto-register all controllers; 'custom' = @ToolScan only
- parser:
- des: MCPTOOL, JAVADOC, TOOL, JACKSON, SWAGGER3, SWAGGER2
- param: MCPTOOL, JAVADOC, TOOL, SpringMVC, JACKSON, SWAGGER2, SWAGGER3
- strict: false # true = a misspelled parser name aborts startup (default: warn only)
- ```
- ### 4. Start & test
- ```bash
- 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`).
- ---
- ## 📡 MCP Protocol 2026-07-28 — 100% Compatible
- 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).
- ### 8 RPC routes, all real (not HTTP simulations)
- | RPC | JSON-RPC endpoint | SSE long-poll | Source |
- |---|---|---|---|
- | `server/discover` | ✅ `POST /mcp/jsonrpc` | — | [`DiscoverEndpoint`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#二servercapabilities握手声明) |
- | `tasks/create` | ✅ | — | [`TaskStore`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#五新增-rpc-方法) |
- | `tasks/get` / `list` / `cancel` | ✅ | — | [`TasksEndpoint`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#五新增-rpc-方法) |
- | `tasks/augmented-prompt` | ✅ | — | [`AugmentedPromptEndpoint`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#五新增-rpc-方法) |
- | `subscriptions/listen` | ✅ (poll) | ✅ `GET /mcp/sse` + Last-Event-ID + 15s heartbeat | [`SseNotificationsController`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#五新增-rpc-方法) |
- | `input_required/respond` (MRTR) | ✅ envelope | — | [`MrtrToolCallbackWrapper`](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md#五新增-rpc-方法) |
- ### Wire JSON fields — 100% reachable
- | 2026-07-28 field | Status | Where |
- |---|---|---|
- | `tools.listChanged` / `resources.listChanged` / `prompts.listChanged` | ✅ SDK native | `WireSchemaExporter.syncAll()` |
- | `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) |
- | `experimental.io.modelcontextprotocol/tasks` *(new)* | ✅ Custom wire | Same |
- | `_meta.resultType` / `ttlMs` / `cacheScope` / `cacheWrapperKey` | ✅ Auto-injected via meta map | `@McpTool(...)` + `McpCallToolResultConverter` |
- | `_meta.taskHandle` / `inputRequests` / `requestState` | ✅ Auto-recognized | `InputRequiredResult` / `TaskHandle` return values |
- | `_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) |
- | MRTR state machine (cross-round merge + 8-round guard) | ✅ | [`MrtrDriver`](server2mcp-core/src/main/java/com/ai/plug/core/spec/mrtr/MrtrDriver.java) |
- | `outputSchema` | ✅ SDK field | `McpSchema.Tool.builder().outputSchema()` |
- | Capabilities health / diff / wire validation | ✅ | `CapabilitiesHealth` + `SnapshotCompareTool` + `WireSchemaValidator` |
- **[Full integration matrix →](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md)**
- ---
- ## ✅ One-line verification
- 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:
- ```bash
- cd server2mcp-test && mvn spring-boot:run # starts on :8888 (H2 in-memory)
- # In another shell:
- bash scripts/verify-protocol-2026-07-28.sh http://localhost:8888
- ```
- ```
- == 0. liveness == ✓ actuator reachable
- == 1. server/discover (JSON-RPC) == ✓×7 (jsonrpc=2.0, preferredVersion=2026-07-28,
- tools.listChanged, tools.subscription,
- completions.listChanged, experimental.tasks,
- _meta.traceparent)
- == 2. tasks/* (JSON-RPC) == ✓×5 (create, get, list, cancel full lifecycle)
- == 3. tasks/augmented-prompt == ✓×1
- == 4. subscriptions/listen == ✓×3 (HTTP poll + text/event-stream + connected)
- == 5. input_required/respond == ✓×2 (accepted + state echo)
- == 6. HTTP legacy endpoints == ✓×2 (/mcp/discover + /mcp/notifications)
- == summary == passed: 21 / failed: 0
- ALL ASSERTIONS PASSED — protocol 2026-07-28 wire verified
- ```
- **[Evidence log →](docs/logs/2026-08-03_ceo_demo-end-to-end-21of21.md)**
- ---
- ## 🧪 Testing & Verification
- | Layer | Count | Status |
- |---|---|---|
- | Unit tests (`server2mcp-core`) | 575 | ✅ all green |
- | Integration tests (`server2mcp-starter-webmvc`) | 22 | ✅ all green |
- | Demo tests (`server2mcp-test`) | 3 | ✅ all green |
- | **End-to-end curl verification** | **21/21** | **✅** |
- | Total | **600+ tests, 21/21 e2e** | **✅** |
- Test philosophy: **TDD double-commit** — `[RED]` test first, then `[GREEN]` implementation. See [`docs/specs/TEST_SPEC.md`](docs/specs/TEST_SPEC.md).
- ---
- ## 🏗️ Architecture
- ```
- ┌─────────────────────────────────────────────────────────────┐
- │ Spring Boot Application │
- │ │
- │ ┌─── Your existing code (unchanged) ───┐ │
- │ │ @RestController │ │
- │ │ @Service │ │
- │ │ @Component │ │
- │ └────────────────┬─────────────────────┘ │
- │ │ │
- │ ┌────────────────▼─────────────────────┐ │
- │ │ api2mcp4j framework │ │
- │ │ │ │
- │ │ Scanner ──→ Parser chain ──→ Provider │
- │ │ │ │ │ │
- │ │ Spring MVC 5 parsers SyncMcpToolMethodCallback │
- │ │ discovery (Swagger2/3, (template method) │
- │ │ Javadoc, │
- │ │ Jackson, │
- │ │ Spring AI) │
- │ │ │ │
- │ │ ── 2026-07-28 layer (new) ── │
- │ │ • JsonRpcRouter + JsonRpcRoutes │
- │ │ • WireServerCapabilities + JsonExporter │
- │ │ • SseNotificationsController │
- │ │ • MrtrDriver + MrtrSessionStore │
- │ │ • MrtrToolCallbackWrapper │
- │ │ • MetaUtils (W3C traceparent mint) │
- │ └────────────────┬─────────────────────┘ │
- │ │ │
- │ ┌────────────────▼─────────────────────┐ │
- │ │ Spring AI MCP SDK 2.0 │ │
- │ │ (McpSyncServer / McpAsyncServer) │ │
- │ └────────────────┬─────────────────────┘ │
- └────────────────────┼────────────────────────────────────────┘
- │ wire: JSON-RPC 2.0 + SSE
- ▼
- ┌────────────────────┐
- │ MCP Clients │
- │ • Claude Desktop │
- │ • Cursor / Cline │
- │ • Your BFF / Agent │
- └────────────────────┘
- ```
- **[Detailed architecture →](docs/reference/architecture.md)**
- ---
- ## 📦 Modules
- ```
- api2mcp4j/
- ├── server2mcp-common # Constants & utilities
- ├── server2mcp-core # Core engine: annotations, scanners, callbacks, providers
- │ ├── com.ai.plug.core.annotation.* # @McpTool, @McpResource, @McpPrompt, @McpArg
- │ ├── com.ai.plug.core.parser.* # 5-parser chain (des + param)
- │ ├── com.ai.plug.core.callback.* # Sync + Async template methods
- │ ├── com.ai.plug.core.spec.* # 2026-07-28 wire layer
- │ └── com.ai.plug.core.provider.* # Spring AI bridge
- ├── server2mcp-autoconfigure # Spring Boot auto-configuration
- ├── server2mcp-spring-boot-starters/
- │ ├── server2mcp-starter-webmvc # ✅ Full endpoint wiring (JSON-RPC + SSE + HTTP)
- │ └── server2mcp-starter-webflux # ✅ Reactive endpoint wiring — full protocol parity with WebMVC
- └── server2mcp-test # ✅ Demo app + 21/21 e2e verification
- ```
- ---
- ## 🤔 When to use api2mcp4j?
- | ✅ Use it for | ❌ Don't use it for |
- |---|---|
- | Exposing internal REST APIs to AI agents quickly | Greenfield MCP-first projects (use Spring AI MCP directly) |
- | Wrapping legacy controllers as MCP tools | Real-time streaming / SSE-only UIs |
- | Multi-agent systems sharing tool definitions | Apps that don't already use Spring Boot |
- | Prototyping AI features on production services | Tiny prototypes (overhead not worth it) |
- ---
- ## 🆚 Comparison
- | Feature | api2mcp4j | Spring AI MCP Official | Manual `@Tool` everywhere |
- |---|---|---|---|
- | Code changes required | **Minimal (config only)** | Medium–High | High |
- | Auto-discover from `@RestController` | ✅ | ❌ | ❌ |
- | 5-parser chain (Swagger + Javadoc + …) | ✅ | Limited | Manual |
- | Non-intrusive | ★★★★★ | ★★★ | ★☆ |
- | Protocol 2026-07-28 (RPC + wire) | ✅ 100% | 🟡 partial | ⚪ |
- | MRTR multi-round | ✅ with decorator | ⚪ | ⚪ |
- | SSE long-poll + Last-Event-ID | ✅ built-in | 🟡 via SDK | ❌ |
- | W3C traceparent (SEP-414) | ✅ auto-minted | ❌ | ❌ |
- | Best for existing projects | ✅ | New apps | Tiny demos |
- ---
- ## 📚 Documentation
- - 📘 **Full docs site** → https://theeterna.github.io/server2mcp-docs/
- - 📊 **Protocol 2026-07-28 integration matrix** → [docs/mcp-2026-07-28-INTEGRATION-MATRIX.md](docs/mcp-2026-07-28-INTEGRATION-MATRIX.md)
- - 🏗️ **Architecture** → [docs/reference/architecture.md](docs/reference/architecture.md)
- - 🧩 **Extension points** (custom parsers / filters / context) → [docs/reference/extension-points.md](docs/reference/extension-points.md)
- - 🚶 **Onboarding (3-step)** → [docs/reference/onboarding.md](docs/reference/onboarding.md)
- - 📐 **Specs (registration / file header / test / work log)** → [docs/specs/](docs/specs/)
- - ⚖️ **Global rules** → [docs/rules/](docs/rules/)
- - 📜 **Work logs (audit trail)** → [docs/logs/](docs/logs/)
- ---
- ## 🤝 Contributing
- Issues, PRs, and ⭐ are very welcome.
- This is a young project — your feedback shapes its future.
- Before submitting a PR, please read:
- - [docs/specs/REGISTRATION_DISCIPLINE_SPEC.md](docs/specs/REGISTRATION_DISCIPLINE_SPEC.md) — the 6-dimension Rubric for new MCP entities
- - [docs/rules/global/destructive-deletion.md](docs/rules/global/destructive-deletion.md) — multi-source verification before deleting public APIs
- - [docs/rules/global/work-log.md](docs/rules/global/work-log.md) — reportable outputs land in `docs/logs/`
- ---
- ## 📄 License
- [Apache License 2.0](LICENSE)
- ---
- ## 🗓️ Roadmap
- - [x] Protocol 2026-07-28 wire & JSON-RPC routing (2026-08-03)
- - [x] MRTR multi-round state machine + 8-round guard
- - [x] SSE long-poll with Last-Event-ID resume
- - [x] W3C traceparent auto-mint
- - [x] WebFlux starter endpoint wiring (parity with WebMVC) (2026-10-27)
- - [ ] Publish to Maven Central — artifacts built, signed, and audited; awaiting Central Portal credentials
- - [ ] OTel SDK real instrumentation (currently wire-format only)
- - [ ] Multi-tenant isolation (`@McpTool(tenant = "...")`)
- - [ ] SDK ≥ 3.0.0 native router migration (tracked by `scripts/trigger-phase3.sh`)
- ---
- <p align="center">
- <sub>Built with care by <a href="https://github.com/TheEterna">Han</a> · Apache 2.0 · 100% protocol 2026-07-28 compatible</sub>
- </p>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.