Spring AI MCP(Model Context Protocol) 实践

依赖导入

以 Gradle 为例

添加快照仓库地址

repositories {
    maven { url 'https://repo.spring.io/milestone' }
    maven { url 'https://repo.spring.io/snapshot' }
}

添加依赖

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter:1.0.0-SNAPSHOT'
    implementation 'org.springframework.ai:spring-ai-starter-mcp-client:1.0.0-SNAPSHOT'
    implementation 'org.springframework.ai:spring-ai-starter-mcp-server-webmvc:1.0.0-SNAPSHOT'
}

构建 Chat Client

创建 Chat Client 并添加工具，使大模型可以调用提供的工具。包括官方已实现的基本工具和自定义实现。

添加官方已实现的基本工具（实现访问本地文件和数据库）

1. 向 application.properties 文件中添加以下配置项

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

2. 向 src/main/resources 目录下添加 mcp-servers-config.json 文件
   配置中的 npx 使用的为绝对路径

{
	"mcpServers": {
		"filesystem": {
			"command": "D:\\nodejs\\22.12.0\\npx.cmd",
			"args": [
				"-y",
				"@modelcontextprotocol/server-filesystem",
				"D:\\tmp"
			]
		},
		"postgres": {
			"command": "D:\\nodejs\\22.12.0\\npx.cmd",
			"args": [
				"-y",
				"@modelcontextprotocol/server-postgres",
				"postgresql://postgres:password@localhost:5432/test"
			]
		}
	}
}

添加自定义实现

1. 获取天气（美国地区）信息的工具（Spring AI example 实现）

package com.example.mcp.server.service;

import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;

@Service
public class WeatherService {

	private static final String BASE_URL = "https://api.weather.gov";

	private final RestClient restClient;

	public WeatherService() {
		this.restClient = RestClient.builder()
				.baseUrl(BASE_URL)
				.defaultHeader("Accept", "application/geo+json")
				.defaultHeader("User-Agent", "WeatherApiClient/1.0 (your@email.com)")
				.build();
	}

	@JsonIgnoreProperties(ignoreUnknown = true)
	public record Points(@JsonProperty("properties") Props properties) {

		@JsonIgnoreProperties(ignoreUnknown = true)
		public record Props(@JsonProperty("forecast") String forecast) {
		}
	}

	@JsonIgnoreProperties(ignoreUnknown = true)
	public record Forecast(@JsonProperty("properties") Props properties) {

		@JsonIgnoreProperties(ignoreUnknown = true)
		public record Props(@JsonProperty("periods") List<Period> periods) {
		}

		@JsonIgnoreProperties(ignoreUnknown = true)
		public record Period(@JsonProperty("number") Integer number, @JsonProperty("name") String name,
				@JsonProperty("startTime") String startTime, @JsonProperty("endTime") String endTime,
				@JsonProperty("isDaytime") Boolean isDayTime, @JsonProperty("temperature") Integer temperature,
				@JsonProperty("temperatureUnit") String temperatureUnit,
				@JsonProperty("temperatureTrend") String temperatureTrend,
				@JsonProperty("probabilityOfPrecipitation") Map probabilityOfPrecipitation,
				@JsonProperty("windSpeed") String windSpeed, @JsonProperty("windDirection") String windDirection,
				@JsonProperty("icon") String icon, @JsonProperty("shortForecast") String shortForecast,
				@JsonProperty("detailedForecast") String detailedForecast) {
		}
	}

	@Tool(description = "根据经度和纬度获取天气预报。")
	public String getWeatherForecastByLocation(@ToolParam(description = "纬度") double latitude, @ToolParam(description = "经度") double longitude) {

		var points = restClient.get()
			.uri("/points/{latitude},{longitude}", latitude, longitude)
			.retrieve()
			.body(Points.class);

		var forecast = restClient.get().uri(points.properties().forecast()).retrieve().body(Forecast.class);

		String forecastText = forecast.properties().periods().stream().map(p -> {
			return String.format("""
					%s:
					温度: %s %s
					风向: %s %s
					天气预报: %s
					""", p.name(), p.temperature(), p.temperatureUnit(), p.windSpeed(), p.windDirection(),
					p.detailedForecast());
		}).collect(Collectors.joining());

		return forecastText;
	}
}

2. 获取本地系统信息工具

package com.example.mcp.server.service;

import java.util.HashMap;
import java.util.Map;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.stereotype.Service;

@Service
public class SystemService {


	@Tool(description = "获取本地系统信息，如操作系统名称、版本、Java版本等。")
    public Map<String, String> getSystemInfo() {
        Map<String, String> info = new HashMap<>();
        info.put("os.name", System.getProperty("os.name"));
        info.put("os.version", System.getProperty("os.version"));
        info.put("os.arch", System.getProperty("os.arch"));
        info.put("java.version", System.getProperty("java.version"));
        info.put("user.name", System.getProperty("user.name"));
        return info;
    }
}

3. 组装为 ToolCallbackProvider

package com.example.mcp.server.config;

import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.example.mcp.server.service.SystemService;
import com.example.mcp.server.service.WeatherService;

@Configuration
public class McpServerConfig {

	@Bean
	public ToolCallbackProvider customTools(WeatherService weatherService, SystemService systemService) {
		return MethodToolCallbackProvider.builder().toolObjects(weatherService, systemService).build();
	}
}

配置 Chat Client

1. 向 application.properties 文件中添加模型配置（这里使用Sealos AI Proxy）

spring.ai.openai.api-key=your api key
spring.ai.openai.base-url=https://aiproxy.gzg.sealos.run
spring.ai.openai.chat.options.model=qwen-coder-plus

2. 添加配置类

package com.example.mcp.client.config;

import java.util.List;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
import org.springframework.ai.chat.memory.InMemoryChatMemory;
import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.modelcontextprotocol.client.McpSyncClient;
import jakarta.annotation.Resource;

@Configuration
public class ChatClientConfig {

	@Resource(name = "customTools")
	private ToolCallbackProvider customToolCallbackProvider;

	@Bean
	public ChatClient chatClient(ChatClient.Builder builder, List<McpSyncClient> mcpSyncClients) {
		return builder
				.defaultAdvisors(new SimpleLoggerAdvisor(), new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
				.defaultTools(new SyncMcpToolCallbackProvider(mcpSyncClients))
				.defaultTools(customToolCallbackProvider)
				.build();
	}
}

构建 Chat Rest API

DTO

1. ChatRequest

package com.example.mcp.client.model;

import lombok.Data;

@Data
public class ChatRequest {

	private String message;
}

2. ChatResponse

package com.example.mcp.client.model;

import lombok.Data;

@Data
public class ChatResponse {

	private String content;
}

Controller

1. ChatController

package com.example.mcp.client.controller;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.example.mcp.client.model.ChatRequest;
import com.example.mcp.client.model.ChatResponse;

import jakarta.annotation.Resource;

@RestController
@RequestMapping("/api/chat")
public class ChatController {

	@Resource
	private ChatClient chatClient;

	@PostMapping
	public ResponseEntity<ChatResponse> chat(@RequestBody ChatRequest request) {
		ChatResponse response = new ChatResponse();
		response.setContent(chatClient.prompt().user(request.getMessage()).call().content());
		return ResponseEntity.ok(response);
	}
}

对话验证

1. 有哪些工具可以使用
2. 洛杉矶今天天气如何
3. 数据中一共有多少张表
4. 请在目录D:\tmp下创建空白文件： hello MCP.txt，并写入内容：Hi~

参考

1. docs.spring.io/spring-ai/r...
2. github.com/spring-proj...
3. mcpcn.com/docs/