MCP Spring Boot Server

A Spring Boot server implementation for Model Context Protocol (MCP), providing weather information services through MCP interfaces.

Features

• Weather information service via MCP
• RESTful API endpoints
• Server-Sent Events (SSE) support
• Automatic tool registration
• Spring Boot 3.x integration

Requirements

• JDK 17 or later
• Maven 3.6.x or later
• Spring Boot 3.2.0 or later

Getting Started

Clone the Repository

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

Build the Project

mvn clean install

Run the Application

mvn spring-boot:run

The server will start on port 8080 by default.

Configuration

The main configuration properties are located in application.properties:

server.port=8080
spring.application.name=mcp-demo
spring.ai.mcp.server.enabled=true

For more configuration options, please check the application.properties file.

API Documentation

Weather Service

The Weather Service provides the following MCP methods:

• getWeather(String cityName): Get weather information for a specific city
• getWeather1(String cityName): Alternative method to get weather information

Example usage in the test client:

var transport = new HttpClientSseClientTransport("http://localhost:8080");
var client = McpClient.sync(transport).build();

Project Structure

src/
├── main/
│   ├── java/
│   │   └── com/unionhole/mcpserver/
│   │       ├── config/
│   │       ├── service/
│   │       └── McpDemoApplication.java
│   └── resources/
│       └── application.properties
└── test/
    └── java/
        └── com/unionhole/mcpserver/
            └── ClientSseTest.java

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Author

James Zou

• Email: 18301545237@163.com
• GitHub: @jameszou

Acknowledgments

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

框架说明

1. Maven 依赖配置

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

<dependencies>
    <!-- Spring AI Core -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-core</artifactId>
        <version>${spring-ai.version}</version>
    </dependency>

    <!-- MCP Server WebMVC -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
        <version>${spring-ai.version}</version>
    </dependency>
    <!-- 添加 MCP Facade 生成器依赖 -->
    <dependency>
        <groupId>com.unionhole</groupId>
        <artifactId>mcp-facade-generator</artifactId>
        <version>${mcp-facade.version}</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;
    }
}

2. 使用 @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. 重新构建项目

参考文档

• Spring AI 文档
• MCP Facade Generator

---

Copyright © 2024 James Zou. All rights reserved.