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 · 中文 · 文档 · 集成矩阵

---

为什么选择 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	工具 / 资源 / 提示词 / 补全 / 引导 / 采样 / 根目录
🆕 Protocol 2026-07-28	Wire schema + JSON-RPC 路由 + SSE 长轮询 + MRTR + OTel traceparent——100%
🔌 自定义解析器	实现 AbstractDesParser / AbstractParamParser，接入解析链
🧪 TDD 规范	JUnit5，双提交 [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 是首个完整支持 2026-07-28 的 Java MCP 框架，尽管 Java MCP SDK 2.0 仅实现了 2025-11-25 wire。我们通过自定义 JSON-RPC 路由器、SSE 控制器和 wire schema 绕过了 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）	✅ envelope	—	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()
能力健康检查 / 差异比较 / wire 验证	✅	CapabilitiesHealth + SnapshotCompareTool + WireSchemaValidator

完整集成矩阵 →

---

✅ 一行验证

演示应用使用 H2 内存数据库启动（无外部依赖），并通过真实的 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 项端到端测试	✅

测试理念：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 Agent	从零开始、以 MCP 为先的项目（直接使用 Spring AI MCP）
将旧版控制器封装为 MCP 工具	实时流式传输 / 仅支持 SSE 的 UI
多 Agent 系统共享工具定义	尚未使用 Spring Boot 的应用
在生产服务中试验 AI 功能	小型原型（开销不值得）

---

🆚 对比

功能	api2mcp4j	Spring AI MCP Official	到处手动使用 @Tool
所需代码更改	极少（仅配置）	中到多	多
从 @RestController 自动发现	✅	❌	❌
5 解析器链（Swagger + Javadoc + …）	✅	有限	手动
非侵入式	★★★★★	★★★	★☆
协议 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 starter 端点接线（与 WebMVC 保持一致）
• 发布到 Maven Central
• OTel SDK 实际埋点（目前仅支持线路格式）
• 多租户隔离（@McpTool(tenant = "...")）
• 迁移到 SDK ≥ 3.0.0 原生路由器（由 scripts/trigger-phase3.sh 跟踪）

---

_{由 Han 用心打造 · Apache 2.0 · 100% 兼容 protocol 2026-07-28}