当前位置：首页 > news >正文

基于 Spring AI 与 Streamable HTTP 构建 MCP Server 实践

news 2026/3/27 2:14:55

基于 Spring AI 与 Streamable HTTP 构建 MCP Server 实践

面向专家读者的实战文章，目标是把“模型驱动工具调用（MCP）”从协议、架构到工程落地完整走通。本文强调可扩展、可观测与生产级交付。

1. 背景与目标

随着模型能力增强，单纯“对话式”应用难以满足真实业务需求：系统必须在受控环境中选择工具、调用外部能力、组合结果并持续推送。MCP（Model Context Protocol）提供了统一的工具暴露与调用规范；而Streamable HTTP则是解决“增量输出、低时延交互、服务端流式推送”的关键技术基础。

本文目标：

以Spring AI为核心编排层
通过Streamable HTTP实现低时延增量输出
构建一个具备工具注册、工具发现、工具调用、结果流式回传的 MCP Server
同时满足安全、可观测、扩展性等生产级要求

2. 总体架构设计

2.1 角色划分

MCP Server：提供工具注册、元信息描述、调用入口、流式返回
Spring AI：作为“模型侧编排器”，负责工具选择与调用
Tool Provider：实际业务能力（数据库、搜索、订单、风控、知识库）
Client（MCP Client/Agent）：可能是 IDE、AIGC 应用、或业务中台

2.2 核心链路

Client 请求 MCP Server（描述任务）
MCP Server 调用 Spring AI
模型判断调用工具，触发工具执行
工具执行结果被包装为增量事件流（Streamable HTTP）
Client 以流式方式接收增量响应

3. 协议与数据结构约定

3.1 Tool Schema 结构

MCP 工具需要声明：

name：工具标识
description：用途说明
input_schema：输入参数结构（JSON Schema）
output_schema：输出结构

3.2 Streamable HTTP 事件模型

本文采用“事件类型 + payload + metadata”的格式，以便 Client 侧按事件增量渲染：

tool_call_start
tool_call_delta
tool_call_result
final

4. Spring AI 工程实现

4.1 依赖与工程结构

建议模块拆分：

mcp-server-core：协议、模型、流式响应
mcp-server-tools：工具实现
mcp-server-app：Spring Boot 启动层

4.2 MCP Server 接口定义

@RestController @RequestMapping("/mcp") public class McpController { private final McpService mcpService; public McpController(McpService mcpService) { this.mcpService = mcpService; } @PostMapping(value = "/invoke", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<ServerSentEvent<McpEvent>> invoke(@RequestBody McpRequest request) { return mcpService.handleRequest(request) .map(event -> ServerSentEvent.builder(event).build()); } }

4.3 MCP 服务编排层

@Service public class McpService { private final AiClient aiClient; private final ToolRegistry toolRegistry; public McpService(AiClient aiClient, ToolRegistry toolRegistry) { this.aiClient = aiClient; this.toolRegistry = toolRegistry; } public Flux<McpEvent> handleRequest(McpRequest request) { return aiClient.chatStream(request.toPrompt(), toolRegistry.getToolSpecs()) .flatMap(this::handleModelOutput); } private Flux<McpEvent> handleModelOutput(AiDelta delta) { // 解析模型输出 → 工具调用 return Flux.just(McpEvent.delta(delta.getContent())); } }

5. Streamable HTTP 的核心实现

5.1 选择 SSE 还是 Chunked Response

SSE 简单、浏览器兼容好
Chunked Response 更自由，但需要自定义解析

本文采用 SSE（Spring WebFlux 原生支持）实现可控的增量输出。

5.2 工具调用事件流示例

public Flux<McpEvent> executeToolWithStream(ToolCall call) { return Flux.concat( Flux.just(McpEvent.start(call.getName())), toolRegistry.invoke(call) .flatMapMany(result -> Flux.just(McpEvent.result(result))), Flux.just(McpEvent.finalEvent()) ); }

6. 工具注册与发现

6.1 工具声明

@Component public class OrderQueryTool implements McpTool { @Override public String name() { return "order_query"; } @Override public String description() { return "根据订单号查询订单详情"; } @Override public JsonSchema inputSchema() { return JsonSchema.object() .field("orderId", JsonSchema.string().required()); } @Override public Mono<ToolResult> execute(JsonNode input) { String orderId = input.get("orderId").asText(); return Mono.just(new ToolResult("订单:" + orderId + " 状态: 已完成")); } }

6.2 工具注册中心

@Component public class ToolRegistry { private final Map<String, McpTool> tools = new ConcurrentHashMap<>(); public ToolRegistry(List<McpTool> toolList) { for (McpTool tool : toolList) { tools.put(tool.name(), tool); } } public List<ToolSpec> getToolSpecs() { return tools.values().stream() .map(ToolSpec::from) .collect(Collectors.toList()); } public Mono<ToolResult> invoke(ToolCall call) { McpTool tool = tools.get(call.getName()); return tool.execute(call.getArguments()); } }