SpringBoot3 + OpenSpec 实现 MCP 服务器实践

四、Proposal：设计提案

提示词模板

我想用 SpringBoot3 + SSE 实现一个 MCP 服务器 Demo，帮我创建一个提案。 需求： - 实现 Tools 能力（initialize、tools/list、tools/call） - 提供一个示例工具：查询日程（get_calendar_events） - 代码结构清晰，便于演示 

技术选型决策

传输层选型

最初考虑了三种方案：Stdio、WebSocket、SSE。

• Stdio 最简单，官方示例都用这个，但我们的项目是 Web 应用，集成起来不够自然
• WebSocket 功能最强，双向通信，但实现相对复杂
• SSE 基于 HTTP 长连接，实现简单，也符合 MCP 的推送模式

本示例项目使用 SSE 方案。

核心抽象设计

MCP 协议定义了多种能力，本 Demo 先聚焦 Tools（工具）。工具是 AI 可调用的函数，后续可根据需求扩展。

协议方法

初步确定实现以下方法：

initialize - 初始化握手，协商协议版本
tools/list - 返回所有可用工具
tools/call - 执行指定工具 

五、Tasks：任务拆分

提示词模板

基于上面的提案，帮我拆解成具体的开发任务。 

第一次拆解

根据提案，把开发拆成以下任务：

六、Design：详细设计

提示词模板

基于任务列表，帮我做详细设计：类结构、核心接口、数据流转。 

整体架构

AI Client │ SSE │ ┌─────────────────────────────────────┐ │ SpringBoot Server │ │ │ │ ┌─────────────────────────────┐ │ │ │ MCP Protocol Handler │ │ │ └─────────────────────────────┘ │ │ │ │ │ ┌───────────────┼───────────────┐ │ │ ▼ ▼ ▼ │ │ Tool Registry Resource Registry Prompt │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ 工具实现 资源实现 提示实现 │ └─────────────────────────────────────┘ 

类设计思考

协议层

• JsonRpcRequest / JsonRpcResponse - 纯粹的 POJO，只做序列化/反序列化
• McpHandler - 负责请求路由，不关心传输细节

注册中心

• ToolRegistry - 工具注册中心，利用 Spring 的 List<Tool> 自动注入
• 这样的好处是新增工具只需写一个类，不用改配置

Controller

• 接收 HTTP POST 请求
• 返回 SseEmitter 实现服务端推送
• 超时时间设为 60 秒

工具接口设计

public interface McpTool {
    String getName(); // 工具名字
    String getDescription(); // 描述，告诉 AI 什么时候用它
    Map<String, Object> getInputSchema(); // 参数格式
    String execute(Map<String, Object> arguments); // 执行逻辑
}

七、Implementation：实现

提示词模板

按照设计文档，实现以下功能： 1. JSON-RPC 协议模型（JsonRpcRequest、JsonRpcResponse） 2. 协议处理器（initialize、tools/list、tools/call） 3. SSE Controller（SseEmitter） 4. Tool 接口和注册中心 5. 日程查询工具（GetCalendarEventsTool），根据日期查询日程 使用 SpringBoot3 + Spring Web，用 @Component、@Autowired 进行依赖注入。 

以下代码均由 AI 根据提案相关内容生成，此处主要为了方便理解贴出了部分关键代码。

7.1 项目初始化

用 start.spring.io 生成项目骨架，添加了 Spring Web 依赖。

7.2 JSON-RPC 协议模型

协议格式是 MCP 规范定义好的，直接照搬：

public class JsonRpcRequest {
    private String jsonrpc = "2.0";
    private String method;
    private Object params;
    private Object id;
}

7.3 协议处理器的实现

这部分是核心，路由逻辑如下：

public JsonRpcResponse handle(JsonRpcRequest request) {
    return switch (request.getMethod()) {
        case "initialize" -> handleInitialize(request);
        case "tools/list" -> handleListTools(request);
        case "tools/call" -> handleCallTool(request);
        default -> JsonRpcResponse.error(-32601, "方法不存在", request.getId());
    };
}

