CH 08MCP：模型上下文协议

8.1MCP 解决什么问题：工具的「USB 接口标准」

先看没有 MCP 时的困境：每个 AI 应用都要把各系统的工具代码抄一遍，升级不同步、权限难管控、还受语言限制。

MCP 是什么：一层一层拆开讲

MCP 与第 7 章 @Tool 的关系

MCP 协议长什么样：一次调用的真实报文

理解「stdio 模式 stdout 被污染就会解析失败」，前提是知道 MCP 在传什么。MCP 基于 JSON-RPC 2.0，一次「用户问订单 → 模型调工具」背后的报文大致是这样三步：

关键点：这些报文全是纯文本 JSON，通过 stdout / stdin 一行一行传。一旦 Server 往 stdout 多吐了一行启动日志、或一个 System.out.println，Client 读到的就不是合法 JSON，先报 Unexpected character ('-')，随后握手超时、连接彻底建不起来。这就是为什么 8.4 节不仅要关 Web 容器、禁 System.out，还必须把 Boot 自己的启动日志改道到 stderr——不是为了好看，是为了不让通信电线里灌杂音。

8.2架构与三大原语

三个角色：Host / Client / Server

把三个角色的关系再讲一遍「为什么这样分」：

Server 端 vs Client 端职责对照

Server 能暴露的三种能力（三大原语）

8.3三种传输方式：怎么连

传输方式决定了「Host 和 Server 之间用什么通道通信」。先给一张总表，再逐个拆开讲。

stdio：本地联调的首选，但必须理解「stdout 就是电线」

SSE 与 Streamable HTTP：远程形态

怎么选传输方式：一张决策表

课程实操顺序：先 stdio 跑通整条链路，再（选做）把 Server 改成 Streamable HTTP 独立部署。不要一上来就远程，否则你会花大量时间在「端口 / 代理 / 跨域」上，而不是学 MCP 本身。

[ERROR] Failed to execute goal ... : Cannot delete ...\target\mcp-order-server-1.0.0.jar
        （Windows 上是「另一个程序正在使用此文件，进程无法访问」）

# 列出所有命令行里带 mcp-order-server 的 java 进程
Get-CimInstance Win32_Process -Filter "Name='java.exe'" |
  Where-Object { $_.CommandLine -like '*mcp-order-server*' } |
  Select-Object ProcessId, CommandLine

# 确认无误后按 Id 逐个结束（把 12345 换成上面查到的 ProcessId）
Stop-Process -Id 12345 -Force

8.4写一个 MCP Server

下面从零建一个独立工程 mcp-order-server。本章无配套 lab 代码，所以全程「自建」：所有路径、类名、片段都按下面逐步操作，不要照抄别的教程的目录。

① 新建工程并加依赖（建议独立工程）

MCP Server 通常做成独立应用，不要和主应用混在一起——这样它才能被多个 AI 应用共享，也便于独立部署与权限治理。

1. 打开 start.spring.io，按下表选择：

   选项	选择
   Project / Language	Maven / Java
   Spring Boot	4.1.x（不要选 3.x）
   Group / Artifact	com.example / mcp-order-server
   Package name	com.example.mcporderserver
   Packaging / Java	Jar / 17
   Dependencies	先不加任何依赖（MCP starter 不在初始选项里，我们手动加）

2. Generate 下载 zip，解压到 D:/springai-lab/mcp-order-server，用 IDEA 打开（File → Open → 选中含 pom.xml 的那层）。

3. 打开 pom.xml，把下面片段完整粘贴进去（替换默认的依赖段，并补上 spring-ai-bom 的 dependencyManagement）。注意版本基准：Spring AI 2.0.1 + Boot 4.1.x + Java 17。

   <!-- 新建工程 mcp-order-server，pom 片段（stdio 形态） -->
   <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
     <version>4.1.1</version>
   </parent>
   
   <dependencies>
     <!-- 就这一个依赖，够了 -->
     <dependency>
       <groupId>org.springframework.ai</groupId>
       <artifactId>spring-ai-starter-mcp-server</artifactId>
     </dependency>
   
     <!-- ★ 不要加 spring-boot-starter-webmvc！ -->
     <!--   stdio 形态没有 HTTP 入口，加了只会启动一个用不上的 Tomcat， -->
     <!--   多一条往 stdout 打日志的路径（见 ②′ 的 logback 一节）。 -->
     <!--   要改远程 Streamable HTTP 形态时再换坐标，见 8.8 末尾。 -->
   </dependencies>
   
   <dependencyManagement>
     <dependencies>
       <dependency>
         <groupId>org.springframework.ai</groupId>
         <artifactId>spring-ai-bom</artifactId>
         <version>2.0.1</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
     </dependencies>
   </dependencyManagement>

4. 保存，等右下角 Maven 同步完成（首次约 1～3 分钟）。

② stdio 模式：一个配置文件 + 一个工具类

1. 在 src/main/resources/ 下右键 → New → File，文件名精确填 application.yml（若已存在就直接打开）。把下面内容整段粘贴覆盖：

   # src/main/resources/application.yml（本地联调用 stdio）
   spring:
     main:
       # ★ 关掉 Web 容器。注意：这只是第一步，不是全部 —— 见 ②′
       web-application-type: none
     ai:
       mcp:
         server:
           name: order-mcp-server        # 服务名，客户端会看到（会出现在 serverInfo.name 里）
           version: 1.0.0
           # ★ 2.0 变更：显式打开 stdio。Streamable HTTP 已成为默认传输，
           #    所以本地用 stdio 时必须显式声明，否则 server 不会走标准输入输出。
           stdio: true
           # 执行类型：SYNC（同步）/ ASYNC（异步，返回 Mono/Flux）
           type: SYNC
           # 是否把工具变更通知给客户端
           tool-change-notification: true

