Agent开发 - 开发MCP图片搜索服务（一）（部署在下一篇文章）

一、MCP服务端开发1. 搜索网址【Free Image and Video API – Pexels】点击Your API Key填写项目信息生成API Key2. 在项目根目录下新建moudle,名称自己定义填写初始化moudle信息修改你的pom.xml中spring-boot版本为你现在项目正在使用的版本注意,建议在新项目中单独打开该模块,不要直接在原项目的的子文件夹中操作,否则可能出现路径上的问题。3. 引入必要的依赖,包括Lombok、hutool工具库和Spring Al MCP服务端依赖!-- lombok -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency !-- hutool工具库 -- dependency groupIdcn.hutool/groupId artifactIdhutool-all/artifactId version5.8.37/version /dependency有Stdio、WebMVCSSE同时支持stdio和sse远程和WebFluxSSE三种服务端依赖可以选选择,开发时只需要填写不同的配置,开发流程都是一样的。此处我们选择引入WebMVC:!-- mcp-server-webmvc webmvc同时支持stdio和sse -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-webmvc-spring-boot-starter/artifactId version1.0.0-M6/version /dependency引入这个依赖后,会自动注册SSE端点,供客户端调用。包括消息和SSE传输端点:文档网址【Untitled :: Spring AI Reference】4. 在resources目录下编写服务端配置文件这里我们编写两套配置方案,分别实现stdio和SSE模式的传输① stdio配置application-stdio.yml需关闭web支持spring: ai: mcp: server: name: yu-image-search-mcp-server version: 0.0.1 type: SYNC # stdio stdio: true # stdio main: web-application-type: none banner-mode: off② sse配置application-sse.yml需关闭stdio模式spring: ai: mcp: server: name: yu-image-search-mcp-server version: 0.0.1 type: SYNC # sse stdio: false③ 然后编写主配置文件application.yml,可以灵活指定激活哪套配置:spring: application: name: algo-image-search-mcp profiles: # 指定激活stdio或sse配置文件 active: stdio # 指定服务端口号 server: port: 81275. 编写图片搜索服务类在tools包下新建ImageSearchTool,使用Tool注解标注方法,作为MCP服务提供的工具package com.jingdong.algoimagesearchmcp.tools; import cn.hutool.core.util.StrUtil; import cn.hutool.http.HttpUtil; import cn.hutool.json.JSONObject; import cn.hutool.json.JSONUtil; import lombok.extern.slf4j.Slf4j; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Service; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.stream.Collectors; Service Slf4j public class ImageSearchTool { // 你的api_key密钥 (可在yml文件中配置用Valude注解拉取API_key的值) Value(${pexels.api-key}) private String API_KEY; // Pexels 常规搜索接口请以文档为准 API文档参考地址【https://www.pexels.com/api/documentation/#photos-search】 private static final String API_URL https://api.pexels.com/v1/search; Tool(description search image from web) public String searchImage(ToolParam(description Search query keyword) String query) { try { return String.join(,, searchMediumImages(query)); } catch (Exception e) { log.error(error search image from mcp server - errorMessage:{},e.getMessage()); return error search image: e.getMessage(); } } // helper methods /** * 搜索中等尺寸的图片列表 * * param query * return */ public ListString searchMediumImages(String query) { // 设置请求头包含API密钥 MapString, String headers new HashMap(); headers.put(Authorization, API_KEY); // 设置请求参数仅包含query可根据文档补充page、per_page等参数 MapString, Object params new HashMap(); params.put(query, query); // 发送 GET 请求 String response HttpUtil.createGet(API_URL) .addHeaders(headers) .form(params) .execute() .body(); // 解析响应JSON假设响应结构包含photos数组每个元素包含medium字段 return JSONUtil.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()); } }6. 编写单元测试类做集成测试真实调用工具验证工具是否可用package com.jingdong.algoimagesearchmcp.tools; import jakarta.annotation.Resource; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.util.Assert; SpringBootTest DisplayName(图片搜索测试类) public class ImageSearchToolTest { Resource private ImageSearchTool imageSearchTool; Test DisplayName(测试图片搜索工具) void searchImage(){ String result imageSearchTool.searchImage(奈克瑟斯奥特曼); Assert.notNull(result,查询结果不应为空); } }可以看到返回了很多图片网址7. 在主类中通过定义ToolCallbackProvider Bean来注册工具:package com.jingdong.algoimagesearchmcp; import com.jingdong.algoimagesearchmcp.tools.ImageSearchTool; import org.springframework.ai.tool.ToolCallbackProvider; import org.springframework.ai.tool.method.MethodToolCallbackProvider; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.Bean; SpringBootApplication public class AlgoImageSearchMcpApplication { public static void main(String[] args) { SpringApplication.run(AlgoImageSearchMcpApplication.class, args); } /** * 注册图片搜索工具提供者Provider,供MCP Client访问时获取tools调用MCP Server的工具 * param imageSearchTool 图片搜索工具类 * return 工具调用Provider */ Bean public ToolCallbackProvider imageSearchTools(ImageSearchTool imageSearchTool){ return MethodToolCallbackProvider .builder() .toolObjects(imageSearchTool) .build(); } }8. 最后使用Maven Package命令将此项目打包称jar包供后续MCP 客户端依赖使用⭐① 前置要求确保你们pom文件中引入了maven plugin插件如下情况 1项目有 spring-boot-starter-parent绝大多数 SpringBoot 项目直接用最简配置在 pom.xml 的buildplugins节点内添加xmlplugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin情况 2项目没有 parent需要显式指定版本 执行目标xmlplugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId version3.2.0/version !-- 和你springboot版本保持一致 -- executions execution goals goalrepackage/goal /goals /execution /executions /pluginrepackage是 spring-boot-maven-plugin 的目标作用将 maven 正常打包生成的普通 jar重新打包为 SpringBoot 可执行的胖 jar把项目依赖的第三方 jar 一并打进包内内置 SpringBoot 启动器支持直接使用java -jar xxx.jar运行。② 执行mvn package命令会在target目录下生成可执行的JAR包,等会儿客户端调用时会依赖这个文件:⭐如何显示target文件项目视图右上角三点 → 勾选Show Excluded Files或者 File→Settings→Build, Execution, Deployment→Directories取消 target 的 Excluded 标记。然后就可以看到了。第一个jar包就是我们要使用的可运行jar包。SpringBoot 项目会同时生成普通 jar 和xxx.jar.original文件带 original 是原始精简 jar不带 original 的是可执行 fat jar。二、MCP 客户端开发下一步是在根项目中开发客户端来调用我们刚才创建的【图片搜索服务】。1. 先引入必要的MCP客户端依赖!-- 添加Spring AI MCP Client starter依赖 -- !-- Source: https://mvnrepository.com/artifact/org.springframework.ai/spring-ai-mcp-client-spring-boot-starter -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-spring-boot-starter/artifactId version1.0.0-M6/version scopecompile/scope /dependency注意 要保证你的客户端依赖和你的服务端形式一致。2. 先测试stdio传输方式① 在 mcp-servers.json配置文件中新增MCPServer的配置,通过java命令执行我们刚刚打包好的jar包。代码如下:{ mcpServers: { algo-image-search-mcp-server: { command: java, args: [ -Dspring.ai.mcp.server.stdiotrue, -Dspring.main.web-application-typenone, -Dlogging.pattern.console, -jar, algo-image-search-mcp/target/algo-image-search-mcp-0.0.1-SNAPSHOT.jar ], env: {} } } }注意args中target前面的目录为你的图片搜索服务的项目根目录名称不是stdio模式的服务名称② 编写单元测试代码调用我们注册的图片搜索工具Test DisplayName(测试图片搜索MCP Server) void doChatWithImageSearchMCpServer(){ // 测试图片搜索MCP String chatId UUID.randomUUID().toString(); String userMessage 帮我搜一些人类幼崽的图片; String result loveApp.doChatWithMcp(userMessage, chatId); Assert.notNull(result,大模型应该回复有内容的信息); }③ debug打断点查看是否注册到图片搜索工具并观察返回结果是否包含图片urldebug可以看到我们request请求中的FunctionCallbacks中的第一个tool就是searchImage,说明MCP Server提供的图片搜索工具被成功加载可以看到结果中包含图片url调用成功3. 再测试sse连接方式① 修改server端application.yml指定的配置文件为ssespring: application: name: algo-image-search-mcp profiles: # 指定激活stdio或sse配置文件 active: sse # 只修改这一行为sse即可 # 指定服务端口号 server: port: 8127② debug模式启动服务端的启动类模拟【图片搜索MCP服务】在远程运行url为本地localhost,端口port为8127同时debug模式是为了我们后续给服务端打断点进行调用服务端工具时的调试③ 修改服务端application.yml中使用MCP的形式为sse原来为stdiospring: ai: # mcp client 客户端配置 mcp: client: sse: # connections本质是一个 Mapserver1就是 map 的 key用来区分多个不同的 MCP 服务连接你可以随便起名 connections: # 如果你后面要在代码里单独拿到指定这个 MCP 客户端实例才会用到这个 key 名字只是自动注入全部 ToolCallbackProvider、直接.tools(toolCallbackProvider)使用的话改名字完全无影响。 algo-image-search-mcp-server: url: http://localhost:8127 # stdio: # # 指定MCP服务器配置文件路径推荐项目根目录下的json文件。 classpath:mcp-servers.json → 读取资源目录里打包进 jar 的文件打包部署后依然正常生效推荐配置文件写法→ Spring Boot 应用启动时读取放在 resources 下打进 jar # # 项目根目录的 .mcp.json → 不属于 classpath 资源Spring 默认不会读取仅给 Claude Code IDE 使用 # # classpath:mcp-servers.json对应文件位置src/main/resources/mcp-servers.json # # 编译后会自动复制到 target/classes/mcp-servers.jsonSpring 就能读到。 # servers-configuration: classpath:mcp-servers.json④ debug执行stdio时候写的客户端单元测试可以看到客户端request请求中检索到了【图片搜索工具类searchImage】服务端也看到了请求打进来了说明工具被客户端注册并成功执行了客户端单元测试AI回复也包含图片url,成功了至此MCP服务端和客户端开发完成MCP部署在下一篇文章进行阐述