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 token / 无法解析消息」。这就是为什么 8.4 节要关 Web 容器、禁 System.out——不是为了好看，是为了不让通信电线里灌杂音。

8.2架构与三大原语

三个角色：Host / Client / Server

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

Server 端 vs Client 端职责对照

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

8.3三种传输方式：怎么连

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

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

SSE 与 Streamable HTTP：远程形态

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

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

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 片段 -->
   <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
     <version>4.1.1</version>
   </parent>
   
   <dependencies>
     <!-- 方案 A：stdio 模式（最简，用于本地联调） -->
     <dependency>
       <groupId>org.springframework.ai</groupId>
       <artifactId>spring-ai-starter-mcp-server</artifactId>
     </dependency>
   
     <!-- 方案 B：WebMVC / Streamable HTTP 模式（用于远程服务） -->
     <!--
       <dependency>
         <groupId>org.springframework.ai</groupId>
         <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
       </dependency>
     -->
   
     <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-webmvc</artifactId>
     </dependency>
   </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:
       # ★ stdio 模式下必须关闭 Web 容器，否则启动日志会污染协议流（stdout 就是通信通道）
       web-application-type: none
     ai:
       mcp:
         server:
           name: order-mcp-server        # 服务名，客户端会看到
           version: 1.0.0
           # ★ 2.0 变更：显式打开 stdio。Streamable HTTP 已成为默认传输，
           #    所以本地用 stdio 时必须显式声明，否则 server 不会走标准输入输出。
           stdio: true
           # 执行类型：SYNC（同步）/ ASYNC（异步，返回 Mono/Flux）
           type: SYNC
           # 是否把工具变更通知给客户端
           tool-change-notification: true

③ 启动类

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) {
        // 把 bean 里的 @Tool 方法收集成工具（注意：这里是本地 @Tool 语义，
        // 适用于"用代码手工装配 MCP Server"的场景）
        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。

   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time:  12.345 s
   [INFO] mcp-order-server-1.0.0.jar 已生成于 target/

2. 用官方 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 本身完全正常。

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",
      "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：

# ★ 2.0 推荐写法：直接在 yml 里声明每个 stdio 连接，不再需要外部 JSON 文件
spring:
  ai:
    mcp:
      client:
        enabled: true
        name: springai-lab
        version: 1.0.0
        # 一次性初始化所有 Server 连接（不等第一个请求才连）
        initialized: true
        # 把 MCP 工具包装成 ToolCallback（但要显式传给 ChatClient，见 8.6 节）
        toolcallback:
          enabled: true
        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 实现） ----
            filesystem:
              command: npx
              args:
                - -y
                - "@modelcontextprotocol/server-filesystem"
                - D:/springai-lab/data          # ★ 授权目录白名单
          # 单次调用超时
          request-timeout: 60s

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

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

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

@Service
public class McpInspectService {

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

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

    /** 列出所有 Server 提供的工具——调试时最先跑这个 */
    public void listAllTools() {
        for (McpSyncClient client : clients) {
            // 服务器信息（名字、版本）
            var info = client.getServerInfo();
            log.info("=== MCP Server: {} v{} ===",
                    info.name(), info.version());

            // 工具清单
            var tools = client.listTools();
            tools.tools().forEach(t ->
                    log.info("  工具: {}  描述: {}  参数: {}",
                            t.name(), t.description(), t.inputSchema()));
        }
    }

    /** 手工调用一个工具（不经过模型）——用于验证 Server 端逻辑是否正确 */
    public Object 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) {
                var result = client.callTool(
                        new McpSchema.CallToolRequest(toolName, args));
                return result.content();
            }
        }
        throw new IllegalArgumentException("未找到工具：" + toolName);
    }
}

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