②′ 关键一步：把 Boot 的启动日志整体改道到 stderr（不做这步后面全废）

printf 时代的经验在这里失效——你以为「不打印」就行了，实际上 Boot 默认的日志输出目标就是 stdout，而 stdout 就是 MCP 的电线。唯一干净的做法：加一个 logback-spring.xml，把 ConsoleAppender 的 target 从 System.out 改成 System.err。这样人的日志照旧能看到（stderr 在终端里一样显示），协议流只走 stdout，互不干扰。

1. 在 src/main/resources/ 下右键 → New → File，文件名精确填 logback-spring.xml（不要叫 logback.xml，那样会绕过 Boot 的 profile 支持）。
2. 粘贴下面内容：

<?xml version="1.0" encoding="UTF-8"?>
<!-- src/main/resources/logback-spring.xml -->
<!-- ★★ 这个文件的唯一使命：把控制台日志从 stdout 挪到 stderr。 -->
<!--    stdio 模式下 stdout 是 MCP 的通信通道，任何人类可读日志写进去都会破坏协议。 -->
<configuration>

    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <target>System.err</target>   <!-- ★ 关键：默认是 System.out，必须改成 System.err -->
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>

</configuration>

# 特征 1：stdout 里混进了人类日志，客户端逐行解析时先在这里报错
Unexpected character ('-') ...            <!-- 因为日志行以时间戳/短横线开头 -->

# 特征 2：等待握手的时长恰好是 20 秒（SDK 默认 initializationTimeout）
搜关键字：timed out        <!-- 通常伴随 "after 20000ms" 之类的字样 -->

# 特征 3：最终死在 MCP 客户端自动配置上，应用没起来
搜关键字：MCP client       <!-- 表现为 Bean 创建失败 / Application run failed -->
搜关键字：APPLICATION FAILED TO START

③ 启动类

1. 在包 com.example.mcporderserver 上右键 → New → Java Class，名称精确填 McpOrderServerApplication，把下面内容粘贴进去：

// McpOrderServerApplication.java
@SpringBootApplication
public class McpOrderServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpOrderServerApplication.class, args);
    }
}

④ 写工具类：用 @McpTool，不是 @Tool

1. 在包 com.example.mcporderserver 上右键 → New → Java Class，名称精确填 OrderMcpTools。
2. 把下面完整内容粘贴进 OrderMcpTools.java 并保存。重点看两处：注解是 @McpTool / @McpToolParam（包 org.springframework.ai.mcp.annotation），类上有 @Component 让它成为 Spring bean。

// OrderMcpTools.java —— 注意：用 @McpTool，不是第 7 章的 @Tool！
@Component
public class OrderMcpTools {

    /**
     * ★ 2.0 变更：服务端暴露 MCP 能力要用 @McpTool / @McpToolParam，
     *   而不是给本地工具用的 @Tool / @ToolParam。两者语义不同：
     *   @Tool     = 让本应用的模型调用（第 7 章）
     *   @McpTool  = 通过 MCP 协议暴露给外部客户端
     *   包路径（2.0 起 MCP 注解已并入 Spring AI 本体）：
     *     org.springframework.ai.mcp.annotation.McpTool
     *     org.springframework.ai.mcp.annotation.McpToolParam
     */
    @McpTool(description = """
            查询指定订单号的当前状态与预计发货时间。
            当用户询问发货情况、物流状态时调用。
            不要用于查询退款进度或账户余额。
            """)
    public OrderStatus queryOrderStatus(
            @McpToolParam(description = "订单号，纯数字字符串，例如 2024001")
            String orderNo) {
        // 这里可以是真实数据库查询。教学演示用模拟数据。
        return switch (orderNo) {
            case "2024001" -> new OrderStatus(orderNo, "未发货", "2024-03-08");
            case "2024002" -> new OrderStatus(orderNo, "已发货", "-");
            default -> new OrderStatus(orderNo, "NOT_FOUND", "-");
        };
    }

    @McpTool(description = "列出某个客户最近 5 笔订单的订单号与状态")
    public List<OrderStatus> listRecentOrders(
            @McpToolParam(description = "客户姓名") String customerName) {
        return List.of(
                new OrderStatus("2024001", "未发货", "2024-03-08"),
                new OrderStatus("2023129", "已完成", "-"));
    }

    public record OrderStatus(String orderNo, String status, String promisedDate) {}
}

⑤ 关键一步：让 Server 发现你的工具

2.0 起这一步变得很简单：不用写任何配置类。 只要工具类是个 Spring bean 且方法上标了 @McpTool， MCP Server 的自动配置会通过注解扫描把它自动注册出去：

@Component          // ★ 必须是 Spring bean，否则扫描不到
public class OrderMcpTools {

    @McpTool(description = "查询指定订单号的当前状态与预计发货时间")
    public OrderStatus queryOrderStatus(
            @McpToolParam(description = "订单号，例如 2024001") String orderNo) {
        // …… 业务逻辑
    }
}
// 就这样，不需要 @Configuration，不需要 ToolCallbackProvider。

注解扫描的包范围可以配置（默认扫应用主类所在包及其子包）。如果你确实需要程序化注册 （例如工具来自第三方对象、或要按环境动态决定暴露哪些），再退回到 Provider 写法：

@Configuration
public class McpServerConfig {

