Pre

大模型开发 - 01 Spring AI 核心特性一览

大模型开发 - 02 Spring AI Concepts

大模型开发 - 03 QuickStart_借助DeepSeekChatModel实现Spring AI 集成 DeepSeek

大模型开发 - 04 QuickStart_DeepSeek 模型调用流程源码解析：从 Prompt 到远程请求

大模型开发 - 05 QuickStart_接入阿里百炼平台：Spring AI Alibaba 与 DashScope SDK

大模型开发 - 06 QuickStart_本地大模型私有化部署实战：Ollama + Spring AI 全栈指南

大模型开发 - 07 ChatClient：构建统一、优雅的大模型交互接口

大模型开发 - 08 ChatClient：构建智能对话应用的流畅 API

大模型开发 - 09 ChatClient：基于 Spring AI 的多平台多模型动态切换实战

大模型开发 - 10 ChatClient：Advisors API 构建可插拔、可组合的智能对话增强体系

大模型开发 - 11 ChatClient：Advisor 机制详解：拦截、增强与自定义 AI 对话流程

大模型开发 - 12 Prompt：Spring AI 中的提示（Prompt）系统详解_从基础概念到高级工程实践

大模型开发 - 13 Prompt：提示词工程实战指南_Spring AI 中的提示设计、模板化与最佳实践

大模型开发 - 14 Chat Memory：实现跨轮次对话上下文管理

大模型开发 - 15 Tool Calling ：从入门到实战，一步步构建智能Agent系统

大模型开发 - 16 Chat Memory：借助 ChatMemory + PromptChatMemoryAdvisor轻松实现大模型多轮对话记忆

大模型开发 - 17 Structured Output Converter：结构化输出转换器_从文本到结构化数据的可靠桥梁

大模型开发 - 18 Chat Memory：集成 JdbcChatMemoryRepository 实现大模型多轮对话记忆

大模型开发 - 19 Chat Memory：集成 BaseRedisChatMemoryRepository实现大模型多轮对话记忆

大模型开发 - 20 Chat Memory：多层次记忆架构_突破大模型对话中的 Token 上限瓶颈

大模型开发 - 21 Structured Output Converter：结构化输出功能实战指南

大模型开发 - 22 Multimodality API：多模态大模型与 Spring AI 的融合

大模型开发 - 23 Chat Model API：深入解析 Spring AI Chat Model API_构建统一、灵活、可扩展的 AI 对话系统

大模型开发 - 24 Embeddings Model API：深入解析 Spring AI Embeddings Model API_构建语义理解的基石

大模型开发 - 25 Image Model API：深入解析 Spring AI Image Model API_构建统一、灵活的 AI 图像生成系统

大模型开发 - 26 Origin Tools： Spring AI 结构化多聊天客户端实战

大模型开发 - 27 Tool Calling：Spring AI 中的工具调用指南

大模型开发 - 28 Tool Calling：Spring AI 工具调用执行外部操作实战

大模型开发 - 29 Tool Calling：大模型与业务系统集成的利器 _Tool Calling 实战指南

大模型开发 - 30 Tool Calling：Spring AI Tool Calling 工作原理及源码详解

大模型开发 - 31 Tool Calling：解决大模型“工具选择困难症”_基于 RAG 的动态工具加载方案解读

大模型开发 - 32 Tool Calling：Spring AI 工具调用最佳实践完整指南

---

概述

随着大模型（LLM）应用的快速发展，如何让 AI 模型安全、高效地与外部工具、数据源和业务系统进行交互，已成为构建企业级 AI 应用的关键挑战。Model Context Protocol（MCP，模型上下文协议） 正是为解决这一问题而生的标准化通信协议。本文将带你从零开始，深入理解 MCP 的核心设计思想，并手把手教你如何在 Java 项目中使用 MCP Java SDK，以及如何通过 Spring AI 快速集成 MCP 客户端与服务端功能。

---

一、什么是 Model Context Protocol（MCP）？

Model Context Protocol（MCP） 是一种标准化的双向通信协议，专为 AI 模型（如大语言模型）与其运行环境中的外部工具、资源和服务之间的交互而设计。它的目标是：

