Kevin's blog
kevin
2025-10-29
目录

MCP 开发完整指南

# MCP 开发完整指南

# 🎯 技术栈选择概述

本指南提供两种 MCP (Model Context Protocol) 开发方式，适用于不同的应用场景：

开发方式 适用场景 优势 劣势
🚀 方案一：Spring AI MCP 生态 Spring AI 应用开发 官方抽象层、未来兼容、最佳实践 依赖Spring AI版本
⚡ 方案二：直接 MCP SDK 独立MCP应用、脱离Spring AI 直接控制、轻量级、版本独立 需要手动实现抽象层

# 📋 选择指导原则

  • ✅ 优先选择方案一：如果你正在开发基于 Spring AI 的应用
  • ✅ 选择方案二：如果你需要独立的 MCP 服务，不依赖 Spring AI 生态

# 🚀 方案一：基于 Spring AI MCP 生态（推荐）

核心原则: 基于 Spring AI MCP 生态系统进行开发，利用官方抽象层

# 📦 服务端依赖配置 (3个核心包)

<properties>
    <java.version>17</java.version>
    <spring-ai.version>1.1.0-SNAPSHOT</spring-ai.version>
</properties>

<dependencies>
    <!-- Spring Boot Web (必需) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Spring AI MCP 核心包 (包含MCP支持) -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-mcp</artifactId>
        <version>${spring-ai.version}</version>
    </dependency>
    
    <!-- Spring AI Model (基础接口) -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-model</artifactId>
        <version>${spring-ai.version}</version>
    </dependency>
    
    <!-- 注意：MCP SDK 通过 spring-ai-mcp 传递依赖自动获得 -->
</dependencies>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# 📦 客户端依赖配置 (4个核心包)

<properties>
    <java.version>17</java.version>
    <spring-ai.version>1.1.0-SNAPSHOT</spring-ai.version>
</properties>

<dependencies>
    <!-- Spring Boot Web (必需) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Spring Boot WebFlux (响应式支持) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
    
    <!-- Spring AI MCP 核心包 (包含ToolCallbackProvider) -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-mcp</artifactId>
        <version>${spring-ai.version}</version>
    </dependency>
    
    <!-- Spring AI Model (ToolCallback接口等) -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-model</artifactId>
        <version>${spring-ai.version}</version>
    </dependency>
    
    <!-- 注意：MCP SDK 通过 spring-ai-mcp 传递依赖自动获得 -->
</dependencies>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 🏗️ 方案一架构说明

# 依赖层次结构

应用代码
    ↓
Spring AI MCP (spring-ai-mcp)
    ↓  
Spring AI Model (spring-ai-model)
    ↓
MCP SDK (io.modelcontextprotocol.sdk:mcp) [传递依赖]
1
2
3
4
5
6
7

# 推荐用法

// 使用Spring AI提供的ToolCallbackProvider
SyncMcpToolCallbackProvider provider = new SyncMcpToolCallbackProvider(mcpClient);
List<ToolCallback> callbacks = Arrays.asList(provider.getToolCallbacks());
1
2
3

# ⚡ 方案二：直接基于 MCP SDK（独立开发）

核心原则: 直接使用 MCP SDK，不依赖 Spring AI 生态系统

# 📦 服务端依赖配置

<properties>
    <java.version>17</java.version>
    <mcp-sdk.version>0.10.0</mcp-sdk.version>
</properties>

<dependencies>
    <!-- Spring Boot 核心 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- MCP SDK 核心包 -->
    <dependency>
        <groupId>io.modelcontextprotocol.sdk</groupId>
        <artifactId>mcp</artifactId>
        <version>${mcp-sdk.version}</version>
    </dependency>
    
    <!-- MCP Spring WebMVC 集成 (SSE传输) -->
    <dependency>
        <groupId>io.modelcontextprotocol.sdk</groupId>
        <artifactId>mcp-spring-webmvc</artifactId>
        <version>${mcp-sdk.version}</version>
    </dependency>
    
    <!-- MCP Spring WebFlux 集成 (响应式SSE传输) -->
    <dependency>
        <groupId>io.modelcontextprotocol.sdk</groupId>
        <artifactId>mcp-spring-webflux</artifactId>
        <version>${mcp-sdk.version}</version>
    </dependency>
</dependencies>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# 📦 客户端依赖配置

<properties>
    <java.version>17</java.version>
    <mcp-sdk.version>0.10.0</mcp-sdk.version>
