mcp-springboot-server

yangshangwei/mcp-springboot-server

3.1

If you are the rightful owner of mcp-springboot-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 dayong@mcphub.com.

A Spring Boot-based Model Context Protocol (MCP) server implementation providing weather information and ticket booking services.

Tools
2
Resources
0
Prompts
0

MCP Spring Boot Server

License JDK Spring Boot Spring AI Author

一个基于Spring Boot的Model Context Protocol (MCP)服务器实现，提供天气信息查询和票务预订服务。该项目展示了如何使用Spring AI和MCP Facade Generator来构建MCP工具服务。

功能特性

  • 天气信息服务: 提供多种天气查询功能，包括基本天气、详细天气、温度查询、降雨状态和5天预报
  • 票务预订服务: 支持活动门票预订、查询票务信息和取消预订功能
  • MCP协议支持: 完整实现Model Context Protocol规范
  • Server-Sent Events (SSE): 支持实时通信
  • 自动工具注册: 通过Facade模式自动注册MCP工具
  • Spring AI集成: 基于Spring AI 1.0.0构建
  • 注解驱动开发: 使用@MCPService和@MCPMethod简化开发

环境要求

  • JDK 17 或更高版本
  • Maven 3.6.x 或更高版本
  • Spring Boot 3.2.3
  • Spring AI 1.0.0

快速开始

克隆项目

git clone https://github.com/yangshangwei/mcp-springboot-server.git
cd mcp-springboot-server

构建项目

mvn clean install

运行应用

mvn spring-boot:run

服务器将在默认端口8080上启动。

配置说明

主要配置位于 application.properties 文件中：

server.port=8080
spring.application.name=mcp-demo
spring.main.banner-mode=off

# MCP 服务器配置
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.resource-change-notification=true
spring.ai.mcp.server.prompt-change-notification=true
spring.ai.mcp.server.tool-change-notification=true
spring.ai.mcp.server.name=mcp-demo-service
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.sse-message-endpoint=/mcp/messages

API 文档

天气服务 (WeatherService)

天气服务提供以下MCP工具方法：

  • getWeather(String cityName): 获取指定城市的基本天气信息
  • getWeatherInfo(String cityName): 获取指定城市的详细天气信息
  • getDetailedWeather(String cityName): 获取包括温度、湿度和风速的详细天气预报
  • getForecast(String cityName): 获取未来5天的天气预报
  • getCurrentTemperature(String cityName): 获取指定城市的当前摄氏温度
  • isRaining(String cityName): 检查指定城市是否正在下雨

票务服务 (BookingService)

票务服务提供以下MCP工具方法：

  • bookTicket(McpRequest request): 预订指定活动的门票
    • 参数: eventName(必需), customerName(必需), seats(可选，默认1)
  • getTicketInfo(McpRequest request): 查询指定活动的门票信息
    • 参数: eventName(必需)
  • cancelBooking(McpRequest request): 取消现有预订
    • 参数: bookingId(必需)

项目结构

src/
├── main/
│   ├── java/
│   │   └── com/artisan/mcpserver/
│   │       ├── config/
│   │       │   └── McpServerConfig.java          # MCP服务器配置
│   │       ├── service/
│   │       │   ├── WeatherService.java           # 天气服务业务逻辑
│   │       │   └── BookingService.java           # 票务服务业务逻辑
│   │       ├── mcp/
│   │       │   ├── WeatherServiceFacade.java     # 天气服务MCP门面
│   │       │   └── BookingServiceFacade.java     # 票务服务MCP门面
│   │       ├── vo/
│   │       │   ├── McpRequest.java               # MCP请求对象
│   │       │   └── MCPResponse.java              # MCP响应对象
│   │       └── McpDemoApplication.java           # 主应用程序类
│   └── resources/
│       └── application.properties                # 应用配置文件
└── test/
    └── java/
        └── com/artisan/mcpserver/
            └── ClientSseTest.java                # MCP客户端测试

开发指南

添加新的MCP服务

  1. 创建服务类：
@MCPService(packageName = "com.artisan.mcpserver.mcp")
@Service
public class YourService {
    
    @MCPMethod(description = "你的方法描述")
    public String yourMethod(String param) {
        // 业务逻辑实现
        return "result";
    }
}
  1. 编译项目：
mvn clean compile

编译后会自动生成对应的Facade类。

  1. 验证工具注册： 启动应用后，通过客户端测试验证新工具是否正确注册。

最佳实践

  1. 服务层设计：

    • 保持服务方法的单一职责
    • 使用有意义的方法名和参数名
    • 添加详细的@MCPMethod描述

  2. 错误处理：

    • 在服务层进行参数验证
    • 使用统一的异常处理机制
    • 返回有意义的错误信息

  3. 日志记录：

    • 记录方法调用的关键信息
    • 使用适当的日志级别
    • 包含请求参数和返回结果

  4. 测试：

    • 为每个服务方法编写单元测试
    • 使用MCP客户端进行集成测试

