CH 08MCP：模型上下文协议

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

先看没有 MCP 时的困境：

MCP 与第 7 章 @Tool 的关系

8.2架构与三大原语

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

8.3三种传输方式：怎么连

8.4写一个 MCP Server

① 依赖（建议独立工程）

MCP Server 通常做成独立应用，不要和主应用混在一起。

<!-- 新建工程 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>

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

# 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

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

// OrderMcpTools.java —— 与第 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();
    }
}

8.5写一个 MCP Client（连上 Server）

① 主应用加依赖

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

② 声明要连接的 Server 列表

创建 src/main/resources/mcp-servers.json：

{
  "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 文件
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 客户端（了解机制）

@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);
    }
}

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

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

@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();
    }
}

8.7完整示例：MCP 文件助手

做一个小助手：既能用我们自己写的订单 MCP Server，也能用官方文件系统 MCP Server（跨语言复用）。

① 先构建并验证 Server

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

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

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

@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();
    }
}

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

@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", "工具清单已打印到日志");
    }
}

④ 验证

# ① 先看工具有没有注册上
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 是一个网页版调试工具，能列出工具、手工填参数调用、看原始报文
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 请求/响应报文

常见坑排错表

8.9自测题