Spring AI MCP 客户端详解

概述

Model Context Protocol (MCP) 是一种标准化协议，用于使 AI 模型以结构化的方式与外部工具和资源进行交互。它充当 AI 模型与外部系统（如数据库、API 和文件系统）之间的桥梁，支持多种传输机制，以适应不同环境。

Spring AI 通过专用的 Boot Starters 和 MCP Java Annotations 集成 MCP，使 Spring 开发者能够构建消费 MCP 服务器的 AI 应用程序，并创建暴露 Spring 基于服务的 MCP 服务器。MCP 架构采用三层设计：

• 客户端/服务器层：包括管理客户端操作和服务器连接的 McpClient，以及处理服务器端协议操作的 McpServer。
• 会话层：通过 McpSession、McpClientSession 和 McpServerSession 管理通信。
• 传输层：通过 McpTransport 处理消息传输和序列化，支持如 STDIO、HTTP/SSE 和 Streamable-HTTP 等传输方式。

MCP Java SDK 提供了协议的 Java 实现，支持同步和异步通信模式。

设置

要使用 Spring AI 中的 MCP 客户端，请按照以下步骤设置：

1. 使用 Spring Initializer 初始化带有 MCP 支持的 AI 应用程序。
2. 在 pom.xml 中添加相应的 Spring Boot starter 依赖：

• spring-ai-starter-mcp-client：提供 STDIO、基于 Servlet 的 Streamable-HTTP、无状态 Streamable-HTTP 和 SSE 支持。
• spring-ai-starter-mcp-client-webflux：提供基于 WebFlux 的 Streamable-HTTP、无状态 Streamable-HTTP 和 SSE 传输（适用于响应式应用）。

例如，添加 Anthropic 模型和 MCP 客户端的依赖：

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

使用 Spring AI BOM 管理版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

配置

配置通过 Spring Boot 属性文件（如 application.yaml）管理。支持两种主要传输类型：stdio 和 SSE。

示例配置

1. Brave Search MCP 客户端 (stdio)：

   spring:
     ai:
       mcp:
         client:
           stdio:
             connections:
               brave-search:
                 command: npx
                 args: 
                   - "-y"
                   - "@modelcontextprotocol/server-brave-search"
                 env:
                   BRAVE_API_KEY: ${BRAVE_API_KEY}

2. Filesystem MCP 客户端 (stdio)：

   spring:
     ai:
       mcp:
         client:
           stdio:
             connections:
               filesystem:
                 command: npx
                 args:
                   - "-y"
                   - "@modelcontextprotocol/server-filesystem"
                   - "./"

3. 自定义 MCP 服务器客户端 (SSE)：

   spring:
     ai:
       mcp:
         client:
           sse:
             connections:
               author-tools-server:
                 url: http://localhost:8081

启动时，Spring AI 会建立与 MCP 服务器的一对一连接，并创建一个 SyncMcpToolCallbackProvider Bean 来暴露所有可用工具。

此外，配置 API 密钥和模型：

spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
    chat:
      options:
        model: claude-opus-4-20250514

使用

MCP 客户端 (McpClient) 负责：

• 建立和管理与 MCP 服务器的连接。
• 处理协议版本协商以确保兼容性。
• 执行能力协商以确定可用功能。
• 管理消息传输和 JSON-RPC 通信。
• 支持工具发现和执行。
• 启用资源访问和管理。
• 促进提示系统交互。

它支持根管理、采样支持以及同步/异步操作。

在 Spring AI 中，使用 MCP 客户端构建聊天机器人时：

• 创建 ChatClient Bean：

  @Bean
  ChatClient chatClient(ChatModel chatModel, SyncMcpToolCallbackProvider toolCallbackProvider) {
      return ChatClient.builder(chatModel)
              .defaultToolCallbacks(toolCallbackProvider.getToolCallbacks())
              .build();
  }

• 实现聊天服务：

  String chat(String question) {
      return chatClient.prompt()
              .user(question)
              .call()
              .content();
  }

• 通过 REST 端点暴露：

  @PostMapping("/chat")
  ResponseEntity<ChatResponse> chat(@RequestBody ChatRequest chatRequest) {
      String answer = chatbotService.chat(chatRequest.question());
      return ResponseEntity.ok(new ChatResponse(answer));
  }

  record ChatRequest(String question) {}
  record ChatResponse(String answer) {}

示例

1. Web 搜索

使用 Brave Search 工具发送问题：

http POST :8080/chat question="How much was Elon Musk's initial offer to buy OpenAI in 2025?"

响应将包括搜索结果和来源。

2. 文件系统操作

http POST :8080/chat question="Create a text file named 'mcp-demo.txt' with content 'This is awesome!'."

确认文件创建。

3. 自定义工具调用

假设有一个自定义服务器暴露作者工具：

http POST :8080/chat question="Who wrote the article 'Testing CORS in Spring Boot?' on Baeldung, and how can I contact them?"

返回作者姓名和电子邮件。

关键特性

• 传输灵活性：支持 STDIO、HTTP/SSE、Streamable-HTTP 和无状态 Streamable-HTTP。
• 双向集成：允许 Spring 开发者参与 MCP 生态系统的客户端和服务器端。
• 注解支持：通过 MCP Annotations 模块，使用如 @McpLogging、@McpSampling、@McpElicitation 和 @McpProgress 等注解进行声明式编程。
• 自动发现：支持注解扫描，并可配置包包含/排除。
• Spring Boot 集成：通过 MCP Boot Starters 简化设置。

最佳实践

• 使用 Spring Initializer 引导项目以支持 MCP。
• 根据传输需求选择合适的 starter（例如，响应式应用使用 spring-ai-starter-mcp-client-webflux）。
• 利用 MCP Annotations 减少样板代码，提高客户端实现的维护性。
• 在客户端-服务器交互中通过协议版本和能力协商确保兼容性。
• 使用结构化日志和通知实现稳健的客户端-服务器通信。