Server2MCP Spring Boot Starter について
api2mcp4j（Server2MCP Spring Boot Starter）は、既存の Spring Boot の @RestController のメソッドを、業務コードに @Tool アノテーションを追加せずに MCP ツールとして公開します。既存の Spring Boot サービスを持つ Java チーム向けで、Spring AI MCP を基盤としています。
主な機能
- 01@RestController の自動スキャンとツール登録
- 02ツール説明を生成するパーサーチェーン
- 03ツール、リソース、プロンプトへの対応
- 04プロトコル 2026-07-28 のルーティング
- 05カスタム説明文・パラメーター用パーサー
活用シーン
- 01レガシーな REST コントローラーの MCP ツール化
- 02既存の API 定義を複数のエージェントで共有
- 03既存サービス上での AI 機能の試作
MCP 対応
本プロジェクトは Spring Boot ベースの MCP サーバーフレームワークであり、REST コントローラーのメソッドをツール、リソース、プロンプトとして MCP クライアントに公開します。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
インストール方法は未掲載です
このサーバーのパッケージやリモートエンドポイントはまだ取得できていません。プロジェクトの README の手順に従ってください。
ツール
ツール一覧はまだ取得されていません
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
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/に記録します
📄 ライセンス
🗓️ ロードマップ
- 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% 準拠
コメント
Markdown 対応
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。