基于Spring AI服务，开发MCP服务

大家好，好久没有写博客了，最近突然想写一些新的东西，如何开发mcp服务，本地如何调试。

一、项目概述

Spring AI MCP Demo 是一个基于 Spring 生态的多模块应用工程，主要围绕 AI 功能集成与服务通信展开，采用分层架构设计，包含客户端与服务端组件，支持标准 I/O 交互与服务器推送等多种通信模式。项目根目录位于 spring-ai-mcp-demo-master ，整体遵循 Maven 项目规范，通过模块化设计实现功能解耦。

二、模块结构与职责

　　1. 核心模块划分

项目包含三个子模块，各自承担不同角色：

spring-ai-mcp-client ：客户端模块，负责与服务端通信，集成 AI 功能调用能力，包含请求封装与响应处理逻辑。
spring-ai-mcp-sse-server ：SSE (Server-Sent Events) 服务端模块，通过 HTTP 长连接实现服务器向客户端的单向实时数据推送，适用于实时通知、数据流传输场景 spring-ai-mcp-sse-server 。
spring-ai-mcp-stdio-server ：标准 I/O 服务端模块，处理命令行输入输出交互，支持通过控制台与外部系统进行数据交换 spring-ai-mcp-stdio-server 。

　　2. 模块间关系

客户端模块（client）可分别与 SSE 服务端、STDIO 服务端通信，服务端模块间通过 MCP（Module Communication Protocol）协议实现内部交互，形成"多客户端-多服务端"的分布式通信架构。

三、技术栈详解

1. 核心框架与语言

Java ：主要开发语言，版本兼容 JDK 11/17（历史编译错误显示曾尝试使用 JDK 21 导致不兼容，需根据本地环境调整）。
Spring Boot ：基础框架，提供自动配置、依赖注入、嵌入式服务器等核心能力，简化应用开发与部署。
Spring AI ：AI 功能集成框架，项目命名中包含"spring-ai"，推测用于对接 AI 模型 API（如 OpenAI、本地大模型等），实现自然语言处理、数据分析等 AI 能力。
SSE (Server-Sent Events) ：由 sse-server 模块实现，基于 HTTP 协议的服务器推送技术，支持文本数据的单向流式传输，适用于实时天气更新、通知推送等场景。
MCP 协议：项目特有的模块通信协议，用于规范客户端与服务端、服务端之间的消息格式与交互流程，确保跨模块通信的一致性。
响应式编程：集成 Reactor Core 库，通过 Mono/Flux 实现异步非阻塞数据流处理，提升高并发场景下的系统响应性能（历史超时异常涉及 reactor-core 的 Mono 操作）。
Maven ：项目构建与依赖管理工具，通过各模块下的 pom.xml 文件声明依赖关系，支持打包为可执行 JAR（如 stdio-server 模块生成的 spring-ai-mcp-stdio-server.jar）。
Windows 环境：开发与运行环境为 Windows 系统，需注意文件路径格式（如使用反斜杠""）与环境变量配置（如 JAVA_HOME）。

2. 通信与架构

3. 构建与部署

四、JDK 版本配置

　　1. 版本兼容问题

项目曾出现"无效的目标发行版: 21"的 Maven 编译错误，原因是 stdio-server 模块的 pom.xml 中指定的 Java 版本与本地环境不匹配。解决方案为：

修改 pom.xml 中的 Java 版本属性，适配本地已安装的 JDK（推荐 JDK 17 或 21）：

<maven.compiler.source>17</maven.

compiler.source>

<maven.compiler.target>17</maven.

compiler.target>

</properties>

2. 环境验证步骤

检查本地 JDK 版本：在命令行执行 java -version ，确认输出版本与 pom.xml 配置一致。
验证 JAVA_HOME 环境变量：确保指向正确的 JDK 安装路径（如 D:\Program Files\Java\jdk-17.0.1 ）。
清理 Maven 缓存：执行 mvn clean install 重新构建，避免旧编译产物干扰。

五、调试与问题排查

1. 本地调试

1. 启动本地的工程：spring-ai-mcp-sse-server, spring-ai-mcp-stdio-server

2. 在trae或cline的MCP服务添加本地配置文件到mcp.json

复制代码

{
  "mcpServers": {
    "addOrMinus-service": {
      "disabled": false,
      "timeout": 30,
      "type": "stdio",
      "command": "java",
      "args": [
        "-jar",
        "D:/mcp/spring-ai-mcp-demo-master/spring-ai-mcp-stdio-server/target/spring-ai-mcp-stdio-server.jar"        
      ],
      "cwd": "D:/mcp/spring-ai-mcp-demo-master/spring-ai-mcp-stdio-server/target",
      "env": {
        "TIMEZONE": "Asia/Shanghai",
        "spring.ai.mcp.server.stdio":"true",
        "spring.main.web-application-type":"none",
        "spring.main.banner-mode":"off"
      }
    },
    "querweather-sse-mcp": {
      "url": "http://localhost:9090/sse",
      "transportType": "sse",
      "autoApproval": false,
      "requireManualConfirmation": true
    }
  }
}

3. 然后就可以在trae的对话框问问题了，比如，北京的天气如何

六、总结

Spring AI MCP Demo 工程通过 Spring Boot + Spring AI 构建了一套灵活的 AI 服务通信框架，结合 SSE 实时推送与标准 I/O 交互，满足多样化的业务场景需求。开发过程中需重点关注 JDK 版本兼容性、服务通信超时、端口冲突等常见问题，通过日志分析与配置调优保障系统稳定运行。后续可扩展更多 AI 功能模块，或集成服务发现、配置中心等中间件，进一步提升系统的可扩展性与可维护性。