Spring AI alibaba MCP协议

本文为个人学习笔记整理，仅供交流参考，非专业教学资料，内容请自行甄别。

---

前言

  本篇主要介绍MCP协议，以及如何开发MCP协议的服务端，客户端；stdio和sse两种开发模式，MCP的部署方案。

---

一、MCP协议

1.1、概述

  MCP 旨在充当 AI 大模型与外部工具、数据源之间的 “万能插座”，解决 AI 模型与外部资源，如数据库、API、本地文件等的交互碎片化问题，统一通信规范，让不同大模型能够通过统一接口调用各类工具，无需重复适配开发。
  通过MCP协议，可以接入第三方的API，而不需要用户自己再编写工具，是对于工具调用的一种优化。
  主要分为了三个角色：

• MCP Host：是发起请求的 AI 应用程序，如聊天机器人、AI 驱动的 IDE、Claude Desktop 等，主要职责是接收用户输入，与大模型交互生成指令，并在大模型需要调用外部工具时触发 MCP 流程。
• MCP Client：作为 MCP Host 与 MCP Server 之间的桥梁，负责与 MCP Server 建立持久连接，将大模型的请求翻译为 MCP 标准格式并发送给 MCP Server，同时接收 MCP Server 的响应并返回给 MCP Host。
• MCP Server：是提供特定功能的外部程序，能够连接各种数据源，如 Google Drive、Slack、GitHub、数据库和 Web 浏览器等，主要职责是提供标准化接口和工具类，支持访问本地或远程资源，执行具体的工具调用，并返回结果。

  目前有一些主流的MCP应用市场，如mcp.so，或阿里云百炼平台。

1.2、MCP架构

  MCP由两层组成:

• 数据层：定义基于 JSON-RPC 的客户端-服务器通信协议,包括生命周期管理以及核心原语,例如工具、资源、提示和通知。
• 传输层：定义实现客户端与服务器之间数据交换的通信机制和通道,包括传输专用的连接设置、消息框接和授权。

  数据层实现了基于JSON-RPC 2.0的交换协议,该协议定义了消息结构和语义。 此层包括:

• Lifecycle management生命周期管理：处理客户端与服务器之间的连接初始化、通信和连接终止
• Server features服务器功能：使服务器能够提供核心功能,包括用于人工智能操作的工具、上下文数据资源,以及客户端之间交互模板的提示
• Client features客户端功能：允许服务器向客户端请求从主机 LLM 进行采样、从用户中获取输入,并向客户端记录消息
• Utility features实用功能：支持用于远程操作的实时更新通知和进度跟踪等附加功能

  传输层管理客户端与服务器之间的通信通道和身份验证。它负责连接建立、消息框接以及MCP参与者之间的安全通信。
  MCP支持两种传输机制:

• Stdio传输：使用标准输入/输出流,在同一设备上实现本地进程之间的直接过程通信,提供最佳性能,且无网络开销。
• SSE传输：使用 HTTP POST 用于客户端到服务器的消息,并可选使用服务器发送事件以实现流媒体功能。此传输支持远程服务器通信,并支持标准的HTTP身份验证方法,包括无记名令牌、API密钥和自定义报头。

二、使用MCP

  以在IDEA中使用Amap Maps（高德地图MCP）为例，采用的是stdio的本地方式，首先需要在项目中引入依赖：

<!--        mcp服务--><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId><version>1.0.0-M6</version></dependency>

  然后在resources目录下增加配置文件mcp-servers.json，官方提供了一个默认的配置，但是我在windows下实际操作是不可行的，包括网上教程说的在windows下要将npx改成npx.cmd

  如果引入官方的配置，项目启动不了，可以尝试以下命令，在IDEA的终端中依次执行，我这里采用的node版本是22.14.0，镜像源是官方：

# 1、全局安装
npm install -g @amap/amap-maps-mcp-server
# 2、查看全局npm包的安装路径
npm config get prefix
# 3、查找启动类
cd 第二步的结果\node_modules\@amap\amap-maps-mcp-server
# 4、在包目录下，查看 package.json 中的 "main" 或 "bin" 字段
Get-Content package.json | Select-String -Pattern '"main"|"\bin"'

