Spring AI + MCP实战避坑指南：从零搭建到高效调优（血泪经验版）

1. 环境准备：别让你的项目“胎死腹中”

大家好，我是老张，一个在Java和AI领域摸爬滚打了十来年的老码农。最近Spring AI和MCP（Model Context Protocol）火得一塌糊涂，我也跟风搞了一把，结果踩的坑比过去一年都多。今天我就把这些血泪教训掰开揉碎了讲给你听，目标是让你看完这篇文章，能绕开我掉进去的所有坑，顺顺利利地把服务搭起来。

首先，咱们得把地基打牢。环境配置这一步看似简单，但很多人就是在这里栽了跟头，项目还没开始就“胎死腹中”。我见过太多人兴冲冲地打开IDE，结果第一步就被Java版本卡住，或者被Maven依赖搞得焦头烂额。所以，咱们先别急着写代码，把准备工作做扎实了，后面才能事半功倍。

1.1 Java与Maven：版本不对，一切白费

Spring AI这玩意儿对Java版本要求不低，官方说至少17，但我强烈建议你直接上JDK 21。别问为什么，问就是我用17的时候遇到过一些奇怪的类加载问题，升级到21之后世界都清净了。你可以去Oracle官网或者Adoptium下载，安装完后记得把环境变量里的JAVA_HOME和PATH都更新了。验证方法很简单，打开命令行，输入java -version和javac -version，看看输出是不是21。别小看这一步，我帮同事排查问题，十次里有三次都是环境变量没配对。

Maven版本也是个坑。我一开始用的是3.6.0，结果拉取Spring AI的里程碑仓库（Milestone）时总是超时或者报错。后来换成Maven 3.9.6，一下子就顺畅了。所以，听我一句劝，别在构建工具上省时间。安装好后，同样用mvn -v检查一下。这里有个小技巧：看Maven输出的时候，留意一下它用的Java版本是不是你刚装的21，有时候系统里装了好几个JDK，Maven可能偷偷用了老的。

1.2 前期验证神器：Cherry Studio

在咱们自己的客户端没写好之前，总得有个东西来测试MCP服务端是不是真的跑通了吧？这时候就需要一个现成的MCP客户端。我试过好几个，Cherry Studio是其中对新手最友好的一个，图形化界面，配置简单，拿来验证功能再合适不过。

你去它的官网下载安装包，安装过程没啥好说的。打开后，重点在“设置”里。你需要配置一个大模型，因为最终是我们的MCP服务端和这个大模型对话，由大模型来决定什么时候调用我们的工具。我推荐用DeepSeek，原因很简单：不用折腾那些网络配置，直接填API Key就能用，对于快速验证来说非常方便。配置好API Key后点“检测”，通了就行。然后回到主聊天界面，选一下你刚配置的模型，随便问个问题，比如“你好”，看看它能不能正常回复。这一步是确保Cherry Studio本身能正常工作，排除掉客户端自身的问题，这样后面测试MCP服务时，如果出问题，我们才能锁定是服务端的原因。

2. 项目创建与依赖管理：避开版本冲突的雷区

好了，环境搞定，咱们打开IDEA，准备创建项目。这一步又有几个隐藏的坑点，一不留神就会导致后面依赖怎么都导不进来。

2.1 创建Spring Boot项目的两个关键选择

点击新建项目，选择Spring Initializr。这里第一个坑就是Server URL。默认的https://start.spring.io没问题，但有时候网络抽风，或者公司内网有镜像，你可能会想换一个。我强烈建议你不要改，就用官方的这个地址。因为Spring AI的依赖目前还在里程碑仓库里，很多国内的镜像源同步不及时，你换了URL，后续在IDE里通过图形界面添加依赖时，很可能根本找不到spring-ai相关的包，到时候还得手动改pom.xml，更麻烦。

第二个选择是Spring Boot版本。选3.5.3或更高。我写这篇文章时用的是3.5.3，稳得很。别选太老的，比如3.2.x，可能不兼容Spring AI的最新特性。至于依赖，先啥都不用选，我们后面手动在pom.xml里加，这样更清晰，避免初始化器引入一些我们不需要的包。

2.2 POM文件：依赖配置的血泪史

项目创建好了，重头戏也是噩梦开始的地方——pom.xml。Spring AI版本迭代太快了，今天还能用的依赖，明天可能就因为仓库更新而报错。下面是我趟过无数坑之后，总结出来的一个能跑通的配置，你直接复制过去，能解决90%的依赖问题。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0%20https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.3</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>mcp-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>mcp-demo</name>
    <description>Demo project for Spring AI MCP</description>

    <properties>
        <java.version>21</java.version>
        <!-- 重点：Spring AI 版