api2mcp4j

Turn your existing Spring Boot REST controllers into MCP (Model Context Protocol) tools — no rewrites, no @Tool everywhere.

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

English · 中文 · Docs · Integration Matrix

---

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.

// Your existing controller — unchanged
@RestController
public class OrderController {
    @GetMapping("/orders/{id}")
    public Order getOrder(@PathVariable Long id) { ... }
}

// Becomes an MCP tool: orders_get_order
// 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

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).

---

📡 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
tasks/create	✅	—	TaskStore
tasks/get / list / cancel	✅	—	TasksEndpoint
tasks/augmented-prompt	✅	—	AugmentedPromptEndpoint
subscriptions/listen	✅ (poll)	✅ GET /mcp/sse + Last-Event-ID + 15s heartbeat	SseNotificationsController
input_required/respond (MRTR)	✅ envelope	—	MrtrToolCallbackWrapper

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
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
MRTR state machine (cross-round merge + 8-round guard)	✅	MrtrDriver
outputSchema	✅ SDK field	McpSchema.Tool.builder().outputSchema()
Capabilities health / diff / wire validation	✅	CapabilitiesHealth + SnapshotCompareTool + WireSchemaValidator

Full integration matrix →

---

✅ 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

Evidence log →

---

🧪 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.

---

🏗️ 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 →

---

📦 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     # ⚠️ Framework core only (no endpoint wiring yet)
└── 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
• 🏗️ 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

Apache License 2.0

---

🗓️ 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)
• Publish to Maven Central
• 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)

---

_{Built with care by Han · Apache 2.0 · 100% protocol 2026-07-28 compatible}