• 解耦模型与工具：模型无需硬编码工具逻辑，而是通过协议动态调用。
• 统一交互接口：无论工具是本地命令、数据库查询还是 Web API，都通过 MCP 统一暴露。
• 支持多种传输方式：适用于进程内通信、HTTP 流、标准输入输出（stdio）等多种场景。
• 保障安全与可控：通过能力协商、资源访问控制等机制限制模型行为边界。

MCP 基于 JSON-RPC 2.0 协议构建，采用请求-响应 + 通知（notification）的混合模式，支持同步与异步操作。

---

二、MCP Java SDK 架构详解

MCP Java SDK 是 MCP 协议的官方 Java 实现，采用清晰的三层架构设计，便于扩展与维护。

1. 三层架构概览

层级	组件	职责
Client/Server 层	McpClient / McpServer	提供高层 API，封装协议逻辑，处理工具调用、资源访问等业务语义
Session 层	McpClientSession / McpServerSession	管理会话状态、消息路由、生命周期，是通信的核心枢纽
Transport 层	McpTransport（多种实现）	负责底层消息的序列化（JSON-RPC）与传输（如 stdio、SSE、WebSocket）

关键点：这种分层设计使得你可以轻松替换底层传输方式，而无需修改业务逻辑。

---

2. MCP 客户端（MCP Client）功能

McpClient 是连接 MCP 服务端的入口，主要能力包括：

• 协议版本协商：确保客户端与服务端使用兼容的 MCP 版本。
• 能力协商（Capability Negotiation）：动态发现服务端支持的功能（如是否支持工具调用、资源访问等）。
• 工具发现与执行：列出可用工具（tools），并按需调用。
• 资源管理：通过 URI 访问外部资源（如文件、数据库记录）。
• 提示词（Prompt）系统交互：获取预定义的提示模板。
• 可选功能：
  • Roots 管理（用于沙箱环境）
  • 采样支持（sampling）
• 多传输支持：
  • StdioTransport：适用于子进程通信（如 LLM 调用本地工具进程）
  • HttpClientSseTransport：基于 Java 原生 HttpClient 的 Server-Sent Events（SSE）
  • WebFluxSseTransport：基于 Spring WebFlux 的响应式 SSE 传输

---

3. MCP 服务端（MCP Server）功能

McpServer 负责暴露工具和资源给客户端，核心职责包括：

• 工具注册与暴露：将 Java 方法注册为 MCP 工具，自动支持发现与调用。
• 资源 URI 处理：实现 mcp:// 或自定义 URI 的资源读取/写入。
• 提示模板管理：提供预设的 prompt 模板供客户端使用。
• 并发连接管理：支持多个客户端同时连接（尤其在 HTTP 场景下）。
• 结构化日志与通知：向客户端推送日志、进度或事件通知。
• 传输实现：
  • StdioTransport：用于命令行工具模式
  • ServletSseTransport：传统 Servlet 容器下的 SSE
  • WebFluxSseTransport：响应式 WebFlux 下的 SSE
  • WebMvcSseTransport：基于 Spring MVC 的 SSE

---

三、重要提醒：MCP Java SDK 0.8.0 的重大变更

如果你正在从 0.7.0 升级到 0.8.0，请注意以下破坏性变更：

• 引入 Session 会话模型：所有通信必须通过 McpSession 进行，不再直接操作 Transport。
• API 重构：McpClient 和 McpServer 的构造方式改变，需使用 Builder 模式。
• 工具注册方式调整：服务端工具注册需通过 ToolProvider 接口。
• 资源访问接口变更：ResourceProvider 替代旧的资源处理逻辑。

建议：升级前务必阅读官方 Migration Guide。

---

四、实战：使用 Spring AI 快速集成 MCP

Spring AI 为 MCP 提供了开箱即用的 Spring Boot Starters，极大简化了开发流程。你可以通过 Spring Initializr 快速创建项目。

步骤 1：选择合适的 Starter

根据你的角色（客户端 or 服务端）和 Web 技术栈（Servlet or WebFlux），选择对应依赖：

客户端（Client）

