api2mcp4j
Turn your existing Spring Boot REST controllers into MCP (Model Context Protocol) tools — no rewrites, no @Tool everywhere.
<dependency>
<groupId>io.github.theeterna</groupId>
<artifactId>server2mcp-starter-webmvc</artifactId>
<version>1.2.0</version>
</dependency>
English · 中文 · Docs · Integration Matrix
Why api2mcp4j?
Most MCP integrations force you to:
- Add
@Tool/@McpToolto 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.
// 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
🚀 Quick Start (≈ 3 minutes)
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>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:
<dependency>
<groupId>io.github.theeterna</groupId>
<artifactId>server2mcp-starter-webflux</artifactId>
<version>1.2.0</version>
</dependency>
3. Configure
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
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)
Wire JSON fields — 100% reachable
✅ 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:
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
🧪 Testing & Verification
Test philosophy: TDD double-commit — [RED] test first, then [GREEN] implementation. See 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 │
└────────────────────┘
📦 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?
🆚 Comparison
📚 Documentation
- 📘 Full docs site → https://theeterna.github.io/server2mcp-docs/
- 📊 Protocol 2026-07-28 integration matrix → docs/mcp-2026-07-28-INTEGRATION-MATRIX.md
- 🏗️ Architecture → docs/reference/architecture.md
- 🧩 Extension points (custom parsers / filters / context) → docs/reference/extension-points.md
- 🚶 Onboarding (3-step) → docs/reference/onboarding.md
- 📐 Specs (registration / file header / test / work log) → docs/specs/
- ⚖️ Global rules → docs/rules/
- 📜 Work logs (audit trail) → 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 — the 6-dimension Rubric for new MCP entities
- docs/rules/global/destructive-deletion.md — multi-source verification before deleting public APIs
- docs/rules/global/work-log.md — reportable outputs land in
docs/logs/
📄 License
🗓️ Roadmap
- Protocol 2026-07-28 wire & JSON-RPC routing (2026-08-03)
- MRTR multi-round state machine + 8-round guard
- SSE long-poll with Last-Event-ID resume
- W3C traceparent auto-mint
- 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)