</properties>

<dependencies>
    <!-- Spring Boot 核心 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
    
    <!-- MCP SDK 核心包 (客户端实现) -->
    <dependency>
        <groupId>io.modelcontextprotocol.sdk</groupId>
        <artifactId>mcp</artifactId>
        <version>${mcp-sdk.version}</version>
    </dependency>
    
    <!-- MCP Spring WebFlux 客户端传输 -->
    <dependency>
        <groupId>io.modelcontextprotocol.sdk</groupId>
        <artifactId>mcp-spring-webflux</artifactId>
        <version>${mcp-sdk.version}</version>
    </dependency>
</dependencies>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 🏗️ 方案二架构说明

# 服务端架构

Spring Boot Application
    ↓
@Configuration + @Bean
    ↓
List<SyncToolSpecification>
    ↓
MCP SDK 自动扫描
    ↓
SSE Endpoint (/sse)
1
2
3
4
5
6
7
8
9

# 客户端架构

Spring Boot Application
    ↓
手动 McpSyncClient Bean
    ↓
自定义 ToolCallback 转换
    ↓
业务逻辑调用
1
2
3
4
5
6
7

# 实现示例

// 手动实现ToolCallback转换
public class CustomMcpToolCallback implements ToolCallback {
    private final McpSyncClient client;
    private final McpSchema.Tool tool;
    
