深度实战：Spring AI 与 MCP（Model Context Protocol）构建下一代 AI Agent

深度实战：Spring AI 与 MCP（Model Context Protocol）构建下一代 AI Agent

1. 前言：AI Agent 时代的到来与 MCP 的诞生背景

在过去的两年中，生成式 AI（AIGC）经历了从单纯的"聊天对话"向"自主决策"的跨越式发展。早期的 LLM 只是一个庞大的知识库，它能吟诗作对，却无法感知实时世界，也无法操作具体的软件工具。为了解决这一局限性，AI Agent（智能体）的概念应运而生。Agent 的核心在于其"行动能力"，即通过 Tool Calling（工具调用）机制，连接数据库、API 和本地文件系统。

然而，在 AI Agent 的开发过程中，开发者面临一个巨大的痛点：生态系统的极度碎片化。每一个 AI 模型、每一个工具平台都有自己的协议标准。如果你想让 Claude 调用你的本地数据库，或者让 GPT-4 操作你的 GitHub 仓库，你往往需要为不同的模型编写大量重复的适配层代码。这种"多对多"的集成模式极大地消耗了开发者的精力，限制了 AI 应用的规模化落地。

正是在这样的背景下，Anthropic 推出了 Model Context Protocol (MCP) 。MCP 的愿景是成为 AI 界的"USB 接口"。它定义了一套标准化的开放协议，使得模型（Client）能够以统一的方式与数据源及工具（Server）进行交互。而对于 Java 开发者而言，Spring AI 则是目前最优雅的集成方案。Spring AI 迅速跟进了对 MCP 的支持，使得 Java 开发者能够利用 Spring 生态的强大优势，快速构建企业级的、具备标准化扩展能力的 AI 应用。本文将作为"AI 学习与实战"系列的重要篇章，带你深度拆解 Spring AI 与 MCP 的实战技巧。

2. Spring AI 架构全解：为 Java 开发者铺就 AI 之路

Spring AI 并非只是对大模型 API 的简单封装，它是对 AI 开发范式的深度抽象。对于习惯了 Spring Boot 开发逻辑的工程师来说，Spring AI 的出现降低了学习曲线，使得 AI 集成就像添加一个 Starter 依赖一样简单。

2.1 核心组件设计

Spring AI 的设计遵循了"抽象胜于实现"的原则。其核心接口 ChatClient 为开发者提供了一个统一的编程模型。无论底层使用的是 OpenAI、Anthropic 还是本地运行的 Ollama，上层代码几乎无需变动。

• Model Options：通过可配置的对象控制模型的采样温度（Temperature）、最大 Token 数等参数。
• Prompt Template：解决了硬编码提示词的问题，支持动态变量替换，是 Prompt Engineering 在 Java 端的最佳实践。
• Output Parsers：将 LLM 返回的非结构化字符串自动映射为 Java POJO，这对于业务系统集成至关重要。

2.2 Advisors 机制

Spring AI 引入了 Advisor（顾问）机制，类似于 AOP（面向切面编程）。它允许开发者在请求发送给 LLM 之前或之后，透明地注入逻辑。例如，你可以通过 QuestionAnswerAdvisor 自动实现 RAG（检索增强生成），或者通过拦截器实现敏感词过滤。这种插件化的设计，为我们后续集成 MCP 提供了坚实的架构基础。

2.3 为什么选择 Spring AI

在 Java 生态中，Spring AI 的优势在于其"企业级属性"。它完美集成了 Spring Boot 的自动配置、健康检查、指标监控（Micrometer）以及安全控制（Spring Security）。在处理 MCP 这种涉及外部进程通讯的复杂协议时，Spring AI 的健壮性显得尤为重要。

3. MCP 协议深度解析：标准化 AI 工具调用的基石

要玩转 Spring AI + MCP，必须理解 MCP 的底层运行逻辑。MCP 本质上是一个客户端-服务器架构（Client-Server Architecture）。

3.1 协议的三大支柱

MCP 协议定义了三种核心的交互内容：

1. Resources（资源）：服务器提供的只读数据，如本地文件内容、数据库 Schema 或实时日志。模型可以读取这些资源来获取上下文。
2. Tools（工具）：服务器提供的可执行函数。模型可以请求执行某个工具（如"发送邮件"或"运行 SQL"），由 MCP Server 执行并返回结果。
3. Prompts（提示词模板）：服务器预定义的提示词片段，帮助用户快速启动特定任务。