{"mcpServers": {"amap-maps": {"command": "node","args": ["第二步的结果\\第四步的结果","--api-key","换成你自己的apikey"],"env": {"AMAP_MAPS_API_KEY": "换成你自己的apikey"}}}
}

  还需要在application.yml中加入：

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

  然后在应用中注入：

    @Resourceprivate ToolCallbackProvider toolCallbackProvider;/*** 测试mcp* @param message* @param chatId* @return*/public String doChatWithMcp(String message, String chatId) {ChatResponse response = chatClient.prompt().user(message).advisors(spec -> spec.param(CHAT_MEMORY_CONVERSATION_ID_KEY, chatId).param(CHAT_MEMORY_RETRIEVE_SIZE_KEY, 10)).tools(toolCallbackProvider).call().chatResponse();String content = response.getResult().getOutput().getText();return content;}

  启动项目，在自定义的日志拦截器中打上断点观察，发现已经加入了MCP提供的工具。

三、MCP客户端和服务端开发

3.1、MCP服务端开发

  MCP的服务端开发，有两种形式，第一是stdio本地模式，和sse远程模式，首先我们新建一个项目，在进行MCP开发时，建议按照单一职责原则，一个类型的MCP应用，单独放在一个项目中。在创建项目后，需要引入依赖：

        <dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-mcp-server-webmvc-spring-boot-starter</artifactId><version>1.0.0-M6</version></dependency>

3.1.1、stdio模式

  首先编写配置文件：

spring:ai:mcp:server:name: image-search-mcp-serverversion: 1848type: SYNC# stdiostdio: true# stdiomain:web-application-type: nonebanner-mode: off

  然后进行工具编写，这里的工具是根据的教程，使用了pexels搜图API，工具开发的流程和上一篇提到的相同，同样是注解模式，使用@Tool和@ToolParam进行标记：

@Service
public class ImageSearchTool {// 替换为你的 Pexels API 密钥（需从官网申请）private static final String API_KEY = "换成你自己的";// Pexels 常规搜索接口（请以文档为准）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) {return "Error search image: " + e.getMessage();}}/*** 搜索中等尺寸的图片列表** @param query* @return*/public List<String> searchMediumImages(String query) {// 设置请求头（包含API密钥）Map<String, String> headers = new HashMap<>();headers.put("Authorization", API_KEY);// 设置请求参数（仅包含query，可根据文档补充page、per_page等参数）Map<String, 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());}
}

  最后需要在配置类中注册Bean，加入自定义的工具，这里直接加在了启动类中，因为Spring Boot的启动类本身就可以作为配置类，@SpringBootApplication复合注解包含了@Configuration。

@SpringBootApplication
public class ImageSearchMcpServerApplication {public static void main(String[] args) {SpringApplication.run(ImageSearchMcpServerApplication.class, args);}@Beanpublic ToolCallbackProvider imageSearchTools(ImageSearchTool imageSearchTool){return MethodToolCallbackProvider.builder().toolObjects(imageSearchTool).build();}
}

  在stdio模式下，还需要将整个应用打包成jar包：

---

  上述的是stdio模式，服务端的开发，在客户端，同样需要在json配置文件中加入服务端的信息，这里的env，可以向服务端传递一些环境参数，服务端可以采用System.env获取。

{"mcpServers": {"image-search-mcp-server": {"command": "java","args": ["-Dspring.ai.mcp.server.stdio=true","-Dspring.main.web-application-type=none","-Dlogging.pattern.console=","-jar","image-search-mcp-server/target/image-search-mcp-server-0.0.1-SNAPSHOT.jar"],"env": {}}}
}

  然后客户端就可以启动项目，流程和二、使用MCP中的类似。

3.1.2、sse模式

  服务端采用sse远程模式，则需要编写配置文件：

spring:ai:mcp:server:name: image-search-mcp-serverversion: 1848type: SYNC# ssestdio: false

  工具的编写和注册和本地模式相同，sse模式不用打jar包，而是需要启动项目。注意端口和客户端的不能冲突。

---

  客户端则需要修改配置：

spring:ai:mcp:client:sse:connections:server1:url: http://localhost:8081

  然后启动项目进行测试。

四、MCP远程部署

  MCP服务，除了可以部署在自己的服务器上，还可以托管在第三方的云平台上，比如阿里云百炼平台-MCP
  根据官方文档，首先进入管理页面，点击右上角的创建MCP服务：

  使用默认的方式即可：

  这里的安装方式，官方只提供了三种：

• npx是基于js语法开发的MCP服务的部署
• uvx是基于python开发的MCP服务的部署
• sse是基于java的，但是需要本地启动服务。

  为了演示该功能，采用npx的模式，进行设置，然后提交部署：


  选择自定义的MCP