# spring-ai-mcp-demo-master

**Repository Path**: luckshi/spring-ai-mcp-demo-master

## Basic Information

- **Project Name**: spring-ai-mcp-demo-master
- **Description**: 使用spring ai创建mcp服务
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2025-06-15
- **Last Updated**: 2025-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# spring-ai-mcp-demo

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

- 修改 pom.xml 中的 Java 版本属性，适配本地已安装的 JDK（推荐 JDK 17 或 21）：
  ```
  <properties>
    <maven.compiler.source>17</maven.
    compiler.source>
    <maven.compiler.target>17</maven.
    compiler.target>
  </properties>
  ```
### 2. 环境验证步骤
1. 检查本地 JDK 版本：在命令行执行 java -version ，确认输出版本与 pom.xml 配置一致。
2. 验证 JAVA_HOME 环境变量：确保指向正确的 JDK 安装路径（如 D:\Program Files\Java\jdk-17.0.1 ）。
3. 清理 Maven 缓存：执行 mvn clean install 重新构建，避免旧编译产物干扰。
## 五、调试与问题排查
### 1. 常见问题及解决方法 （1）服务启动超时
- 现象 ：client 模块启动时抛出 TimeoutException ，提示创建 asyncToolCallbacksDeprecated bean 超时（20000ms）。
- 原因 ：与服务端通信超时，可能是服务端未启动、网络阻塞或防火墙限制。
- 解决 ：
  - 检查 sse-server/stdio-server 是否正常运行，查看 `mcp-server.log` 日志定位服务端启动问题。
  - 在 client 模块的 application.properties 中增加超时配置： spring.ai.mcp.client.timeout=30000 （延长至 30 秒）。
  - 关闭防火墙或添加端口例外（默认端口 8080，可通过 server.port 配置修改）。 （2）端口占用冲突
- 现象 ：启动时报错 Address already in use: bind ，提示 8080 端口被占用。
- 解决 ：
  - 终止占用进程：Windows 下执行 netstat -ano | findstr :8080 找到 PID，再通过 taskkill /PID <PID> /F 结束进程。
  - 修改端口配置：在 application.properties 中设置 server.port=8081 切换至未占用端口。
### 2. 日志调试技巧
- 日志文件 ：核心日志输出至项目根目录的 mcp-server.log，包含服务启动状态、请求处理流程、异常堆栈等关键信息。
- 日志级别调整 ：在 application.properties 中设置 logging.level.root=DEBUG 开启详细日志，辅助定位细粒度问题（如网络请求参数、AI 模型响应内容）。
### 3. 启动命令，进行本地mcp配置，我采用的是trae里边的配置

```
{
  "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",      
      "autoApprove": ["根据城市名称获取天气预报"]
    }
  }
}
```
然后启动服务：spring-ai-mcp-sse-server服务
![输入图片说明](mcp%E9%85%8D%E7%BD%AE.png)
![输入图片说明](%E6%99%BA%E8%83%BD%E4%BD%93%E9%85%8D%E7%BD%AEmcp.png)
![输入图片说明](mcp%E6%B5%8B%E8%AF%95.png)

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