7.4 SSE 接口

SSE 接口实现：

@PostMapping(value = "/mcp", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter handle(@RequestBody JsonRpcRequest request) {
    SseEmitter emitter = new SseEmitter(60_000L);
    CompletableFuture.runAsync(() -> {
        try {
            JsonRpcResponse response = mcpHandler.handle(request);
            emitter.send(SseEmitter.event().data(objectMapper.writeValueAsString(response)));
            emitter.complete();
        } catch (Exception e) {
            emitter.completeWithError(e);
        }
    });
    return emitter;
}

7.5 工具注册

利用 Spring 的依赖注入：

@Component
public class ToolRegistry {
    private final Map<String, Tool> tools = new ConcurrentHashMap<>();

    @Autowired
    public void registerAllTools(List<Tool> toolList) {
        toolList.forEach(tool -> tools.put(tool.getName(), tool));
    }
}

这样所有实现 Tool 接口的 @Component 都会自动注册进来。

7.6 示例工具

写了一个简单的日程查询工具：

@Component
public class GetCalendarEventsTool implements Tool {
    @Override
    public String getName() {
        return "get_calendar_events";
    }

    @Override
    public String getDescription() {
        return "查询指定日期的日历事件";
    }

    @Override
    public String execute(Map<String, Object> arguments) {
        String date = (String) arguments.get("date");
        return "2026-02-10 有 3 个会议";
    }
}

八、Verification：验证与归档

提示词模板

验证实现是否完整，帮我生成归档报告。 需要验证： - JSON-RPC 协议解析和响应（initialize、tools/list、tools/call） - SSE 传输层 - 日程查询工具（get_calendar_events）调用 

测试结果

正向测试

→ POST /mcp {"method":"tools/list","id":1} ← {"jsonrpc":"2.0","result":{"tools":[{"name":"get_calendar_events",...}]},"id":1}
→ POST /mcp {"method":"tools/call","params":{"name":"get_calendar_events","arguments":{"date":"2026-02-10"}},"id":2} ← {"jsonrpc":"2.0","result":{"content":[{"type":"text","text":"..."}]},"id":2}

异常测试

→ POST /mcp {"method":"unknown","id":1} ← {"jsonrpc":"2.0","error":{"code":-32601,"message":"方法不存在"},"id":1}

归档

openspec archive --change "<change-name>" 

九、在 Claude Code 中测试 MCP 服务器

前置条件

确保 MCP 服务器已启动：

# 编译并启动 SpringBoot 应用 ./gradlew bootRun # 服务器默认在 http://localhost:8080 运行

配置方法

SSE 方式需要在 MCP 客户端和服务器之间建立 HTTP 连接。一种简单方式是使用 npx 直接调用：

# 启动 MCP 服务器（另一个终端）# 添加 MCP 服务 claude mcp add--transport http --scope user calendar-mcp http://localhost:8080/mcp 

在 Claude Code 中使用

1. 确保 MCP 服务器已启动运行
2. 如果配置正确，Claude Code 会自动发现可用工具并调用

在 Claude Code 对话中直接测试：

请调用 get_calendar_events 工具，查询今天的日程 

验证步骤

1. 服务器启动后，确认控制台输出 Started McpServerApplication in x seconds

测试接口是否正常返回：

curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

验证配置

1. 重启 Claude Code
2. 对话中尝试调用工具：
   • '列出所有可用工具'
   • '查询今天的日程'
3. 如果工具正常返回，说明 MCP 服务器配置成功

十、总结

本文基于 SpringBoot3 和 SSE 实现最小可用 MCP 服务器，并通过 OpenSpec 工件驱动流程，从提案到实现完整演示 AI 辅助后端开发的技术落地实践，希望能给大家一些关于 OpenSpec 与 MCP 开发使用的参考。