3.2 传输层协议

MCP 支持多种传输方式，最常用的是：

• Stdio Transport：通过标准输入输出进行通讯。这在本地开发中非常常见，Spring AI 会启动一个 MCP Server 的子进程，通过管道与其对话。
• HTTP Transport：通过 SSE（Server-Sent Events）进行异步通讯，适用于远程服务集成。

3.3 MCP 的工作流

当一个集成了 MCP 的 Spring AI 应用启动时，它会首先与 MCP Server 建立连接并进行初始化握手。在握手过程中，Server 会告知 Client 它拥有哪些工具和资源。当用户提出需求时（如"分析这个 CSV 文件"），Spring AI 会将 MCP 提供的工具元数据发送给 LLM，LLM 决定调用哪个工具，Spring AI 转发调用指令给 MCP Server，最后将执行结果返回给 LLM 生成最终回答。

4. 实战：构建基于 MCP 的自定义工具服务器

在这一小节，我们将动手实现一个简单的 MCP Server。虽然 Spring AI 社区正在推进 Java 版本的 MCP Server SDK，但目前主流的做法是使用 TypeScript 或 Python 编写 Server。这里我们以 Python 为例，创建一个能够查询本地天气和系统状态的 MCP Server。

4.1 环境准备

你需要安装 mcp 库：

pip install mcp

4.2 编写 Server 代码

创建一个 weather_server.py：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MyTools")

@mcp.tool()
def get_weather(city: str) -> str:
    """获取指定城市的天气信息"""
    # 在真实场景中，这里会调用第三方 API
    return f"{city} 的当前天气是晴天，25摄氏度。"

@mcp.tool()
def get_system_load() -> str:
    """获取当前系统 CPU 负载"""
    import psutil
    return f"当前 CPU 使用率为: {psutil.cpu_percent()}%"

if __name__ == "__main__":
    mcp.run()

4.3 关键点说明

• @mcp.tool() 装饰器非常关键，它会自动将函数的签名、文档字符串（Docstring）转换为 LLM 可理解的 JSON Schema。
• 文档字符串必须描述清晰，因为 LLM 正是根据这段描述来判断何时该调用此工具。
• FastMCP 封装了底层的 JSON-RPC 通讯逻辑，让开发者只需关注业务函数本身。

5. Spring AI 集成 MCP：实现动态工具发现与调用

有了 MCP Server 之后，接下来的重点是在 Spring Boot 应用中将其集成进来。Spring AI 提供了 McpClient 及其配套的配置类。

5.1 引入依赖

在 pom.xml 中引入 Spring AI MCP 的 Starter（需确保 Spring AI 版本在 1.0.0-M4 及以上）：

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

5.2 配置 MCP 客户端

在 application.yml 中配置如何连接到我们的 Python Server：

spring:
  ai:
    mcp:
      client:
        stdio:
          connections:
            my-weather-tools:
              command: python
              args: ["/path/to/weather_server.py"]

这里我们配置了一个名为 my-weather-tools 的连接，指定通过 python 命令启动脚本。Spring AI 会在后台管理这个子进程的生命周期。

5.3 在代码中使用工具

Spring AI 的妙处在于，你不需要手动解析 MCP 的响应。你可以通过 ChatClient 开启工具调用功能：

@RestController
public class AiController {

    private final ChatClient chatClient;

    public AiController(ChatClient.Builder builder, McpSyncClient mcpClient) {
        // 将 MCP 客户端发现的工具自动注册到 ChatClient 中
        var mcpToolCallbackProvider = new McpFunctionCallbackProvider(mcpClient);
        this.chatClient = builder
                .defaultFunctions(mcpToolCallbackProvider.getFunctions())
                .build();
    }

    @GetMapping("/ask")
    public String ask(@RequestParam String message) {
        return chatClient.prompt(message).call().content();
    }
}

当用户访问 /ask?message=上海天气怎么样？ 时，Spring AI 会自动识别出需要调用 get_weather 工具，通过 MCP 协议发送请求给 Python 进程，并将结果反馈给用户。

6. 进阶：复杂场景下的多步推理与上下文管理

在实际的企业应用中，AI Agent 往往需要执行多步操作才能完成任务。例如："查询当前的系统负载，如果负载超过 80%，请查一下明天的天气预报，看看是否需要安排服务器扩容作业"。