    @Override
    public String call(String arguments) {
        // 手动实现调用逻辑
        Map<String, Object> args = parseArguments(arguments);
        McpSchema.CallToolRequest request = new McpSchema.CallToolRequest(tool.name(), args);
        McpSchema.CallToolResult result = client.callTool(request);
        return extractResult(result);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 📋 项目功能分析

# 🔧 MCP Server 功能清单

功能类别 具体功能 实现类 说明
数学工具 add, multiply, power MathToolsConfiguration 基础数学计算工具
文本工具 uppercase, analyze_text, reverse TextToolsConfiguration 文本处理工具
系统资源 system://info, time://current, app://status SystemResourcesConfiguration 系统信息资源
传输支持 SSE WebMVC, SSE WebFlux, STDIO MCP SDK内置 多种传输协议
核心配置 服务器自定义配置 McpServerConfiguration 可扩展配置

# 🔧 MCP Client 功能清单

功能类别 具体功能 实现类 说明
动态管理 热加载、配置管理 DynamicMcpClientManager 支持运行时配置变更
工具回调 MCP工具转Spring AI ToolCallback SimpleMcpToolCallbackProvider / SpringAiMcpClientManager Spring AI集成
配置服务 配置读取、验证 McpConfigurationService 配置管理服务
REST API 工具列表、状态查询、调用接口 McpToolController Web API接口
测试工具 智能Schema解析、自动测试 SpringAiMcpClientExample 开发测试工具
连接管理 手动MCP客户端创建 McpClientConfiguration 客户端连接管理

# 🚀 使用模式对比

# 🔧 服务端实现步骤对比

# 方案一：Spring AI MCP 生态

  1. 添加依赖 (3个Spring AI包)
  2. 创建工具Bean:
    @Configuration
public class MyToolsConfiguration {
    @Bean
    public SomeSpringAiToolType myTool() {
        // 使用Spring AI抽象
    }
}
    1
    2
    3
    4
    5
    6
    7
  3. 启动应用 - 自动发现和注册

# 方案二：直接 MCP SDK

  1. 添加依赖 (4个MCP SDK包)
  2. 创建工具配置类:
    @Configuration
public class MyToolsConfiguration {
    @Bean
    public List<McpServerFeatures.SyncToolSpecification> myTools() {
        return List.of(createMyTool());
    }
}
    1
    2
    3
    4
    5
    6
    7
  3. 启动应用 - MCP SDK 自动暴露工具

# 🔧 客户端实现步骤对比

# 方案一：Spring AI MCP 生态

  1. 添加依赖 (4个Spring AI包)
  2. 创建客户端管理器:
    @Service
public class SpringAiMcpClientManager {
    public List<ToolCallback> connectToMcpServer(String serverName, String serverUrl) {
        // 使用 SyncMcpToolCallbackProvider
        SyncMcpToolCallbackProvider provider = new SyncMcpToolCallbackProvider(mcpClient);
        return Arrays.asList(provider.getToolCallbacks());
    }
}
    1
    2
    3
    4
    5
    6
    7
    8
  3. 自动获得 Spring AI ToolCallback

# 方案二：直接 MCP SDK

  1. 添加依赖 (3个MCP SDK包)
  2. 创建客户端配置:
    @Bean
public McpSyncClient mcpClient() {
    // 手动创建 MCP 客户端
}
    1
    2
    3
    4
  3. 手动实现 ToolCallback 转换

# ⚠️ 重要说明

# 1. 依赖可用性

  • ✅ MCP SDK (io.modelcontextprotocol.sdk:*): 公开可用
  • ✅ Spring AI MCP (spring-ai-mcp, spring-ai-model): 可用
  • ❌ Spring AI Starters (spring-ai-starter-mcp-*): 不存在
  • ❓ Spring AI AutoConfig (spring-ai-autoconfigure-mcp-client): 当前版本POM有问题

# 2. 技术选择建议

# 选择方案一的场景：

  • ✅ 正在开发基于 Spring AI 的应用
  • ✅ 希望获得官方抽象层和最佳实践
  • ✅ 需要与 Spring AI 生态系统深度集成
  • ✅ 优先考虑未来兼容性和更新支持

# 选择方案二的场景：

  • ✅ 需要独立的 MCP 服务，不依赖 Spring AI
  • ✅ 对依赖和版本有严格控制要求
  • ✅ 需要轻量级的解决方案
  • ✅ 要使用 MCP SDK 的高级特性

# 3. 版本兼容性

  • Spring Boot: 3.2.4
  • Java: 17+
  • Spring AI: 1.1.0-SNAPSHOT
  • MCP SDK: 0.10.0

# 📝 最佳实践

# 🎯 通用原则

  1. 明确技术栈: 基于应用场景选择合适的方案
  2. 依赖管理: 使用具体版本号，避免版本冲突
  3. 测试优先: 使用项目中的示例进行功能验证

# 🎯 方案一最佳实践

  1. 优先使用: Spring AI 提供的 SyncMcpToolCallbackProvider
  2. 避免手工实现: 不要自己实现 ToolCallback 转换逻辑
  3. 传递依赖: 通过 Spring AI 包获得 MCP SDK，不直接依赖

# 🎯 方案二最佳实践

  1. 服务端: 使用 MCP SDK 的原生 Spring 集成
  2. 客户端: 结合手动配置和自定义 ToolCallback 实现
  3. 直接控制: 充分利用 MCP SDK 的原生功能

# 📊 验证方法

# 编译验证

mvn clean compile
1

# 依赖树检查

# 方案一验证：

mvn dependency:tree | grep mcp
1

应该看到：

[INFO] +- org.springframework.ai:spring-ai-mcp:jar:1.1.0-SNAPSHOT:compile
[INFO] |  \- io.modelcontextprotocol.sdk:mcp:jar:0.10.0:compile
1
2

# 方案二验证：

mvn dependency:tree | grep modelcontextprotocol
1

应该看到：

[INFO] +- io.modelcontextprotocol.sdk:mcp:jar:0.10.0:compile
[INFO] +- io.modelcontextprotocol.sdk:mcp-spring-webmvc:jar:0.10.0:compile
[INFO] +- io.modelcontextprotocol.sdk:mcp-spring-webflux:jar:0.10.0:compile
1
2
3

# 🎯 总结

这个完整指南提供了两种成熟的 MCP 开发方式：

# 🚀 方案一：Spring AI MCP 生态（推荐用于Spring AI应用）

  • 利用官方抽象层和最佳实践
  • 获得Spring AI生态系统的完整支持
  • 自动处理版本兼容性和更新

# ⚡ 方案二：直接 MCP SDK（用于独立MCP应用）

  • 直接控制和轻量级实现
  • 不依赖Spring AI版本
  • 充分利用MCP SDK原生功能

根据你的应用场景和技术需求，选择最适合的方案开始你的 MCP 开发之旅！

更新时间: 2025-06-05
适用版本: Spring AI 1.1.0-SNAPSHOT, MCP SDK 0.10.0

上次更新: 2025/06/05, 16:11:33
MCP-SDK源码设计
SpringAI-MCP-Server

← SpringAI-MCP-Server→

最近更新
01
AI是如何学习的
10-29
02
提示词工程实践指南
10-29
03
chatGpt提示原则
10-29
更多文章>
| Copyright © 2022-2025 Kevin | MIT License