贡献指南

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 创建 Pull Request

License

This project is licensed under the Apache License 2.0 - see the file for details.

Acknowledgments

  • Spring Boot Team
  • Model Context Protocol Team
  • All contributors to this project

架构设计

核心组件

  1. Service Layer (服务层): 包含业务逻辑的核心服务类

    • WeatherService: 天气信息服务
    • BookingService: 票务预订服务

  2. MCP Facade Layer (MCP门面层): 将业务服务暴露为MCP工具

    • WeatherServiceFacade: 天气服务的MCP门面
    • BookingServiceFacade: 票务服务的MCP门面

  3. Configuration Layer (配置层): MCP服务器配置

    • McpServerConfig: 自动注册MCP工具的配置类

  4. VO Layer (值对象层): 数据传输对象

    • McpRequest: MCP请求封装
    • MCPResponse: MCP响应封装

工作原理

  1. 注解驱动: 使用@MCPService和@MCPMethod注解标记服务和方法
  2. 自动代码生成: MCP Facade Generator在编译时自动生成Facade类
  3. 自动工具注册: McpServerConfig自动发现并注册所有Facade类为MCP工具
  4. SSE通信: 通过Server-Sent Events提供实时通信能力

框架说明

1. Maven 依赖配置

项目使用了以下主要依赖：

<dependencies>
    <!-- Spring Boot Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>

    <!-- Spring AI MCP Server WebMVC -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
        <version>${spring-ai.version}</version>
    </dependency>

    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- MCP Facade Generator -->
    <dependency>
        <groupId>com.unionhole</groupId>
        <artifactId>mcp-facade-generator</artifactId>
        <version>1.0.1</version>
    </dependency>
</dependencies>

2. MCP 配置说明

在 application.properties 中配置 MCP 服务器：

# MCP 服务器配置
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.resource-change-notification=true
spring.ai.mcp.server.prompt-change-notification=true
spring.ai.mcp.server.tool-change-notification=true
spring.ai.mcp.server.name=mcp-demo-service
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.sse-message-endpoint=/mcp/messages

3. MCP Tools 配置

通过 McpServerConfig 类配置 MCP Tools：

@Configuration
public class McpServerConfig {
    @Bean
    public ToolCallbackProvider autoRegisterTools(ApplicationContext applicationContext) {
        // 获取所有带有 @Component 注解且类名以 Facade 结尾的 bean
        String[] beanNames = applicationContext.getBeanNamesForAnnotation(Component.class);
        List<Object> facadeBeans = new ArrayList<>();
        for (String beanName : beanNames) {
            if (beanName.endsWith("Facade")) {
                facadeBeans.add(applicationContext.getBean(beanName));
            }
        }
        return MethodToolCallbackProvider.builder()
                .toolObjects(facadeBeans.toArray())
                .build();
    }
}

4. 业务服务开发

  1. 创建服务类并添加 @MCPService 注解：
@MCPService
@Service
public class WeatherService {
    public String getWeather(String cityName) {
        // 实现业务逻辑
        return "Weather info for " + cityName;
    }
}
  1. 使用 @MCPMethod 注解标记需要暴露的方法：
@MCPMethod(description = "获取天气信息")
public String getWeather(String cityName) {
    // 方法实现
}

5. 客户端测试

使用提供的 ClientSseTest 类进行测试：

public class ClientSseTest {
    public static void main(String[] args) {
        var transport = new HttpClientSseClientTransport("http://localhost:8080");
        var client = McpClient.sync(transport).build();

        try {
            client.initialize();
            client.ping();

            // 列出可用的工具
            McpSchema.ListToolsResult toolsList = client.listTools();
            System.out.println("Available Tools = " + toolsList);

            client.closeGracefully();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

注意事项

  1. 确保正确配置了 Spring AI 和 MCP 的版本
  2. 所有 Facade 类都应该使用 @Component 注解
  3. 建议使用 @MCPMethod 注解来提供方法的描述信息
  4. 异常处理应该在服务层统一处理

常见问题解决

1. 编译时出现 IllegalArgumentException

如果在编译过程中遇到以下错误：

java: java.lang.IllegalArgumentException

解决方案：

在 IntelliJ IDEA 中添加 VM 选项：

  1. 打开 Settings (Ctrl + Alt + S)
  2. 导航到 Build, Execution, Deployment > Compiler
  3. 在 "Build process VM options" 字段中添加： 
    -Djps.track.ap.dependencies=false
  4. 点击 Apply 和 OK
  5. 重新构建项目

参考文档