工具调用MCP_Server 开发梳理

一、MCP 简介

MCP（Model Context Protocol）是 Spring AI 提供的工具调用协议，允许 AI 模型通过标准化接口调用外部工具。本项目是一个基于 Spring Boot 的图片搜索 MCP 服务器实现。

三、开发步骤

步骤 1：创建 Maven 项目

在pom.xml中添加以下核心依赖：

<!-- 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></dependency><!-- Hutool 工具库（可选，用于HTTP请求和JSON处理） --><dependency><groupId>cn.hutool</groupId><artifactId>hutool-all</artifactId><version>5.8.37</version></dependency>

步骤 2：创建工具类

创建一个 Spring Service 类，并使用@Tool注解标记工具方法：

packagecom.imagesearchmcpserver.tools;importorg.springframework.ai.tool.annotation.Tool;importorg.springframework.ai.tool.annotation.ToolParam;importorg.springframework.stereotype.Service;@ServicepublicclassImageSearchTool{@Tool(description="search image from web")publicStringsearchImage(@ToolParam(description="Search query keyword")Stringquery){// 实现工具逻辑returnsearchMediumImages(query).toString();}}

关键注解说明：

步骤 3：配置工具提供者

在启动类中配置ToolCallbackProviderBean：

@SpringBootApplicationpublicclassYuImageSearchMcpServerApplication{publicstaticvoidmain(String[]args){SpringApplication.run(YuImageSearchMcpServerApplication.class,args);}@BeanpublicToolCallbackProviderimageSearchTools(ImageSearchToolimageSearchTool){returnMethodToolCallbackProvider.builder().toolObjects(imageSearchTool).build();}}

步骤 4：配置应用

创建三种配置文件：

4.1application.yml（默认配置）

spring:application:name:image-search-mcp-serverprofiles:active:sse# 默认使用 SSE 模式server:port:8127

4.2application-sse.yml（SSE 模式）

spring:ai:mcp:server:name:image-search-mcp-serverversion:0.0.1type:SYNCstdio:false# 启用 HTTP/SSE 模式

4.3application-stdio.yml（标准输入输出模式）

spring:ai:mcp:server:name:image-search-mcp-serverversion:0.0.1type:SYNCstdio:true# 启用标准输入输出模式main:web-application-type:none# 非 Web 应用banner-mode:off# 关闭启动 Banner

步骤 5：实现业务逻辑

在工具类中实现具体的业务逻辑。本项目以 Pexels 图片搜索 API 为例：

publicList<String>searchMediumImages(Stringquery){// 1. 设置请求头（包含 API 密钥）Map<String,String>headers=newHashMap<>();headers.put("Authorization",API_KEY);// 2. 设置请求参数Map<String,Object>params=newHashMap<>();params.put("query",query);// 3. 发送 HTTP 请求Stringresponse=HttpUtil.createGet(API_URL).addHeaders(headers).form(params).execute().body();// 4. 解析响应并提取图片 URLreturnJSONUtil.parseObj(response).getJSONArray("photos").stream().map(photoObj->(JSONObject)photoObj).map(photoObj->photoObj.getJSONObject("src")).map(photo->photo.getStr("medium")).filter(StrUtil::isNotBlank).collect(Collectors.toList());}

四、启动方式

方式 1：SSE 模式（默认）

# 开发环境运行./mvnw spring-boot:run# 或打包后运行./mvnw clean packagejava-jartarget/image-search-mcp-server-0.0.1-SNAPSHOT.jar

方式 2：Stdio 模式

./mvnw spring-boot:run -Dspring-boot.run.profiles=stdio# 或java-jartarget/image-search-mcp-server-0.0.1-SNAPSHOT.jar--spring.profiles.active=stdio

五、两种运行模式对比

六、MCP 工具调用流程

┌─────────────────┐ HTTP/SSE ┌──────────────────────┐ │ AI 客户端 │ ────────────────► │ MCP Server │ │ (如 LlamaIndex)│ │ (Spring Boot) │ └─────────────────┘ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ ToolCallbackProvider│ │ 发现并注册工具方法 │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ ImageSearchTool │ │ 执行具体业务逻辑 │ └──────────────────────┘

七、扩展开发

添加新工具

只需创建新的 Service 类并添加@Tool注解：

@ServicepublicclassWeatherTool{@Tool(description="Get current weather")publicStringgetWeather(@ToolParam(description="City name")Stringcity){// 实现天气查询逻辑return"Weather in "+city+": sunny";}}

更新工具提供者

在启动类中添加新工具：

@BeanpublicToolCallbackProvidertools(ImageSearchToolimageSearchTool,WeatherToolweatherTool){returnMethodToolCallbackProvider.builder().toolObjects(imageSearchTool,weatherTool).build();}

八、注意事项

1. API Key 管理：敏感信息如 API Key 应通过环境变量或配置中心管理，避免硬编码
2. 错误处理：工具方法应妥善处理异常，返回友好的错误信息
3. 参数校验：对输入参数进行必要的校验
4. 日志记录：建议添加适当的日志记录便于排查问题
5. 依赖版本：确保 Spring AI BOM 版本与 MCP Server 依赖版本一致

九、前端调用方式

9.1 前端项目结构

ai-agent-frontend/ ├── src/ │ ├── api/ │ │ └── index.js # API 封装与 SSE 连接 │ ├── components/ │ │ └── ChatRoom.vue # 聊天组件 │ ├── views/ │ │ └── SuperAgent.vue # AI 超级智能体页面 │ └── main.js # 入口文件 ├── package.json └── vite.config.js

9.2 核心调用流程

前端通过SSE (Server-Sent Events)与后端建立实时通信，实现流式响应。

9.2.1 SSE 连接封装

// src/api/index.jsimportaxiosfrom'axios'constAPI_BASE_URL=process.env.NODE_ENV==='production'?'/api':'http://localhost:8123/api'exportconstconnectSSE=(url,params,onMessage,onError)=>{constqueryString=Object.keys(params).map(key=>`${encodeURIComponent(key)}=${encodeURIComponent(params[key])}`).join('&')constfullUrl=`${API_BASE_URL}${url}?${queryString}`consteventSource=newEventSource(fullUrl)eventSource.onmessage=event=>{letdata=event.dataif(data==='[DONE]'){if(onMessage)onMessage('[DONE]')}else{if(onMessage)onMessage(data)}}eventSource.onerror=error=>{if(onError)onError(error)eventSource.close()}returneventSource}

9.2.2 调用 AI 聊天接口

// AI超级智能体聊天exportconstchatWithManus=(message)=>{returnconnectSSE('/ai/manus/chat',{message})}

9.3 组件层面调用

在 Vue 组件中使用 SSE 连接：

// src/views/SuperAgent.vueimport{ref,onMounted,onBeforeUnmount}from'vue'import{chatWithManus}from'../api'constmessages=ref([])constconnectionStatus=ref('disconnected')leteventSource=nullconstsendMessage=(message)=>{// 添加用户消息addMessage(message,true,'user-question')// 关闭之前的连接if(eventSource){eventSource.close()}connectionStatus.value='connecting'letmessageBuffer=[]eventSource=chatWithManus(message)eventSource.onmessage=(event)=>{constdata=event.dataif(data&&data!=='[DONE]'){messageBuffer.push(data)// 根据标点或长度判断是否创建新消息气泡constlastChar=data.charAt(data.length-1)consthasCompleteSentence=['。','！','？','…'].includes(lastChar)constisLongEnough=messageBuffer.join('').length>40if(hasCompleteSentence||isLongEnough){addMessage(messageBuffer.join(''),false,'ai-answer')messageBuffer=[]}}if(data==='[DONE]'){if(messageBuffer.length>0){addMessage(messageBuffer.join(''),false,'ai-final')}connectionStatus.value='disconnected'eventSource.close()}}eventSource.onerror=(error)=>{connectionStatus.value='error'eventSource.close()}}

9.4 完整调用链路

┌─────────────────┐ HTTP/SSE ┌──────────────────────┐ 调用工具 ┌──────────────────────┐ │ Vue 前端 │ ────────────────► │ 后端 API Gateway │ ─────────────► │ MCP Server │ │ SuperAgent.vue │ /ai/manus/chat │ (端口 8123) │ /mcp/tools │ (端口 8127) │ └─────────────────┘ └──────────────────────┘ └──────────────────────┘ ▲ │ │ │ │ │ └─────────── SSE 流式响应 ◄───────────┴─────────── 工具执行结果 ◄───────────┘

9.5 前端配置说明

9.6 注意事项

1. 跨域处理：后端需配置 CORS 允许前端域名访问
2. 连接管理：发送新消息前需关闭旧连接，避免重复响应
3. 消息缓冲：SSE 可能分段传输，需缓冲后按语义合并
4. 异常处理：监听onerror事件，优雅处理连接断开
5. 资源清理：组件销毁前调用eventSource.close()释放资源