Server2MCP Spring Boot Starter

api2mcp4j

既存の Spring Boot REST コントローラーを MCP（Model Context Protocol）ツールに変換できます。全面的な書き換えも、あらゆる箇所への @Tool 追加も不要です。

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

English · 中文 · Docs · Integration Matrix

---

api2mcp4j を選ぶ理由

ほとんどの MCP 統合では、次の作業が必要になります。

• すべてのメソッドに @Tool／@McpTool を追加する
• ビジネスロジックを並行する「MCP」用コードパスに重複して実装する
• ツールの説明を別途管理する

api2mcp4j は既存の @RestController Bean をスキャンし、そのメソッドを MCP ツールとして公開します。つまり、ビジネスコードの変更は一切不要です。MyBatis-Plus が MyBatis を拡張するように、api2mcp4j は 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

---

✨ 主な機能

🎯 非侵襲的	interface スコープですべてのコントローラーを自動登録。@Tool アノテーションは不要です
🔍 5 段階のパーサーチェーン	Swagger v3／Swagger v2／Javadoc／Spring MVC／Jackson／Spring AI の中から最適な説明を採用します
🛠️ MCP を完全にカバー	ツール／リソース／プロンプト／補完／入力要求／サンプリング／ルート
🆕 プロトコル 2026-07-28	ワイヤースキーマ＋JSON-RPC ルーティング＋SSE ロングポーリング＋MRTR＋OTel traceparent に 100% 対応
🔌 カスタムパーサー	AbstractDesParser／AbstractParamParser を実装して、チェーンに追加できます
🧪 TDD の徹底	JUnit5、2 段階のコミット [RED]、続いて [GREEN]。600 件のテストがすべて成功
🚀 すぐに開始	mvn spring-boot:run → MCP エンドポイントが利用可能になります

---

🚀 クイックスタート（約 3 分）

1. クローンしてビルド

git clone https://github.com/TheEterna/api2mcp4j.git
cd api2mcp4j
mvn clean install -DskipTests

2. Spring Boot プロジェクトに追加

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

3. 設定

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. 起動してテスト

mvn spring-boot:run

MCP サーバーは http://localhost:8080/mcp/jsonrpc で利用できます（HTTP フォールバックは /mcp/discover、/mcp/tasks、/mcp/sse です）。

---

📡 MCP Protocol 2026-07-28 — 100% 互換

api2mcp4j は、Java MCP SDK 2.0 が 2025-11-25 のワイヤーしか実装していないにもかかわらず、2026-07-28 に完全対応してリリースされた初の Java MCP フレームワークです。カスタム JSON-RPC ルーター、SSE コントローラー、ワイヤースキーマを実装することで SDK の制限を回避しました。SDK のアップグレード互換性も損なっていません（SDK ≥ 3.0.0 がリリースされるまでは、コントローラーがフォールバックとして機能します）。

8 つの RPC ルート、すべて実装済み（HTTP シミュレーションではありません）

RPC	JSON-RPC エンドポイント	SSE ロングポーリング	ソース
server/discover	✅ POST /mcp/jsonrpc	—	DiscoverEndpoint
tasks/create	✅	—	TaskStore
tasks/get／list／cancel	✅	—	TasksEndpoint
tasks/augmented-prompt	✅	—	AugmentedPromptEndpoint
subscriptions/listen	✅（ポーリング）	✅ GET /mcp/sse + Last-Event-ID + 15s ハートビート	SseNotificationsController
input_required/respond（MRTR）	✅ エンベロープ	—	MrtrToolCallbackWrapper

Wire JSON フィールド — 到達率 100%

2026-07-28 フィールド	ステータス	場所
tools.listChanged / resources.listChanged / prompts.listChanged	✅ SDK ネイティブ	WireSchemaExporter.syncAll()
tools.subscription / completions.listChanged (2026-07-28 に新規追加)	✅ カスタム wire	WireServerCapabilities
experimental.io.modelcontextprotocol/tasks (新規)	✅ カスタム wire	同上
_meta.resultType / ttlMs / cacheScope / cacheWrapperKey	✅ meta map 経由で自動注入	@McpTool(...) + McpCallToolResultConverter
_meta.taskHandle / inputRequests / requestState	✅ 自動認識	InputRequiredResult / TaskHandle の戻り値
_meta.traceparent / tracestate / baggage (W3C SEP-414)	✅ JSON-RPC で自動生成	MetaUtils
MRTR ステートマシン（ラウンド間マージ + 8 ラウンドガード）	✅	MrtrDriver
outputSchema	✅ SDK フィールド	McpSchema.Tool.builder().outputSchema()
Capabilities のヘルスチェック / 差分 / wire 検証	✅	CapabilitiesHealth + SnapshotCompareTool + WireSchemaValidator