6.1 多工具协同

在这种情况下，LLM 需要具备规划能力。MCP 协议支持同时暴露多个工具。Spring AI 会在 Prompt 中包含所有可用工具的列表。如果任务复杂，LLM 会生成一系列的工具调用指令（Tool Call Sequence）。Spring AI 的 ChatClient 内部包含了一个循环机制，它会逐一执行这些工具，并将中间结果不断喂回给模型，直到模型给出最终结论。

6.2 资源（Resources）的妙用

除了工具（Tools），MCP 的资源（Resources）功能在长上下文任务中非常有用。比如，你可以将一个长达 10MB 的日志文件通过 MCP Resource 暴露出来。Spring AI 可以配置为"按需读取"。当模型认为它需要参考日志时，它会请求读取该资源。这种方式比直接将整个日志塞进 Prompt 更加节省 Token，也更精准。

6.3 状态保持

MCP 协议本身是有状态的。通过 McpClient 的 Session 管理，我们可以确保多次对话之间工具的上下文得以延续。这在需要多步身份验证或会话保持的任务中尤为重要。

7. 性能优化与安全性设计：从原型到生产的跨越

将 Spring AI + MCP 应用投入生产环境之前，必须考虑性能和安全。

7.1 安全性：沙箱与权限管理

MCP Server 直接运行在服务器上，如果 LLM 被诱导（Prompt Injection）执行了危险操作（如 rm -rf /），后果不堪设想。

• 最小权限原则：MCP Server 运行的操作系统用户应只有极小的权限。
• 输入校验：在工具函数的内部，必须对 LLM 传入的参数进行严格校验，不要直接拼接字符串执行 Shell 命令或 SQL。
• 沙箱化：建议将 MCP Server 部署在 Docker 容器中，限制其 CPU、内存和网络访问。

7.2 性能：连接池与超时处理

• 启动耗时：Stdio 模式下，每次启动 MCP Server 子进程都有开销。Spring AI 默认会保持长连接，但开发者需要监控连接的存活状态。
• 并行执行：对于不互相关联的工具调用，可以考虑在服务端实现并行处理。
• 超时设置 ：在 Spring AI 配置中，务必设置合理的 connect-timeout 和 read-timeout，防止由于某个外部 API 响应慢导致整个 AI 对话卡死。

7.3 可观测性

利用 Spring Boot Actuator。你可以暴露端点来查看当前连接了哪些 MCP Server，以及各个工具的调用频率和成功率。通过集成 Brave 或 OpenTelemetry，你甚至可以追踪一个请求从 Spring AI 到 MCP Server 再到外部 API 的完整链路。

8. 结语：Spring AI + MCP 的学习路径与实战建议

AI 技术迭代飞快，保持竞争力的核心在于掌握"标准化"的工具和协议。Spring AI + MCP 的组合，不仅是 Java 开发者的福音，更是构建可扩展、生产级 AI Agent 的工业标准。

学习路线建议

1. 夯实基础：先掌握 Spring Boot 3.x 核心特性，了解 Reactive Programming（响应式编程），因为 Spring AI 的底层大量使用了 Project Reactor。
2. 深入模型原理：阅读 Anthropic 和 OpenAI 关于 Tool Calling 的官方文档，理解模型是如何决定调用工具的。
3. MCP 协议深度游 ：去 GitHub 搜索 mcp-servers 仓库，看看社区里别人是怎么实现各种 Server 的（如 GitHub, Slack, Google Drive 的集成）。
4. 动手实战：尝试用 Spring AI 复现一个复杂的 Agent 任务，比如一个能根据你的本地笔记（Markdown）自动生成周报的机器人。
5. 关注社区：Spring AI 目前处于快速演进期，密切关注 Spring 官方博客，学习最新的 API 变动。

实战建议

• 不要过度工程化：如果一个简单的 REST 调用能解决问题，不一定非要上 MCP。MCP 的价值在于多模型通用和动态发现。
• 重视提示词工程：工具的描述（Description）就是给 AI 看的 API 文档，写好描述能大幅提升工具调用的准确率。
• 持续监控：上线后一定要收集 AI 调用工具的 Trace 数据，分析模型在哪一环节容易出错。

通过本文的讲解，希望你能掌握 Spring AI 与 MCP 的精髓，开启你的 AI Agent 航程。未来已来，让我们用 Java 赋能 AI，用 AI 重塑 Java 应用！