    @Bean
    public ToolCallbackProvider orderToolsProvider(OrderMcpTools orderMcpTools) {
        return MethodToolCallbackProvider.builder()
                .toolObjects(orderMcpTools)
                .build();
    }
}

运行验证 ①：打包并确认 Server 能起

1. 打开 IDEA 底部 Terminal（或系统终端，先 cd 到工程目录），执行：

   # 进入工程目录（按你的实际路径）
   cd D:/springai-lab/mcp-order-server
   
   # 打包，跳过测试加快速度
   mvn clean package -DskipTests

   看到什么算通过：末尾出现 BUILD SUCCESS，且 target/ 下生成 mcp-order-server-1.0.0.jar（约 22 MB，是带依赖的 fat jar）。

   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time:  12.345 s          <!-- 时间因机器而异，只看 BUILD SUCCESS -->
   [INFO] mcp-order-server-1.0.0.jar 已生成于 target/

2. 先验一条确定型判据：stdout 必须是 0 字节。这一步比 Inspector 更重要，因为它能在你接客户端之前就把污染问题挡掉。把工程的 stdout / stderr 分别重定向到两个文件，跑 8 秒后强制结束：

   # Git Bash（IDEA 默认终端是 PowerShell，等价写法在下面）
   cd D:/springai-lab/mcp-order-server
   timeout 8 java -jar target/mcp-order-server-1.0.0.jar > out.txt 2> err.txt
   wc -c < out.txt     # ★ 必须是 0
   wc -l < err.txt     # 应该是 6 行左右（启动日志全在这里）
   
   # PowerShell 等价写法
   # $p = Start-Process java -ArgumentList '-jar','target\mcp-order-server-1.0.0.jar' `
   #        -RedirectStandardOutput out.txt -RedirectStandardError err.txt -PassThru
   # Start-Sleep 8; Stop-Process -Id $p.Id -Force
   # (Get-Item out.txt).Length      # 必须 0
   # (Get-Content err.txt).Count    # 约 6 行

   看到什么算通过（本章实测原文）：out.txt 0 字节 0 行，err.txt 6 行。这两条同时成立，才说明「协议电线」是干净的、人与机器各走各的通道。若 out.txt 非空，把它打印出来看看是什么——90% 是 Boot 日志，说明 ②′ 的 logback-spring.xml 没生效（文件名写成了 logback.xml？没放在 src/main/resources/？忘了重新 mvn package？）。

3. 用官方 Inspector（网页调试工具）连上它，确认工具能被发现并调用：

   # 在 mcp-order-server 工程目录下执行
   npx @modelcontextprotocol/inspector java -jar target/mcp-order-server-1.0.0.jar

   看到什么算通过：终端提示打开了网页（通常 http://localhost:6274），在页面里能看到 order-mcp-server 声明的两个工具 queryOrderStatus / listRecentOrders，填参数 2024001 调用能返回 未发货。这代表 Server 本身完全正常。

   注：这里 npx 是你在终端里手工敲的，Windows 下完全正常（终端会经过 shell 解析 npx.cmd）。但 8.5 节要把它写进 yml 让 Java 去拉起时，不能用 npx——除了拉不起来，它 96 秒的启动耗时也过不了 20 秒初始化窗口，详见 8.5 的差异一。

8.5写一个 MCP Client（连上 Server）

客户端跑在主应用 springai-lab 里（它既是 Host 也是 Client）。下面逐步加依赖、写配置、写调试服务。

① 主应用加依赖

1. 打开主应用 D:/springai-lab 的 pom.xml。
2. 在 <dependencies> 里粘贴下面这段（starter 坐标以官方为准，不要编造版本，交给 spring-ai-bom 管理）：

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

② 声明要连接的 Server 列表（2.0 推荐 yml 写法）

1. 打开主应用的 src/main/resources/application.yml，在 spring.ai.mcp.client 下粘贴下面的 stdio 连接配置。

先给你看一份备选的外部 JSON 写法（了解即可，本章以 yml 为准）：

