Spring Boot搭建Model Context Protocol (MCP) 服务

<dependencies>
    <!-- Web Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Lombok (可选，简化代码) -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

package com.example.mcp.model;

import com.fasterxml.jackson.databind.JsonNode;
import lombok.Data;

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

package com.example.mcp.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
public class JsonRpcResponse {
    private String jsonrpc = "2.0";
    private Object result;
    private Object error;
    private Object id;

    // 成功的静态工厂方法
    public static JsonRpcResponse success(Object id, Object result) {
        return new JsonRpcResponse("2.0", result, null, id);
    }
}

package com.example.mcp.service;

import com.example.mcp.model.JsonRpcRequest;
import com.example.mcp.model.JsonRpcResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.stereotype.Service;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Service
public class McpService {

    private final ObjectMapper objectMapper = new ObjectMapper();

    public JsonRpcResponse handleRequest(JsonRpcRequest request) {
        String method = request.getMethod();

        try {
            switch (method) {
                case "initialize":
                    return handleInitialize(request);
                case "tools/list":
                    return handleListTools(request);
                case "tools/call":
                    return handleCallTool(request);
                case "notifications/initialized":
                    // 客户端确认初始化完成，通常无需回复内容，但需保持连接
                    return null; 
                default:
                    throw new RuntimeException("Method not found: " + method);
            }
        } catch (Exception e) {
            // 简单错误处理
            return new JsonRpcResponse("2.0", null, Map.of("code", -32603, "message", e.getMessage()), request.getId());
        }
    }

    // 1. 握手协议
    private JsonRpcResponse handleInitialize(JsonRpcRequest request) {
        Map<String, Object> result = new HashMap<>();
        result.put("protocolVersion", "2025-11-05");
        result.put("capabilities", Map.of("tools", Map.of())); // 声明支持工具
        result.put("serverInfo", Map.of("name", "SpringBoot-MCP-Demo", "version", "1.0.0"));
        return JsonRpcResponse.success(request.getId(), result);
    }

    // 2. 定义工具列表
    private JsonRpcResponse handleListTools(JsonRpcRequest request) {
        // 定义一个简单的加法工具
        Map<String, Object> addTool = Map.of(
            "name", "calculate_sum",
            "description", "计算两个数字的和",
            "inputSchema", Map.of(
                "type", "object",
                "properties", Map.of(
                    "a", Map.of("type", "number", "description", "第一个数字"),
                    "b", Map.of("type", "number", "description", "第二个数字")
                ),
                "required", List.of("a", "b")
            )
        );
        
        // 定义一个系统信息工具
        Map<String, Object> sysInfoTool = Map.of(
            "name", "get_system_info",
            "description", "获取当前服务器运行环境信息",
            "inputSchema", Map.of("type", "object", "properties", Map.of())
        );

        return JsonRpcResponse.success(request.getId(), Map.of("tools", List.of(addTool, sysInfoTool)));
    }

    // 3. 执行工具逻辑
    private JsonRpcResponse handleCallTool(JsonRpcRequest request) {
        String name = request.getParams().get("name").asText();
        Map<String, Object> arguments = objectMapper.convertValue(request.getParams().get("arguments"), Map.class);

        String resultText = "";

        if ("calculate_sum".equals(name)) {
            double a = Double.parseDouble(arguments.get("a").toString());
            double b = Double.parseDouble(arguments.get("b").toString());
            resultText = String.valueOf(a + b);
        } else if ("get_system_info".equals(name)) {
            resultText = System.getProperty("os.name") + " - Java " + System.getProperty("java.version");
        } else {
            throw new RuntimeException("Unknown tool: " + name);
        }

        // MCP 要求的返回格式 content: [{type: "text", text: "..."}]
        Map<String, Object> content = Map.of(
            "content", List.of(Map.of("type", "text", "text", resultText))
        );
        
        return JsonRpcResponse.success(request.getId(), content);
    }
}

package com.example.mcp.controller;

import com.example.mcp.model.JsonRpcRequest;
import com.example.mcp.model.JsonRpcResponse;
import com.example.mcp.service.McpService;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;

import java.io.IOException;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;

@RestController
@RequestMapping("/mcp")
public class McpController {

    private final McpService mcpService;
    // 用于保存SSE连接（生产环境可能需要更复杂的Session管理）
    private final ConcurrentHashMap<String, SseEmitter> emitters = new ConcurrentHashMap<>();

    public McpController(McpService mcpService) {
        this.mcpService = mcpService;
    }

    /**
     * 1. SSE 连接端点
     * 客户端连接到这里监听服务端事件
     */
    @GetMapping("/sse")
    public SseEmitter handleSse(HttpServletResponse response) {
        // 设置 SSE 超时时间，0表示无限
        SseEmitter emitter = new SseEmitter(0L);
        String sessionId = UUID.randomUUID().toString();
        
        emitters.put(sessionId, emitter);

        emitter.onCompletion(() -> emitters.remove(sessionId));
        emitter.onTimeout(() -> emitters.remove(sessionId));

        try {
            // MCP 标准：连接建立后，服务端发送 endpoint 事件，告知客户端去哪里发 POST 消息
            // 注意：这里硬编码了本地地址，实际部署需改为配置的域名/IP
            String endpointUrl = "/mcp/messages?sessionId=" + sessionId;
            emitter.send(SseEmitter.event().name("endpoint").data(endpointUrl));
            System.out.println("Client connected, session: " + sessionId);
        } catch (IOException e) {
            emitters.remove(sessionId);
        }

        return emitter;
    }

    /**
     * 2. 消息接收端点 (POST)
     * 客户端发送 JSON-RPC 请求到这里
     */
    @PostMapping("/messages")
    public JsonRpcResponse handleMessage(
            @RequestParam(required = false) String sessionId,
            @RequestBody JsonRpcRequest request) {
        
        System.out.println("Received: " + request.getMethod());
        
        // 处理核心业务逻辑
        JsonRpcResponse response = mcpService.handleRequest(request);
        
        return response;
    }
}

curl -N http://localhost:8080/mcp/sse

event:endpoint
data:/mcp/messages?sessionId=xxxx-xxxx-xxxx...

curl -X POST http://localhost:8080/mcp/messages \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "initialize",
  "id": 1,
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {"name": "curl-client", "version": "1.0"}
  }
}'

curl -X POST http://localhost:8080/mcp/messages \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 2,
  "params": {
    "name": "calculate_sum",
    "arguments": {"a": 10, "b": 25.5}
  }
}'

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "35.5"
      }
    ]
  },
  "id": 2
}