Spring AI MCP Example

Spring AI MCP示例

演示如何使用的基本参考实现 模型上下文协议（MCP） 随着 春季AI该项目展示了一种客户端-服务器架构，其中MCP服务器公开天气和旅行工具，MCP客户端通过AI聊天界面使用这些工具。

什么是MCP？

模型上下文协议（MCP） 是一种协议，使人工智能应用程序能够安全地访问外部工具、资源和数据源。在这个例子中，我们演示：

• MCP服务器：展示人工智能模型可以调用的天气和旅行相关工具
• MCP客户端：连接到服务器并使用OpenAI与用户聊天，自动利用可用工具

项目结构

spring-ai-mcp/
├── mcp-server/          # MCP server exposing weather tools
│   └── src/main/java/dev/fusionize/
│       ├── Main.java           # Spring Boot application entry point
│       ├── Config.java         # Tool callback provider configuration
│       ├── Controller.java     # Health check endpoint
│       └── WeatherService.java # Weather and travel tools implementation
│
└── mcp-client/          # MCP client with chat interface
    └── src/main/java/dev/fusionize/
        ├── Main.java           # Spring Boot application entry point
        ├── Config.java         # MCP client and chat client configuration
        ├── ChatController.java # REST API for chat interactions
        └── ChatService.java    # Chat service using MCP tools

特性

MCP服务器工具

服务器公开了以下工具：

1. getWeather -获取城市的当前天气信息

- 参数： city （字符串）， units （字符串：“celsius”或“fahrenheit”） - 返回：天气信息，包括温度、条件、湿度和推荐项目

1. getTravelTips -获取目的地的旅行建议和提示

- 参数： destination （字符串） - 返回：最佳参观时间、必看景点、必尝美食和旅行提示

1. shouldPackUmbrella -根据天气情况检查你是否应该带雨伞

- 参数： city （字符串） - 返回：推荐理由和天气状况

1. compareWeather -比较两个城市的天气

- 参数： city1 （字符串）， city2 （字符串） - 返回：天气与温差的比较

先决条件

• Java 21 或更高
• Gradle （包括包装）
• OpenAI API密钥 （适用于聊天客户端）

设置

1. 克隆存储库

   git clone 
   cd spring-ai-mcp

1. 设置OpenAI API密钥

将您的OpenAI API密钥导出为环境变量：

   export OPENAI_API_KEY=your-api-key-here

或者创建一个 .env 文件（未包含在存储库中）：

   OPENAI_API_KEY=your-api-key-here

运行应用程序

步骤1：启动MCP服务器

服务器在端口上运行 8081 并通过MCP公开气象工具。

cd mcp-server
../gradlew bootRun

或者从根目录：

./gradlew :mcp-server:bootRun

您应该看到指示服务器正在运行的输出。您可以通过访问来验证它是否正常工作：

• 健康检查：http://localhost:8081/health

步骤2：启动MCP客户端

在一个 新终端，在端口上启动客户端 8080:

cd mcp-client
../gradlew bootRun

或者从根目录：

./gradlew :mcp-client:bootRun

客户端将自动连接到MCP服务器并注册可用工具。您应该看到如下输出：

=== MCP Tools Registered ===
- getWeather: Get current weather information for a city
- getTravelTips: Get travel recommendations and tips for a destination
- shouldPackUmbrella: Check if you should pack an umbrella based on weather conditions
- compareWeather: Compare weather between two cities
============================

测试

1.检查可用工具

从MCP服务器获取所有可用工具的列表：

curl http://localhost:8080/api/tools

2.与AI聊天

人工智能现在可以使用天气工具来回答你的问题。请尝试以下示例：

获取天气信息：

curl "http://localhost:8080/api/chat?message=What's the weather like in Paris?"

获取旅行提示：

curl "http://localhost:8080/api/chat?message=Give me travel tips for Tokyo"

比较天气：

curl "http://localhost:8080/api/chat?message=Compare the weather in London and Dubai"

雨伞推荐：

curl "http://localhost:8080/api/chat?message=Should I pack an umbrella for Amsterdam?"

复杂查询：

curl "http://localhost:8080/api/chat?message=I'm planning a trip to Paris next week. What should I know about the weather and what should I pack?"

3.服务器健康检查

检查MCP服务器状态和可用工具：

curl http://localhost:8081/health

运作原理

MCP服务器流

1. 气象服务 定义带注释的方法 @Tool Spring AI
2. 配置 创建a ToolCallbackProvider 注册这些工具
3. Spring AI MCP服务器通过HTTP/SSE端点自动公开这些工具 /mcp/messages
4. 服务器在端口8081上运行，并监听MCP客户端连接

MCP客户端流

1. 配置 创造 McpSyncClient 通过SSE连接到MCP服务器的实例
2. SyncMcpToolcallback提供程序 包装MCP客户端，并将其工具提供给Spring AI
3. 聊天客户端 已配置为自动使用这些工具
4. 当用户发送消息时，AI模型（OpenAI）可以决定调用适当的工具
5. 客户端运行在端口8080上，并为聊天交互提供REST API

通信流

User → ChatController → ChatService → ChatClient (OpenAI)
                                          ↓
                                    (AI decides to use tools)
                                          ↓
                              SyncMcpToolCallbackProvider
                                          ↓
                                    McpSyncClient (SSE)
                                          ↓
                                    MCP Server (8081)
                                          ↓
                                    WeatherService Tools

配置

服务器配置(mcp-server/src/main/resources/application.yml)

• 端口: 8081
• MCP端点: /mcp/messages 上海证券交易所
• 服务器类型：同步
• 能力：工具已启用

客户端配置(mcp-client/src/main/resources/application.yml)

• 端口: 8080
• OpenAI模型：gpt-4o-mini
• MCP服务器URL: http://localhost:8081/mcp
• 连接类型：SSE（服务器发送事件）

使用的技术

• 弹簧靴3.5.6 -应用框架
• 春季AI 1.0.3 -人工智能集成框架
• 春季AI MCP -模型上下文协议支持
• OpenAI API -AI模型提供商
• Java 21 -程序设计语言
• Gradle -构建工具

局限性

这是一个 基本示例 出于教育目的：

• 天气数据是 模拟的 （在服务中硬编码）
• 仅支持有限的一组城市
• 无身份验证或安全功能
• 单MCP服务器连接
• 基本错误处理

扩展示例

要扩展此示例，您可以：

1. 添加更多工具 -新建 @Tool 注释方法 WeatherService
2. 连接到真实的API -用实际天气API替换模拟数据
3. 添加多个MCP服务器 -在客户端中配置多个服务器连接
4. 添加身份验证 -为MCP端点实施安全措施
5. 添加持久性 -存储聊天记录或用户偏好
6. 添加WebSocket支持 -使用WebSocket而不是SSE进行双向通信

故障排除

客户端无法连接到服务器

• 确保服务器在端口8081上运行
• 检查中的URL application.yml 比赛： http://localhost:8081/mcp
• 验证防火墙设置

OpenAI API错误

• 确保 OPENAI_API_KEY 环境变量已设置
• 检查您的API密钥是否有效并具有信用
• 验证网络连接

工具未出现

• 检查服务器日志以进行工具注册
• 验证 @Tool 存在注释
• 确保 ToolCallbackProvider bean创建正确

许可证

这是一个参考示例项目。您可以将其作为您自己的MCP实现的起点。

贡献

这是一个基本的参考示例。请随意分叉和扩展它以满足您的需求！

______________________________________________________________________

备注：此示例演示了使用Spring AI的MCP的基本概念。对于生产使用，请考虑添加适当的错误处理、安全性、日志记录和测试。