api2mcp4j

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

  com.ai.plug
  server2mcp-starter-webmvc
  1.1.4-SNAPSHOT

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

---

🚀 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

  com.ai.plug
  server2mcp-starter-webmvc
  1.1.4-SNAPSHOT

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)

Wire JSON fields — 100% reachable

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

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?

---

🆚 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

Apache License 2.0

---

🗓️ 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
• [ ] 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