Starter	说明
spring-ai-starter-mcp-client	核心客户端，支持 stdio 和 HTTP SSE
spring-ai-starter-mcp-client-webflux	基于 WebFlux 的响应式 SSE 客户端

服务端（Server）

Starter	说明
spring-ai-starter-mcp-server	核心服务端，支持 stdio
spring-ai-starter-mcp-server-webmvc	基于 Spring MVC 的 SSE 服务端
spring-ai-starter-mcp-server-webflux	基于 WebFlux 的响应式 SSE 服务端

推荐：新项目优先使用 WebFlux（响应式）以获得更好的并发性能。

---

步骤 2：构建一个 MCP 服务端（示例）

假设我们要构建一个提供“天气查询”工具的 MCP 服务端。

2.1 添加依赖（Maven）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
    <version>1.0.0-M5</version> <!-- 请使用最新版本 -->
</dependency>

2.2 注册工具

@Component
public class WeatherToolProvider implements ToolProvider {

    @Override
    public List<Tool> getTools() {
        Tool weatherTool = Tool.builder()
            .name("getWeather")
            .description("获取指定城市的当前天气")
            .inputSchema(JsonObject.of(
                "city", JsonString.of("城市名称，如 '北京'")
            ))
            .build();
        return List.of(weatherTool);
    }

    @ToolMethod("getWeather")
    public String getWeather(String city) {
        // 模拟调用天气 API
        return "当前 " + city + " 的天气是晴，25°C。";
    }
}

2.3 启动服务端

@SpringBootApplication
public class McpWeatherServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpWeatherServerApplication.class, args);
    }
}

默认情况下，服务端会监听 /mcp 路径的 SSE 连接（如 http://localhost:8080/mcp）。

---

步骤 3：构建 MCP 客户端调用服务端

3.1 添加客户端依赖

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
</dependency>

3.2 配置连接

在 application.yml 中配置服务端地址：

spring:
  ai:
    mcp:
      client:
        transport:
          type: SSE
          sse:
            uri: http://localhost:8080/mcp

3.3 调用工具

@Service
public class WeatherService {

    private final McpClient mcpClient;

    public WeatherService(McpClient mcpClient) {
        this.mcpClient = mcpClient;
    }

    public String fetchWeather(String city) {
        // 发起工具调用
        ToolCall call = ToolCall.builder()
            .name("getWeather")
            .arguments(JsonObject.of("city", JsonString.of(city)))
            .build();

        ToolResult result = mcpClient.callTool(call).block();
        return result.getContent().asString();
    }
}

启动客户端后，它会自动连接服务端、协商能力、发现工具，并执行调用。

---

五、传输方式选择建议

场景	推荐 Transport
LLM 调用本地 CLI 工具（如 Python 脚本）	StdioTransport
Web 应用中前端 ↔ 后端 MCP 通信	WebFluxSseTransport（响应式）或 WebMvcSseTransport
微服务间 MCP 调用	HTTP SSE（WebFlux 更佳）
高并发、低延迟场景	WebFlux + SSE

---

六、调试与日志

MCP 支持结构化日志输出。你可以在服务端或客户端启用 DEBUG 日志：

logging:
  level:
    org.springframework.ai.mcp: DEBUG

你将看到完整的 JSON-RPC 请求/响应内容，便于排查问题。

---

七、总结

Model Context Protocol（MCP）为 AI 模型与外部世界的交互提供了一套标准化、安全、可扩展的通信框架。通过 MCP Java SDK 和 Spring AI 的 Boot Starters，Java 开发者可以：

• 快速构建 MCP 服务端，暴露工具与资源；
• 轻松集成 MCP 客户端，调用远程能力；
• 灵活选择传输方式，适配不同部署环境；
• 利用 Spring Boot 的自动配置，减少样板代码。

随着 MCP 生态的成熟，我们有望看到更多工具库、中间件和云服务原生支持 MCP，真正实现“模型即服务，工具即插件”的 AI 应用新范式。

---

附录：官方资源

• MCP 协议规范（GitHub）
• MCP Java SDK 文档
• Spring AI MCP 客户端文档
• Spring AI MCP 服务端文档
• MCP 工具注册与资源管理指南

---