Spring AI Model Context Protocol 集成 Brave Search 完整案例

3. 项目配置

在 src/main/resources/application.properties 文件中，配置你的 OpenAI API Key 和 MCP 客户端设置。

debug=true spring.application.name=mcp spring.main.web-application-type=none # OpenAI API Key 配置 spring.ai.openai.api-key=${OPENAI_API_KEY} # MCP 客户端配置 spring.ai.mcp.client.stdio.servers-configuration=classpath:/mcp-servers-config.json # 日志配置 logging.level.root=INFO logging.level.org.springframework.ai.mcp=WARN logging.level.org.springframework.ai.mcp.client.transport.StdioClientTransport=WARN logging.level.org.springframework.ai.mcp.samples.brave=INFO logging.level.io.modelcontextprotocol.client=WARN logging.level.io.modelcontextprotocol.spec=WARN

重要提示：请将 OPENAI_API_KEY 环境变量设置为你从 OpenAI 获取的有效 API Key。

4. MCP 服务器配置

在 src/main/resources/mcp-servers-config.json 文件中，配置 Brave Search MCP 服务器：

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {}
    }
  }
}

此配置：

• 通过 npx 使用 Brave Search MCP 服务器
• Brave API 密钥通过环境变量传递
• 初始化与服务器的同步连接

5. 编写 Java 代码

5.1 Application.java

主应用程序类，配置 ChatClient 并执行预设问题。

package org.springframework.ai.mcp.samples.brave;

import java.util.List;
import io.modelcontextprotocol.client.McpSyncClient;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class Application {
    private static final Logger logger = LoggerFactory.getLogger(Application.class);

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args).close();
    }

    @Bean
    public CommandLineRunner predefinedQuestions(ChatClient.Builder chatClientBuilder, List<McpSyncClient> mcpSyncClients) {
        return args -> {
            var chatClient = chatClientBuilder
                    .defaultToolCallbacks(new SyncMcpToolCallbackProvider(mcpSyncClients))
                    .build();
            String question = "Does Spring AI supports the Model Context Protocol? Please provide some references.";
            logger.info("QUESTION: {}\n", question);
            logger.info("ASSISTANT: {}\n", chatClient.prompt(question).call().content());
        };
    }
}

代码解析

这段代码的主要功能：

• 应用程序入口：标准的 Spring Boot 应用程序入口点。
• ChatClient 配置：使用 SyncMcpToolCallbackProvider 配置 ChatClient，使其能够使用 MCP 工具回调。
• 预设问题执行：在应用程序启动时，自动执行一个关于 Spring AI 是否支持 Model Context Protocol 的问题。
• 日志记录：记录问题和 AI 助手的回答。

6. 运行与测试

6.1 前置条件

• Java 17 或更高版本
• Maven 3.6+
• npx 包管理器
• Git
• OpenAI API 密钥
• Brave Search API 密钥（在 https://brave.com/search/api/ 获取）

6.2 设置步骤

构建应用程序：

./mvnw clean install

设置 API 密钥：

export OPENAI_API_KEY='your-openai-api-key-here'
export BRAVE_API_KEY='your-brave-api-key-here'

克隆仓库：

git clone https://github.com/spring-projects/spring-ai-examples.git
cd model-context-protocol/brave

安装 npx：首先确保安装 npm，然后运行：

npm install -g npx

6.3 运行应用程序

使用 Maven 运行应用程序：

./mvnw spring-boot:run

应用程序将执行一个查询，询问 Spring AI 是否支持 Model Context Protocol。它使用 Brave Search MCP 服务器在互联网上搜索相关信息，通过 MCP 客户端处理结果，并在退出前提供详细回答。

7. 工作原理

7.1 MCP 客户端配置

MCP 客户端通过配置文件进行配置：

application.properties：

spring.ai.mcp.client.stdio.servers-configuration=classpath:/mcp-servers-config.json

mcp-servers-config.json：

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {}
    }
  }
}

7.2 聊天集成

ChatClient 在 Application 类中配置了 MCP 工具回调：

var chatClient = chatClientBuilder
        .defaultToolCallbacks(new SyncMcpToolCallbackProvider(mcpSyncClients))
        .build();

此设置允许 AI 模型：

• 理解何时使用 Brave Search
• 适当地格式化查询
• 处理搜索结果并将其整合到回答中

8. 集成测试

项目包含一个集成测试，用于验证应用程序是否正常工作：

8.1 ExampleInfo.json

{
  "timeoutSec": 300,
  "successRegex": [
    "Does Spring AI supports the Model Context Protocol",
    "QUESTION:",
    "ASSISTANT:",
    "Spring AI.*Model Context Protocol"
  ],
  "requiredEnv": [
    "OPENAI_API_KEY",
    "BRAVE_API_KEY"
  ],
  "setupCommands": []
}

8.2 RunBrave.java

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS org.zeroturnaround:zt-exec:1.12
//DEPS com.fasterxml.jackson.core:jackson-databind:2.17.1
//JAVA 17
//FILES ExampleInfo.json
//SOURCES ../../../integration-testing/jbang-lib/IntegrationTestUtils.java
/*
 * Integration test launcher for brave
 * Refactored to use centralized utilities
 */
public class RunBrave {
    public static void main(String... args) throws Exception {
        IntegrationTestUtils.runIntegrationTest("brave");
    }
}

9. 实现思路与扩展建议

9.1 实现思路

本案例的核心思想是**"通过 MCP 协议连接 AI 模型与外部工具"**。我们：

• 使用标准协议：通过 Model Context Protocol (MCP) 连接 AI 模型与 Brave Search 工具。
• 自动配置：利用 Spring Boot 的自动配置功能，通过配置文件轻松设置 MCP 客户端。
• 工具回调：通过 SyncMcpToolCallbackProvider 将 MCP 工具集成到 ChatClient 中。

9.2 扩展建议

• 多 MCP 服务器：可以配置多个 MCP 服务器，使 AI 模型能够访问更多工具和服务。
• 自定义工具：开发自定义 MCP 服务器，提供特定领域的工具和功能。
• 异步处理：使用异步 MCP 客户端，提高应用程序的响应性能。
• Web 界面：添加 Web 界面，使用户能够直接与 AI 模型进行交互，而不仅仅是预设问题。
• 错误处理：增强错误处理机制，处理 MCP 服务器连接失败或 API 限制等情况。