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

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

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)                    │
│   └────────────────┬─────────────────────┘                  │
│                    │