{
  "mcpServers": {
    // ① 我们自己的订单 MCP Server（stdio：本地启动一个 Java 进程）
    "order-server": {
      "command": "java",
      "args": [
        "-jar",
        "D:/springai-lab/mcp-order-server/target/mcp-order-server-1.0.0.jar"
      ]
    },

    // ② 官方文件系统 Server（Node 实现，演示跨语言复用）
    "filesystem": {
      "command": "npx",      // ★ 别这么写：npx 当子进程启动器会拉不起 / 超时，改用 node 直跑（见 8.5 差异一）
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "D:/springai-lab/data"          // ★ 授予访问的目录白名单
      ]
    },

    // ③ 远程 Streamable HTTP Server（生产形态）
    "remote-weather": {
      "url": "http://localhost:8081/mcp",
      "type": "STREAMABLE",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

2.0 推荐写法：直接在 yml 里声明每个 stdio 连接，不再需要外部 JSON 文件，粘贴到主应用 application.yml。

# 建一个固定的「MCP Servers 安装区」，只做一次
mkdir D:/springai-lab/mcp-servers
cd D:/springai-lab/mcp-servers
npm init -y
npm install @modelcontextprotocol/server-filesystem

# 装完确认入口文件存在（路径就是下面 yml 里要填的那个）
dir node_modules\@modelcontextprotocol\server-filesystem\dist\index.js

# ★ 2.0 推荐写法：直接在 yml 里声明每个 stdio 连接，不再需要外部 JSON 文件
spring:
  ai:
    mcp:
      client:
        enabled: true              # 默认即 true（写出来是给人看的）
        name: springai-lab
        version: 1.0.0
        # 默认即 true：启动时把所有 Server 一次性连上
        # 只有显式写 false 才会变成「首次使用时才连」的惰性模式
        initialized: true
        # 默认即 true：把 MCP 工具包装成 ToolCallback
        # ★ 注意「包装」≠「交给模型」，后者必须手写，见 8.6 节
        toolcallback:
          enabled: true
        # ★ 单次工具调用超时。注意它在 client 层，不在 stdio 层！
        #   写进 stdio: 下面不会被识别（Spring 对未知键默认静默忽略）
        request-timeout: 60s
        stdio:
          connections:
            # ---- 我们自己的订单 MCP Server ----
            order-server:
              command: java
              args:
                - -jar
                - D:/springai-lab/mcp-order-server/target/mcp-order-server-1.0.0.jar
            # ---- 官方文件系统 Server（Node 实现） ----
            # ★★ 不要写 npx！用 node 直接跑本地装好的入口文件（原因见下方 warn）
            #    路径里的 mcp-servers 就是上面 npm install 的那个目录
            filesystem:
              command: node
              args:
                - D:/springai-lab/mcp-servers/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js
                - D:/springai-lab/data          # ★ 授权目录白名单

③ 用代码直接操作 MCP 客户端（了解机制）

1. 在主应用包 com.example.springai.ch08 上右键 → New → Java Class，名称填 McpInspectService。
2. 粘贴下面内容。它注入 List<McpSyncClient> 拿到全部连接，提供「列出工具」和「手工调工具」两个方法——这是 MCP 调试的黄金顺序。

容器里每个已配置的 Server 都会有一个 McpSyncClient bean。注入 List<McpSyncClient> 就能拿到全部连接，先手工列工具、再手工调工具——这是 MCP 调试的黄金顺序。

@Service
public class McpInspectService {

    private static final Logger log = LoggerFactory.getLogger(McpInspectService.class);

    /**
     * 容器里每个已配置的 Server 都会有一个 McpSyncClient bean。
     * 用 List 注入可以拿到全部。
     */
    private final List<McpSyncClient> clients;

    public McpInspectService(List<McpSyncClient> clients) {
        this.clients = clients;
    }

    /** 连接数：yml 里配了几个 Server 就该有几个；0 说明一个都没建起来 */
    public int clientCount() {
        return clients.size();
    }

    /** 列出所有 Server 及其工具，返回结构化结果便于断言 */
    public List<Map<String, Object>> listAllTools() {
        List<Map<String, Object>> servers = new ArrayList<>();
        for (McpSyncClient client : clients) {
            // 服务端自报的名字/版本（不是你在 yml 里起的连接别名！）
            McpSchema.Implementation info = client.getServerInfo();
            List<McpSchema.Tool> tools = client.listTools().tools();

            log.info("=== MCP Server: {} v{} === 工具数={}",
                    info.name(), info.version(), tools.size());

            List<Map<String, Object>> toolList = new ArrayList<>();
            for (McpSchema.Tool t : tools) {
                log.info("  工具: {}  描述: {}", t.name(), t.description());
                toolList.add(Map.of("name", t.name(),
                        "description", String.valueOf(t.description())));
            }

            Map<String, Object> one = new LinkedHashMap<>();
            one.put("server", info.name());
            one.put("version", info.version());
            one.put("initialized", client.isInitialized());   // 握手完成了吗
            one.put("tools", toolList);
            servers.add(one);
        }
        return servers;
    }

    /** 手工调用一个工具（不经过模型）——用于验证 Server 端逻辑是否正确 */
    public String callToolManually(String toolName, Map<String, Object> args) {
        for (McpSyncClient client : clients) {
            boolean has = client.listTools().tools().stream()
                    .anyMatch(t -> t.name().equals(toolName));
            if (has) {
                McpSchema.CallToolResult result =
                        client.callTool(new McpSchema.CallToolRequest(toolName, args));
                log.info("[manual-call] {}({}) -> isError={}", toolName, args, result.isError());
                return result.content().toString();
            }
        }
        throw new IllegalArgumentException("所有已连接的 Server 都没有工具：" + toolName);
    }
}

运行验证 ②：主应用启动，确认连上 Server

1. 确认 mcp-order-server 已打包（target/*.jar 存在），且 Node 已安装、filesystem 包已 npm install 到本地目录（8.5 ② 开头那一步）。然后启动主应用：

   # 在主应用目录下
   cd D:/springai-lab
   mvn spring-boot:run

   看到什么算通过（★ 注意：别去搜「Connected to MCP server」——那行字符串实测出现 0 次）：旧教程（含本章早期版本）让你盯 Connected to MCP server 'xxx'，而 2.0.1 的日志里根本没有这句话。照着搜会误判成「没连上」，白折腾。真正的判据是下面四条同时成立：

   # ① 子进程被拉起（每个连接一行，这里应该出现 2 次）
   ... i.m.c.transport.StdioClientTransport : MCP server started
   
   # ② Server 自己的日志被转发到 Host（证明 jar 真的跑起来了，不是假连上）
   ... i.m.c.transport.StdioClientTransport : STDERR Message received: ... Starting McpOrderServerApplication v1.0.0 using Java 17.0.12 ...
   ... i.m.c.transport.StdioClientTransport : STDERR Message received: ... Started McpOrderServerApplication in 2.435 seconds ...
   ... i.m.c.transport.StdioClientTransport : STDERR Message received: Secure MCP Filesystem Server running on stdio
   
   # ③ 协议握手成功：版本 + 对端服务名（★ 这条信息量最大）
   ... i.m.client.LifecycleInitializer : Server response with Protocol: 2025-11-25,
       Capabilities: ... Info: Implementation[name=order-mcp-server, title=null, version=1.0.0, ...]
   
   # ④ 工具真的被取出来了（8.6 节那行自打的日志）
   ... c.e.springai.ch08.McpChatClientConfig : 已从 MCP Server 加载 16 个工具

   其中 ② 那一堆 STDERR Message received: ... 正是 8.4 节 ②′ 把日志改道 stderr 带来的附加收益：协议走 stdout 不互相干扰，而人的日志通过 stderr 被 Host 转发进主应用日志——跨进程调试第一次变得可读。

2. 另开一个终端，调一个运维接口把工具清单打印到日志（接口实现见 8.7 节，这里先验证连接本身）：

   # 触发工具清单打印（若此接口尚未实现，可暂时在 main 里调用 listAllTools()）
   curl http://localhost:8080/api/v1/mcp-assistant/tools

   看到什么算通过（本章实测原文，工具数要精确对上）：

   ... c.e.springai.ch08.McpInspectService : === MCP Server: order-mcp-server v1.0.0 === 工具数=2
   ... c.e.springai.ch08.McpInspectService :   工具: listRecentOrders  描述: 列出某个客户最近 5 笔订单的订单号与状态
   ... c.e.springai.ch08.McpInspectService :   工具: queryOrderStatus  描述: 查询指定订单号的当前状态与预计发货时间。
   ... c.e.springai.ch08.McpInspectService : === MCP Server: secure-filesystem-server v1.0.0 === 工具数=14

   ★ 两处易错点：① 第二个 Server 的名字是 secure-filesystem-server，不是 filesystem（filesystem 只是你在 yml 里给这个连接起的别名）；② filesystem Server 当前版本带 14 个工具（read_file 已标 DEPRECATED，还有 read_text_file / list_directory_with_sizes / search_files 等），总数是 16，不是旧教程说的 6～8 个。工具数会随 npm 包升级而变，别把数字写死在作业里——要写就写「2 + N」。

关于 initialized：默认就是 true，别被旧文档误导。网上（包括本章早期版本）有「initialized: false 是惰性连接，要设 true 才不会首次调用卡顿」的说法——方向对，前提错：实测元数据默认值就是 true，所以你从没遇到过「首次请求卡几秒」，正是因为默认已经是一次性建连。真正的坑在反方向：如果有人为了「加快启动」把它改成 false，Server 路径写错时要等到第一次调用才暴露，排查难度立刻上一个台阶。结论：保持默认（true），并且不需要在 yml 里写这一行；写出来只是为了让人读懂。

8.6把 MCP 工具交给模型：和第 7 章无缝衔接

工具发现流程：从 Server 到模型的四步

spring.ai.mcp.client.toolcallback.enabled（默认就是 true，不用手写）打开时， Spring AI 会把所有 MCP Server 提供的工具自动包装成 ToolCallback， 然后你就能像使用本地 @Tool 一样把它们交给模型。

1. 在主应用包 com.example.springai.ch08 上右键 → New → Java Class，名称填 McpChatClientConfig。
2. 粘贴下面内容。注意注入的是 SyncMcpToolCallbackProvider（异步客户端则注入 AsyncMcpToolCallbackProvider），并显式调用 .defaultToolCallbacks(mcpTools)。

@Configuration
public class McpChatClientConfig {

    /**
     * ★ 关键 bean：Spring AI 会把所有 MCP Server 的工具汇总成这个 Provider，
     *   它是"MCP 世界"和"Spring AI 工具世界"之间的桥梁。
     *
     * ★★ 2.0 最容易踩的坑：MCP 工具【不会】自动注册到 ChatClient 上。
     *    框架刻意这么设计——避免一个应用无意间把上百个外部工具全塞给模型。
     *    你必须显式地把它传给 .defaultTools(...) 或 .tools(...)，就像下面这样。
     */
    @Bean("mcpAssistantClient")
    public ChatClient mcpAssistantClient(
            ChatModel chatModel,
            // ★ 2.0 的具体类型是 SyncMcpToolCallbackProvider
            //   （异步客户端则注入 AsyncMcpToolCallbackProvider）
            SyncMcpToolCallbackProvider mcpToolCallbackProvider) {   // 自动装配

        // 取出全部 MCP 工具（本质是 ToolCallback[]，与第 7 章完全同类型）
        ToolCallback[] mcpTools = mcpToolCallbackProvider.getToolCallbacks();

        // 打印出来确认连上了几个工具——启动日志里能看到
        org.slf4j.LoggerFactory.getLogger(McpChatClientConfig.class)
                .info("已从 MCP Server 加载 {} 个工具", mcpTools.length);

        return ChatClient.builder(chatModel)
                .defaultSystem("""
                        你是"智汇"智能助手，可以访问文件系统和订单系统。

                        规则：
                        1. 涉及真实数据（文件、订单）时必须调用工具。
                        2. 需要读取或写入文件时，先确认路径在允许范围内。
                        3. 工具报错时，向用户说明原因并给出建议。
                        """)
                .defaultToolCallbacks(mcpTools)     // ★ 显式注册 MCP 工具（不写这行模型就用不了）
                .build();
    }
}

运行验证 ③：启动日志确认工具已加载

1. 重启主应用（若已在运行先停掉），观察启动日志：

   # 主应用目录
   cd D:/springai-lab
   mvn spring-boot:run

   看到什么算通过：日志中出现 已从 MCP Server 加载 N 个工具，其中 N = 订单 Server 的 2 个 + filesystem Server 的 14 个 = 16（实测值；filesystem 的工具数随 npm 包版本变化，别把 16 当常量背下来）。这条日志来自上面 McpChatClientConfig 里的 info(...)，它证明「MCP 工具已被取出并准备好了」。

   ... c.e.springai.ch08.McpChatClientConfig : 已从 MCP Server 加载 16 个工具
   ... c.e.springai.ch08.McpChatClientConfig :   - listRecentOrders  (列出某个客户最近 5 笔订单的订单号与状态)
   ... c.e.springai.ch08.McpChatClientConfig :   - queryOrderStatus  (查询指定订单号的当前状态与预计发货时间。...)
   ... c.e.springai.ch08.McpChatClientConfig :   - read_file  (Read the complete contents of a file as text. DEPRECATED: ...)
   ... <!-- 后面还有 13 行，一行一个工具 -->
   
   # ★ 建议像上面这样顺手打印工具名：出问题时一眼能看出「少了哪个 Server 的工具」
   #   只打数字的话，14 和 16 你分不清是谁挂了一个

本地 @Tool 与 MCP 工具：注册方式对照

记住：本地 @Tool 和 MCP 工具最终都变成 ToolCallback，所以你完全可以把两者混着交给模型——本地一个、远程一个，模型分不清。唯一区别就是「MCP 那个需要你多写一行显式注册」。

8.7完整示例：MCP 文件助手

做一个小助手：既能用我们自己写的订单 MCP Server，也能用官方文件系统 MCP Server（跨语言复用，Server 是 Node 写的）。重点是验证「MCP 工具要显式注册、且权限边界在 Server 端」。

端到端数据流：一次问答怎么走到 Server

把 8.7 的完整链路在脑子里过一遍，出问题才知道断在哪一层：

动手 checkpoint：把 order-server 的 jar 路径（D:/springai-lab/mcp-order-server/target/...）和 filesystem 的白名单目录（D:/springai-lab/data）改成你机器上的真实路径，否则 8.7 第 ②③④ 步会连不上或越权判定失效。路径错了不是 MCP 的问题，是配置问题。

① 先构建并验证 Server（回顾）

8.4 节已经做过这一步，这里再给一次完整命令，确保 jar 就绪：

# 打包 MCP Server
cd D:/springai-lab/mcp-order-server
mvn clean package -DskipTests

# 预期输出：BUILD SUCCESS，并在 target/ 下生成 mcp-order-server-1.0.0.jar

# ★ 先用 8.4 运行验证 ① 的两个动作确认它「干净且能用」：
#   1) 分流运行，stdout 必须 0 字节（否则主应用一定起不来）
#   2) 用 Inspector 连一次，确认两个工具能列出、能调用
# 这两步过了再往下，能省掉后面一半的排查时间。

② 业务服务（含安全边界）

1. 在包 com.example.springai.ch08 上右键 → New → Java Class，名称填 FileAssistantService。
2. 粘贴下面内容。它注入名为 mcpAssistantClient 的 ChatClient（即 8.6 节配的那个），把用户问题交给模型。

@Slf4j
@Service
public class FileAssistantService {

    private final ChatClient mcpAssistantClient;
    private final ChatModel chatModel;          // 给下面的反例方法用

    public FileAssistantService(
            @Qualifier("mcpAssistantClient") ChatClient client,
            ChatModel chatModel) {
        this.mcpAssistantClient = client;
        this.chatModel = chatModel;
    }

    public String ask(String question) {
        long start = System.currentTimeMillis();
        String answer = mcpAssistantClient.prompt()
                .user(question)
                .call()
                .content();
        log.info("[mcp-ask] {}ms question={} answerLen={}",
                System.currentTimeMillis() - start, question,
                answer == null ? 0 : answer.length());
        return answer;
    }

    /**
     * ★ 反例实验专用：同一个模型、但【不挂任何工具】。
     *   拿来和 ask() 的结果对比，验证 8.6 的铁律（见 8.7 ④ 与「反例不稳定」）。
     */
    public String askWithoutTools(String question) {
        return ChatClient.builder(chatModel)
                .defaultSystem("你是智能助手，可以查询订单状态与文件系统。")  // ← 故意的，见下方 warn
                .build()
                .prompt()
                .user(question)
                .call()
                .content();
    }
}

③ 接口（含一个运维接口，用于排查工具注册情况）

1. 在包 com.example.springai.ch08 上右键 → New → Java Class，名称填 McpAssistantController。
2. 粘贴下面内容。四个端点各有分工：/tools 看「连了几个、有多少工具」、/call 绕过模型直接调工具、/ask 走模型、/ask-no-tools 是反例对照组。

@RestController
@RequestMapping("/api/v1/mcp-assistant")
public class McpAssistantController {

    private final FileAssistantService assistant;
    private final McpInspectService inspect;

    public McpAssistantController(FileAssistantService assistant,
                                  McpInspectService inspect) {
        this.assistant = assistant;
        this.inspect = inspect;
    }

    /** 端点总表：排错时先看这一张，别急着怀疑工具描述 */
    @GetMapping("/endpoints")
    public Map<String, Object> endpoints() {
        Map<String, Object> m = new LinkedHashMap<>();
        m.put("GET /tools", "已连接 Server 及其工具（结构化，可断言）");
        m.put("GET /call?tool=&arg=", "手工调工具，不经过模型");
        m.put("POST /ask", "走模型（ChatClient 已挂 MCP 工具）");
        m.put("POST /ask-no-tools", "反例：裸 ChatClient，验证「不显式注册就用不了」");
        return m;
    }

    /**
     * ★ 排查「工具没注册上」的最快手段：直接返回结构化结果，不靠读日志。
     *   clientCount 应为 yml 里配的 Server 数；toolCount 应为各 Server 工具数之和。
     *   生产环境记得加管理员权限。
     */
    @GetMapping("/tools")
    public Map<String, Object> tools() {
        List<Map<String, Object>> servers = inspect.listAllTools();
        int total = servers.stream()
                .mapToInt(s -> ((List<?>) s.get("tools")).size())
                .sum();
        Map<String, Object> m = new LinkedHashMap<>();
        m.put("clientCount", inspect.clientCount());
        m.put("toolCount", total);
        m.put("servers", servers);
        return m;
    }

    /** 手工调用：把「连接问题」与「模型不选工具」彻底分开 */
    @GetMapping("/call")
    public Map<String, Object> call(@RequestParam String tool,
                                    @RequestParam(defaultValue = "2024001") String arg) {
        Map<String, Object> args = tool.startsWith("queryOrderStatus")
                ? Map.of("orderNo", arg)
                : Map.of("customerName", arg);
        return Map.of("tool", tool, "args", args,
                "result", inspect.callToolManually(tool, args));
    }

    @PostMapping("/ask")
    public Map<String, String> ask(@RequestBody Map<String, String> body) {
        return Map.of("answer", assistant.ask(body.get("question")));
    }

    @PostMapping("/ask-no-tools")
    public Map<String, String> askNoTools(@RequestBody Map<String, String> body) {
        return Map.of("answer", assistant.askWithoutTools(body.get("question")));
    }
}

④ 端到端验证（四个用例）

下面四个用例覆盖「注册成功 / 远程调用 / 跨语言 / 越权拦截」。第 ④ 步是本章最有价值的验证。

1. 先确认工具真的注册上了（调 8.5 已配好的 /tools）：

   curl http://localhost:8080/api/v1/mcp-assistant/tools

   看到什么算通过（确定型判据）：JSON 里 "clientCount": 2、"toolCount": 16，且 servers 数组里两个元素的 server 分别是 order-mcp-server 与 secure-filesystem-server、initialized 都是 true。

   {
     "clientCount": 2,
     "toolCount": 16,
     "servers": [
       { "server": "order-mcp-server", "version": "1.0.0", "initialized": true,
         "tools": [ { "name": "listRecentOrders", ... }, { "name": "queryOrderStatus", ... } ] },
       { "server": "secure-filesystem-server", "version": "1.0.0", "initialized": true,
         "tools": [ { "name": "read_file", ... }, /* …共 14 个 */ ] }
     ]
   }

   三处常见误判：① 把 secure-filesystem-server 当成「配错了名字」——它是 Server 自报的名字，filesystem 只是你在 yml 里起连接别名；② 把 toolCount=16 背成常量——它随 npm 包版本变化，断言请用「2 + N」；③ 看到 initialized=false 就以为要改配置——那说明握手没完成，去看 8.5 的启动日志。

2. 用远程 MCP 工具查订单（模型不知道这是远程的）：

   curl -X POST http://localhost:8080/api/v1/mcp-assistant/ask \
     -H "Content-Type: application/json" \
     -d '{"question":"订单 2024001 发货了吗？"}'

   看到什么算通过（实测原文）：答案包含「未发货」与「2026-10-28」，说明模型调用了 queryOrderStatus 并把结果组织成了自然语言。同时主应用日志里应出现两个进程各自的痕迹（缺一个都说明没真正跨进程）：

   # Host 侧：模型确实发了这一次请求
   ... c.e.springai.ch08.FileAssistantService : [mcp-ask] 2007ms question=订单 2024001 发货了吗？ answerLen=58
   
   # Server 侧：工具在【另一个进程】里被执行（这是「真的跨进程」的确凿证据）
   ... i.m.c.transport.StdioClientTransport : STDERR Message received: ... [OrderMcpTools] queryOrderStatus 被调用 orderNo=2024001

   ★ 别只看 JSON 答案。模型完全可能在没调工具的情况下编一个「已发货」出来（8.7 末尾的反例会演示），所以「答案对不对」不是判据，「Server 侧有没有那行日志」才是判据。

3. 用文件系统 MCP 工具（跨语言：Server 是 Node 写的）：

   curl -X POST http://localhost:8080/api/v1/mcp-assistant/ask \
     -H "Content-Type: application/json" \
     -d '{"question":"列出 D:/springai-lab/data 目录下的所有文件"}'

   看到什么算通过：答案里能列出你白名单目录下真实存在的文件名（本章环境是 readme.txt 与 orders.csv，换成你自己建的目录就以实际为准）——证明 Java 主应用成功驱动了一个 Node 实现的 Server。这一条的价值是语言无关性：整个链路里 Java 只认协议，不认实现语言。

4. 越权测试：让文件助手读白名单外的目录：

   curl -X POST http://localhost:8080/api/v1/mcp-assistant/ask \
     -H "Content-Type: application/json" \
     -d '{"question":"帮我读一下 C:/Windows/System32/drivers/etc/hosts 文件"}'

   看到什么算通过（实测原文，注意错误是 Server 侧返回的）：MCP 工具调用抛错，主应用日志出现：

   ERROR ... o.s.ai.mcp.SyncMcpToolCallback : Error calling tool: [TextContent[...,
       text=Access denied - path outside allowed directories:
       C:\Windows\System32\drivers\etc\hosts not in D:\springai-lab\data, ...]]

   而给用户的回答是一句礼貌的「无权访问该目录」——模型没有能力绕过它，因为拒绝发生在 Node 进程里，不在模型的判断范围内。这验证了 MCP 的权限边界在 Server 端。

   ★ 排错提示：如果你连 Access denied 都没看到、模型直接说「我读不到」，那可能是路径根本不存在（模型自己判断后就放弃了，压根没调工具）。 判断方法：看日志里有没有 Error calling tool:——有，才是「被 Server 拒绝」；没有，就是「模型没调」，回 8.6 查注册。

# ① 先看工具有没有注册上（结构化 JSON，直接看数字）
curl http://localhost:8080/api/v1/mcp-assistant/tools
# 期望：clientCount=2, toolCount=16, 两个 server 名分别为
#       order-mcp-server / secure-filesystem-server

# ② 绕过模型，手工调一次（把「连接问题」和「模型不选工具」分开）
curl "http://localhost:8080/api/v1/mcp-assistant/call?tool=queryOrderStatus&arg=2024001"
# 期望：result 里有 未发货 / 2026-10-28（这一步过了，说明连接与 Server 都没问题）

# ③ 走模型查订单（模型不知道这是远程的）
curl -X POST http://localhost:8080/api/v1/mcp-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"订单 2024001 发货了吗？"}'
# 期望：答案含「未发货 + 2026-10-28」，且日志出现 [OrderMcpTools] queryOrderStatus 被调用

# ④ 用文件系统 MCP 工具（跨语言：Server 是 Node 写的）
curl -X POST http://localhost:8080/api/v1/mcp-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"列出 D:/springai-lab/data 目录下的所有文件"}'
# 期望：列出 readme.txt / orders.csv 这类真实文件名

# ⑤ 越权测试：读白名单外的目录
curl -X POST http://localhost:8080/api/v1/mcp-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"帮我读一下 C:/Windows/System32/drivers/etc/hosts 文件"}'
# 期望：Server 返回 Access denied - path outside allowed directories
# ★ 这验证了 MCP 的价值：权限约束在 Server 端，而不是靠模型自觉

# ⑥ 反例对照组：同一个问题，问一个【没挂工具】的裸 client
curl -X POST http://localhost:8080/api/v1/mcp-assistant/ask-no-tools \
  -H "Content-Type: application/json" \
  -d '{"question":"订单 2024001 发货了吗？"}'
# 期望：说没有查询能力 / 或者【编造一个答案】 —— 两种都可能出现，见下方警告

8.8调试与常见坑

用官方 Inspector 调试 Server

MCP Inspector 是一个网页版调试工具，能列出工具、手工填参数调用、看原始报文。它在定位「Server 端问题」时比看日志高效得多。

1. 在 mcp-order-server 工程目录下执行（需联网首次拉取）：

   # MCP Inspector 是一个网页版调试工具，能列出工具、手工填参数调用、看原始报文
   npx @modelcontextprotocol/inspector java -jar target/mcp-order-server-1.0.0.jar
   
   # 它会启动一个本地 Web 界面（通常是 http://localhost:6274）
   # 在里面你可以：
   #   1. 看到 Server 声明的全部工具与参数 schema
   #   2. 手工填参数调用，验证 Server 端逻辑
   #   3. 查看完整的 JSON-RPC 请求/响应报文

   看到什么算通过：浏览器打开 http://localhost:6274，左侧列出 queryOrderStatus / listRecentOrders，填 2024001 点调用，右侧返回订单状态 JSON。这证明 Server 端逻辑正确，之后再从客户端连它。

常见坑排错表

选做：把 stdio Server 改成 Streamable HTTP 独立部署

课程建议先 stdio 跑通，再试远程。把订单 Server 从「本地子进程」改成「独立 Web 服务」只需三步：

1. 把 pom.xml 里的 spring-ai-starter-mcp-server 换成 spring-ai-starter-mcp-server-webmvc（并保留 spring-boot-starter-webmvc）。
2. 改 application.yml：删掉 web-application-type: none 和 stdio: true，改为 spring.ai.mcp.server.protocol=STREAMABLE（或 STATELESS），并设 server.port（如 8081）。
3. 重新 mvn clean package，用 java -jar 直接启动（不再是子进程，而是一个常驻 Web 服务）。
4. 主应用那边：把 stdio.connections.order-server 整段删掉，改用远程声明（url: http://localhost:8081/mcp + type: STREAMABLE），其余代码一行不用动。

看到什么算通过：启动订单 Server 能看到 Tomcat 监听 8081；主应用 /tools 里 clientCount 仍是 2、order-mcp-server 的 initialized=true；8.7 的 curl 验证全部照常通过。这证明「换传输方式对业务代码零侵入」——这正是协议标准化的好处。

8.9自测题

8.10实操作业与本章验收

• 能画出 Host / Client / Server 的关系图，并说出 stdio / SSE / Streamable HTTP 三种传输方式的区别与适用场景。
• 能独立写一个 stdio 模式的 MCP Server（用 @McpTool/@McpToolParam，包 org.springframework.ai.mcp.annotation），并用 Inspector 调通。
• 能在主应用里配置 MCP Client，连上两个以上 Server（含一个 Node 实现的），并把工具显式注册到 ChatClient（SyncMcpToolCallbackProvider → .defaultToolCallbacks(...)）。
• 能解释「为什么 MCP 工具不会自动注册到 ChatClient、以及为什么 MCP 的权限边界比写在提示词里更可靠」。

8.11动手清单与自查表

① 你要建的文件（以及「建对了」的可观察判据）

② 分步验收（每一步都有「等于什么」的判据）

③ 卡住了去哪查