統合マトリックス全文 →

---

✅ 1 行で検証

デモアプリは H2 インメモリ DB（外部依存関係ゼロ）で起動し、実際の HTTP/SSE wire に対して 2026-07-28 のすべての機能を検証します。

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

証拠ログ →

---

🧪 テストと検証

レイヤー	件数	ステータス
ユニットテスト（server2mcp-core）	575	✅ すべて成功
統合テスト（server2mcp-starter-webmvc）	22	✅ すべて成功
デモテスト（server2mcp-test）	3	✅ すべて成功
エンドツーエンド curl 検証	21/21	✅
合計	600+ テスト、21/21 e2e	✅

テストの方針：TDD ダブルコミット — まず [RED] テストを作成し、次に [GREEN] 実装を行います。詳しくは docs/specs/TEST_SPEC.md をご覧ください。

---

🏗️ アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│ 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 │
            └────────────────────┘

アーキテクチャの詳細 →

---

📦 モジュール

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

---

🤔 api2mcp4j はどのような場合に使いますか？

✅ 適した用途	❌ 適さない用途
内部 REST API を AI エージェントにすばやく公開する	MCP を前提としたグリーンフィールドプロジェクト（Spring AI MCP を直接使用してください）
レガシーコントローラーを MCP ツールとしてラップする	リアルタイムストリーミング / SSE 専用 UI
複数のエージェントシステムでツール定義を共有する	Spring Boot をまだ使用していないアプリ
本番サービス上で AI 機能のプロトタイプを作成する	小規模なプロトタイプ（オーバーヘッドに見合いません）

---

🆚 比較

機能	api2mcp4j	Spring AI MCP Official	手動で @Tool を設定
必要なコード変更	最小限（設定のみ）	中〜大	大
@RestController から自動検出	✅	❌	❌
5 種類のパーサーチェーン（Swagger + Javadoc + …）	✅	限定的	手動
非侵襲性	★★★★★	★★★	★☆
Protocol 2026-07-28（RPC + wire）	✅ 100%	🟡 一部対応	⚪
MRTR マルチラウンド	✅ デコレーター付き	⚪	⚪
SSE ロングポーリング + Last-Event-ID	✅ 組み込み	🟡 SDK 経由	❌
W3C traceparent（SEP-414）	✅ 自動生成	❌	❌
既存プロジェクトに最適	✅	新規アプリ	小規模なデモ

---

📚 ドキュメント

• 📘 ドキュメントサイト全文 → https://theeterna.github.io/server2mcp-docs/
• 📊 Protocol 2026-07-28 統合マトリックス → docs/mcp-2026-07-28-INTEGRATION-MATRIX.md
• 🏗️ アーキテクチャ → docs/reference/architecture.md
• 🧩 拡張ポイント（カスタムパーサー／フィルター／コンテキスト） → docs/reference/extension-points.md
• 🚶 オンボーディング（3 ステップ） → docs/reference/onboarding.md
• 📐 仕様（登録／ファイルヘッダー／テスト／作業ログ） → docs/specs/
• ⚖️ 全体ルール → docs/rules/
• 📜 作業ログ（監査証跡） → docs/logs/

---

🤝 コントリビューション

Issue、PR、⭐ を歓迎します。
このプロジェクトはまだ始まったばかりです。皆さんのフィードバックが今後の方向性を形作ります。

PR を提出する前に、以下をお読みください。

• docs/specs/REGISTRATION_DISCIPLINE_SPEC.md — 新しい MCP エンティティ向けの 6 つの評価基準
• docs/rules/global/destructive-deletion.md — パブリック API を削除する前の複数ソースによる検証
• docs/rules/global/work-log.md — 報告対象の成果物は docs/logs/ に記録します

---

📄 ライセンス

Apache License 2.0

---

🗓️ ロードマップ

• Protocol 2026-07-28 のワイヤー形式と JSON-RPC ルーティング（2026-08-03）
• MRTR マルチラウンド状態機械 + 8 ラウンド制限
• Last-Event-ID による再開に対応した SSE ロングポーリング
• W3C traceparent の自動生成
• WebFlux スターターのエンドポイント接続（WebMVC と同等）
• Maven Central への公開
• OTel SDK による実計装（現在はワイヤー形式のみ）
• マルチテナント分離（@McpTool(tenant = "...")）
• SDK ≥ 3.0.0 のネイティブルーターへの移行（scripts/trigger-phase3.sh で追跡）

---

_{Han が心を込めて開発 · Apache 2.0 · Protocol 2026-07-28 に 100% 準拠}