【Spring AI MCP】一、MCP 原理详解

1. MCP 概述

Model Context Protocol（MCP，模型上下文协议）是由 Anthropic 公司于 2024 年 11 月推出的开放协议，旨在标准化 AI 应用程序（如大型语言模型 LLM）与外部数据源、工具和服务之间的交互方式。它类似于 AI 领域的“USB-C 接口”，提供了一个统一的桥梁，让 AI 模型能够无缝访问数据库、API、文件系统、网络服务等外部资源，而无需为每个集成点编写自定义代码。

MCP 的核心目标是简化 AI 智能体（Agent）的开发：在 LLM 之上构建复杂工作流时，避免碎片化的集成。协议定义了如何通过结构化消息传递上下文，包括工具调用（Tools）、资源访问（Resources）和提示模板（Prompts）。截至 2025 年 12 月，MCP 已形成活跃生态，支持 Python、Java、C#、TypeScript 等多语言 SDK，并有大量预构建服务器（如文件系统、搜索引擎）可用。

Spring AI（Spring 框架的 AI 扩展）从 1.0.0-M5 版本开始全面拥抱 MCP，通过 Boot Starters 和注解提供无缝集成。这使得 Java 开发者能轻松构建 MCP 服务器（暴露工具）和客户端（调用工具），并与 Spring 的工具调用（Tool Calling）框架融合。Spring AI MCP 扩展了官方 MCP Java SDK，支持同步/异步通信，并自动处理 FunctionCallback 到 MCP Tools 的转换。

2. MCP 核心原理

MCP 的设计基于客户端-主机-服务器架构（Client-Host-Server），强调标准化、灵活性和安全性。以下是其核心原理详解：

2.1 架构原理

MCP Server（服务器）：暴露工具、资源和提示的组件，通常连接本地数据源（如文件系统）或远程服务（如 API）。服务器通过 MCP 协议公开功能，例如一个天气 MCP Server 可以暴露 getWeather 工具，供 AI 调用获取实时数据。
MCP Client（客户端）：集成在 AI 应用中（如 Spring AI 的 ChatClient），负责发现服务器能力、调用工具并处理响应。客户端可以同时连接多个服务器，实现工具链式调用。
MCP Host（主机）：运行客户端的 AI 应用（如 Claude Desktop 或自定义 Spring Boot 应用），协调 LLM 与多个客户端的交互。主机确保安全边界，例如通过 OAuth 2.0 隔离不同服务器。

工作流程：

初始化（Initialization）：客户端连接服务器，交换能力描述（Capabilities）。服务器返回工具列表（JSON Schema 定义）、资源 URI 和提示模板。
发现（Discovery）：客户端查询可用工具，例如 listTools() 方法返回工具 schema，LLM 根据用户查询决定调用哪个工具。
调用（Invocation）：客户端发送工具调用请求（e.g., callTool("getWeather", {lat: 39.9, lon: 116.4})），服务器执行并返回结果。支持参数验证、错误处理和进度通知。
通知（Notification）：服务器可推送事件，如工具更新（动态添加/移除）或日志消息。客户端可订阅资源变化（e.g., 文件更新）。
终止（Shutdown）：客户端断开连接，释放资源。

此架构支持动态工具更新：服务器通知客户端工具变更，无需重启应用，提高了扩展性。

2.2 核心组件原理

MCP 定义了三种主要能力，每个能力通过 JSON-RPC 2.0 消息实现（请求-响应 + 通知）：