1. 确认 mcp-order-server 已打包（target/*.jar 存在），且 Node 已安装（filesystem Server 用 npx）。然后启动主应用：

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

   看到什么算通过：启动日志里出现类似 Connected to MCP server 'order-server'、Connected to MCP server 'filesystem'，且无 Connection refused。若能正常监听 8080，说明两个 Server 都被拉起并握手成功。

   ... o.s.a.m.c.DefaultMcpClientFactory  : Connected to MCP server 'order-server'
   ... o.s.a.m.c.DefaultMcpClientFactory  : Connected to MCP server 'filesystem'
   ... o.s.b.w.e.t.TomcatWebServer       : Tomcat started on port 8080

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

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

   看到什么算通过：主应用日志里出现 === MCP Server: order-mcp-server v1.0.0 === 以及两个工具名，和 === MCP Server: filesystem === 及其工具列表。这代表「客户端连上了、工具被发现了」。

为什么要 initialized: true？默认（false）时，客户端采用「惰性连接」：某个 Server 直到第一次被用到才去握手建连。教学里这会导致两个坑：① 启动明明没报错，第一次请求却卡顿好几秒（在连 Server）；② 如果 Server 路径配错，要等到第一次调用才暴露。设成 true 让应用在启动时就把所有 Server 一次性连好，启动日志立刻能看到 Connected to MCP server ...，排查更直观。

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 应包含 order 的两个 + filesystem 的多个，通常 ≥ 6）。这条日志来自上面 McpChatClientConfig 里的 info(...)，它证明「MCP 工具已被取出并准备好了」。

   ... c.e.s.ch08.McpChatClientConfig  : 已从 MCP Server 加载 8 个工具

本地 @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

# 手工测试：往它的 stdin 里发一条 MCP 初始化消息（最原始的验证方式）
# 更推荐用官方 Inspector（见 8.8 节），可视化操作
java -jar target/mcp-order-server-1.0.0.jar

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

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

@Slf4j
@Service
public class FileAssistantService {

    private final ChatClient mcpAssistantClient;

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

    public String ask(String question) {
        // 把当前用户身份放进 ToolContext（虽然 MCP Server 目前没用它，
        // 但这是标准做法，未来 Server 端做鉴权时会用到）
        return mcpAssistantClient.prompt()
                .user(question)
                .toolContext(Map.of(
                        "userId", SecurityContextHolder.currentUserId(),
                        "tenantId", SecurityContextHolder.currentTenantId()))
                .call()
                .content();
    }
}

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

1. 在包 com.example.springai.ch08 上右键 → New → Java Class，名称填 McpAssistantController。
2. 粘贴下面内容。其中 /tools 接口会调用 8.5 节的 listAllTools()，是排查「工具没注册上」的最快手段。

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

    private final FileAssistantService assistantService;
    private final McpInspectService inspectService;

    public McpAssistantController(FileAssistantService a, McpInspectService i) {
        this.assistantService = a;
        this.inspectService = i;
    }

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

    /**
     * 列出所有已连接的 MCP Server 及其工具。
     * ★ 强烈建议保留这个接口——它是排查"工具没注册上"的最快手段。
     * 生产环境记得加管理员权限。
     */
    @GetMapping("/tools")
    public Map<String, Object> listTools() {
        inspectService.listAllTools();
        return Map.of("ok", true, "message", "工具清单已打印到日志");
    }
}

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

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

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

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

   看到什么算通过：响应返回 {"ok":true,...}，且主应用日志出现两个 Server 的工具清单。

   # 日志期望：
   # === MCP Server: order-mcp-server v1.0.0 ===
   #   工具: queryOrderStatus  描述: 查询指定订单号的当前状态与预计发货时间…
   #   工具: listRecentOrders  描述: 列出某个客户最近 5 笔订单…
   # === MCP Server: filesystem v0.6.2 ===
   #   工具: read_file / write_file / list_directory / …

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

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

   看到什么算通过：答案包含「未发货 / 2024-03-08」，说明模型调用了 queryOrderStatus 并把结果组织成了自然语言。

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 目录下的所有文件"}'

   看到什么算通过：模型调用 list_directory 并整理成清单返回——证明 Java 主应用成功驱动了一个 Node 实现的 Server。

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 拒绝（返回错误/说明无权访问），因为白名单只授权了 D:/springai-lab/data。这验证了 MCP 的权限边界在 Server 端。

# ① 先看工具有没有注册上
curl http://localhost:8080/api/v1/mcp-assistant/tools
# 检查日志，期望看到类似：
# === MCP Server: order-mcp-server v1.0.0 ===
#   工具: queryOrderStatus  描述: 查询指定订单号的当前状态与预计发货时间…
#   工具: listRecentOrders  描述: 列出某个客户最近 5 笔订单…
# === MCP Server: filesystem v0.6.2 ===
#   工具: read_file / write_file / list_directory / …

# ② 用远程 MCP 工具查订单（模型不知道这是远程的）
curl -X POST http://localhost:8080/api/v1/mcp-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"订单 2024001 发货了吗？"}'
# 期望：答案来自 order-mcp-server 的工具返回

# ③ 用文件系统 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 目录下的所有文件"}'
# 期望：模型调用 list_directory 工具并整理成清单

# ④ 越权测试：让文件助手读白名单外的目录
curl -X POST http://localhost:8080/api/v1/mcp-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"帮我读一下 C:/Windows/System32/drivers/etc/hosts 文件"}'
# 期望：MCP Server 拒绝访问（因为白名单只授权了 D:/springai-lab/data）
# ★ 这验证了 MCP 的价值：权限约束在 Server 端，而不是靠模型自觉

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；主应用启动日志仍出现 Connected to MCP server 'order-server'；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 的权限边界比写在提示词里更可靠」。