spring-ai-demo-mcp-server

ffengtian/spring-ai-demo-mcp-server

3.2

If you are the rightful owner of spring-ai-demo-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This is a Spring AI MCP Server Demo project based on Spring Boot 3.4.9 and Spring AI 1.0.0, showcasing the use of the Model Context Protocol (MCP) with simulated server methods and SSE support.

Tools
2
Resources
0
Prompts
0

Spring AI MCP Server Demo

这是一个基于 Spring Boot 3.4.9 和 Spring AI 1.0.0 的 MCP Server 演示项目，使用 @Tool 注解提供两个模拟的 MCP Server 方法，并支持 SSE 远程服务。

🚀 项目特性

  • JDK 17 + Spring Boot 3.4.9 + Spring AI 1.0.0
  • MCP Server 工具：
    • 🌤️ 天气预报工具：根据地区名称返回模拟天气信息
    • 🍜 特产查询工具：根据地区名称返回地区特色美食
  • SSE 流式响应：支持实时流式数据推送
  • 标准 Spring Boot 项目结构：遵循最佳实践

📋 技术栈

  • 后端框架：Spring Boot 3.4.9
  • AI 框架：Spring AI 1.0.0
  • MCP 协议：Model Context Protocol
  • 响应式编程：Spring WebFlux (SSE 支持)
  • 构建工具：Maven
  • Java 版本：JDK 17

🛠️ 快速开始

1. 环境要求

  • JDK 17+
  • Maven 3.6+

2. 运行项目

# 编译项目
mvn clean compile

# 运行项目
mvn spring-boot:run

项目启动后访问：http://localhost:8080

🔧 MCP Server 工具

天气预报工具 (WeatherTool)

工具名称描述参数
getWeatherForecast根据地区名称获取天气预报信息location - 地区名称
getSupportedWeatherCities获取所有支持天气预报查询的城市列表无
getBatchWeatherForecast批量获取多个城市的天气预报信息cities - 城市名称列表（逗号分隔）

特产查询工具 (SpecialtyTool)

工具名称描述参数
getLocalSpecialty根据地区名称获取当地特色美食和特产信息location - 地区名称
getSupportedSpecialtyCities获取所有支持特产查询的城市列表无
getBatchLocalSpecialty批量获取多个城市的特产美食信息cities - 城市名称列表（逗号分隔）
getCitiesByCategory根据菜系名称查询相关城市category - 菜系名称

📡 API 接口

测试接口

天气查询测试

GET /api/test/weather/{location}

特产查询测试

GET /api/test/specialty/{location}

批量天气查询测试

GET /api/test/weather/batch?cities=北京,上海,广州

批量特产查询测试

GET /api/test/specialty/batch?cities=北京,上海,广州

菜系查询测试

GET /api/test/category/{category}

支持城市列表

GET /api/test/cities

SSE 流式接口

流式天气查询

GET /api/sse/weather/{location}

流式特产查询

GET /api/sse/specialty/{location}

流式批量天气查询

GET /api/sse/weather/batch?locations=北京,上海,广州

流式批量特产查询

GET /api/sse/specialty/batch?locations=北京,上海,广州

流式服务器状态

GET /api/sse/status

🎯 功能演示

支持的城市

项目支持以下10个城市的天气和特产查询：

  • 北京、上海、广州、深圳、杭州
  • 成都、西安、武汉、南京、重庆

示例调用

单个城市天气查询

curl http://localhost:8080/api/test/weather/北京

单个城市特产查询

curl http://localhost:8080/api/test/specialty/成都

菜系查询

curl http://localhost:8080/api/test/category/川菜

🏗️ 项目结构

src/main/java/com/learn/peppa/spring/ai/demo/
├── SpringAiDemoApplication.java          # 主启动类
├── tool/
│   ├── WeatherTool.java                   # 天气预报MCP工具
│   └── SpecialtyTool.java                 # 特产查询MCP工具
├── controller/
│   ├── TestController.java                # MCP工具测试控制器
│   └── SseController.java                 # SSE流式响应控制器
├── dto/
│   ├── WeatherInfo.java                   # 天气信息DTO
│   ├── SpecialtyInfo.java                 # 特产信息DTO
│   └── McpResponse.java                   # MCP响应DTO
└── service/
    └── McpServerService.java              # MCP Server服务类

🔧 开发说明

MCP Server 配置

在 application.properties 中配置 MCP Server：

# MCP Server 配置
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.stdio=true
spring.ai.mcp.server.name=weather-specialty-server
spring.ai.mcp.server.version=1.0.0

@Tool 注解使用

使用 @Tool 注解标记 MCP 工具方法：

@Tool(name = "getWeatherForecast", description = "根据地区名称获取天气预报信息")
public String getWeatherForecast(String location) {
    // 工具实现
}

代码规范

  • 遵循阿里 P3C 代码规范
  • 使用 Spring Boot 最佳实践
  • 响应式编程模式
  • 完整的错误处理

🐛 故障排除

常见问题

  1. MCP Server 启动失败

    • 检查 Spring AI 1.0.0 依赖是否正确
    • 确认 MCP Server 配置正确

  2. 工具方法无法调用

    • 检查 @Tool 注解是否正确
    • 确认方法参数和返回值类型正确

  3. SSE 连接问题

    • 检查 WebFlux 依赖是否正确
    • 确认 SSE 端点配置正确

📄 许可证

本项目仅用于学习和演示目的。

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

注意：本项目是一个 MCP Server 演示，不涉及大模型调用。大模型调用功能应在客户端项目中实现。