Tools（工具）：
原理：可执行函数，LLM 通过自然语言触发调用。工具 schema 自动从方法签名和 Javadoc 生成（参数类型、描述）。
示例：在 Spring AI 中，使用 @Tool 注解标记方法：
java @Tool(description = "获取指定位置的天气") public String getWeather(@ToolParameter(name = "city") String city) { // 调用外部 API return "北京晴天，25°C"; }
原理扩展：支持同步（阻塞调用）和异步（Mono/Flux 返回），集成 Spring 的 ToolCallbackProvider。LLM 使用 function calling 解析用户意图，自动注入参数。
Resources（资源）：
原理：静态或动态数据源，如文件内容或数据库查询结果。支持订阅（subscribe/unsubscribe）实时更新。
示例：文件系统 MCP Server 暴露 /files/{path} 资源，客户端可读取或监听变化。
原理扩展：URI-based 访问，带版本控制和权限检查。Spring AI 通过 McpResourceSpecification 注册资源，支持流式传输大文件。
Prompts（提示）：
原理：预设模板，用于注入上下文或格式化响应。模板支持变量替换（e.g., {user_query}）。
示例：一个提示模板 "分析以下数据：{data}"，客户端填充后发送给 LLM。
原理扩展：标准化消息格式化，确保 LLM 输入一致性。Spring AI 通过 @McpPrompt 注解定义模板。

2.3 传输层原理

MCP 支持多种传输机制，确保本地/远程灵活性：

Stdio（标准输入输出）：IPC（进程间通信），适合本地子进程。原理：通过管道（pipe）双向传输 JSON 消息，无网络开销。
SSE（Server-Sent Events）：HTTP-based 单向推送，适合远程。原理：客户端 POST 请求初始化，服务器通过 SSE 流式响应，支持多客户端并发。Spring AI 提供 WebMVC/WebFlux 传输实现。
Streamable HTTP（新版）：双向 HTTP，支持流式工具调用，取代纯 SSE。

传输基于 JSON-RPC：

请求：{"jsonrpc": "2.0", "method": "callTool", "params": {...}, "id": 1}
响应：{"jsonrpc": "2.0", "result": {...}, "id": 1}
通知：单向推送，如进度更新。

2.4 安全与扩展原理

安全：集成 OAuth 2.0，服务器作为 Resource Server，客户端获取 access token。Spring Security 自动处理令牌验证，支持 scopes（如 tools.read）。
日志与监控：内置日志级别（DEBUG 到 EMERGENCY），客户端可设置过滤。支持采样（sampling）和进度令牌（progress token）跟踪调用链。
扩展：动态注册工具（运行时添加），多服务器编排。Spring AI 的 McpFunctionCallback 桥接传统 Function Calling 到 MCP，确保向后兼容。

组件	原理要点	Spring AI 集成
Tools	JSON Schema 定义，LLM 意图解析	`@Tool` 注解 + ToolCallbackProvider
Resources	URI 访问 + 订阅	`McpResourceSpecification` Bean
Prompts	模板变量替换	`@McpPrompt` + 自动注入
传输	JSON-RPC over Stdio/SSE	WebFlux/MVC Starters
安全	OAuth 2.0 + Scopes	Spring Security 自动配置

3. Spring AI 中的 MCP 实现原理

Spring AI MCP（从 1.0.0-M6 起）扩展了官方 Java SDK，提供 Boot Starters：

spring-ai-mcp-server-starter：自动配置 McpSyncServer/McpAsyncServer，扫描 @Tool 方法。
spring-ai-mcp-client-starter：配置客户端连接（如 Stdio/SSE），注入到 ChatClient.functions。

原理图（基于 Spring AI Tool Calling）：

用户查询 → LLM 解析意图 → 生成工具调用。
ChatClient 通过 McpFunctionCallback 转发到 MCP Client。
Client 序列化请求 → 传输层发送 → Server 执行 → 反序列化响应。
LLM 整合结果 → 生成最终回复。

示例配置（application.yml）：

spring:
  ai:
    mcp:
      server:
        enabled: true
        type: SYNC  # 或 ASYNC
        sse-message-endpoint: /mcp/message
      client:
        stdio:
          connections:
            weather:
              command: npx
              args: ["@modelcontextprotocol/server-weather"]

此实现确保 MCP 与 Spring 的依赖注入、AOP 等无缝融合，支持动态刷新工具列表。

4. 优势与局限

优势：统一集成（单协议多源）、实时交互（流式响应）、生态丰富（预构建服务器）。
局限：依赖 LLM 支持 Tool Calling；远程传输需网络稳定；早期版本（pre-1.0）API 变动大。

MCP + Spring AI 标志着 Java AI 开发的标准化时代。通过此原理，您可构建如“自然语言查询数据库”的智能应用。下一节将深入构建示例，若需代码或特定场景，请补充！

【Spring AI MCP】一、MCP 原理详解