7大核心问题与解决方案：Solon-AI-MCP无缝集成Spring Boot实战指南

引言：告别MCP集成的"最后一公里"难题

你是否在Spring Boot项目中集成Solon-AI-MCP时遭遇过这些困扰：启动时的ClassNotFoundException、连接超时的神秘异常、工具调用时的JSON解析错误？作为Model Context Protocol（MCP协议）在Java生态的重要实现，Solon-AI-MCP为AI模型与外部工具的交互提供了标准化接口，但与Spring Boot的集成仍存在诸多"隐性陷阱"。

本文将通过7大典型问题解析+完整代码示例+架构级解决方案，帮助你彻底掌握Solon-AI-MCP与Spring Boot的集成技术。读完本文后，你将能够：

• 快速定位并解决90%的常见集成错误
• 优化MCP客户端的性能与资源占用
• 实现生产级别的MCP服务高可用部署
• 掌握自定义工具与资源适配的高级技巧

MCP协议与Spring Boot集成架构解析

MCP协议核心概念

Model Context Protocol（MCP协议）是一种允许AI模型通过标准化接口与外部工具、资源交互的通信协议。其核心组件包括：

classDiagram
    class McpClient {
        +sync(transport) SyncSpec
        +async(transport) AsyncSpec
    }
    class McpSyncClient {
        +listPrompts() ListPromptsResult
        +callTool() CallToolResult
        +readResource() ReadResourceResult
    }
    class McpAsyncClient {
        +listPrompts() Mono~ListPromptsResult~
        +callTool() Mono~CallToolResult~
        +readResource() Mono~ReadResourceResult~
    }
    class McpTransport {
        <<interface>>
        +sendRequest()
        +receiveResponse()
    }
    McpClient --> McpSyncClient
    McpClient --> McpAsyncClient
    McpSyncClient --> McpTransport
    McpAsyncClient --> McpTransport

Solon-AI-MCP提供了两种客户端实现：

• 同步客户端(McpSyncClient)：适用于简单场景，阻塞式调用
• 异步客户端(McpAsyncClient)：基于Reactor响应式编程，支持非阻塞操作

Spring Boot集成架构

在Spring Boot环境中，MCP客户端的集成需要考虑以下核心组件：

flowchart TD
    A[Spring Boot应用] -->|自动配置| B[MCP客户端Bean]
    B --> C[Transport层]
    C -->|HTTP/SSE/STDIO| D[MCP服务器]
    B --> E[工具调用处理器]
    B --> F[资源访问管理器]
    E --> G[自定义工具实现]
    F --> H[资源加载器]
    A --> I[Spring事件总线]
    E --> I
    F --> I

Spring Boot的依赖注入、生命周期管理与Solon-AI-MCP的集成点主要在三个层面：

1. Bean管理：MCP客户端的创建与销毁
2. 配置体系：外部化配置与动态调整
3. 事件机制：工具调用与资源变更的事件通知

问题一：依赖冲突与版本适配

典型症状

项目启动时出现：

java.lang.ClassNotFoundException: io.modelcontextprotocol.spec.McpSchema$Tool

或Maven依赖解析警告：

Dependency convergence error for org.noear:solon-ai-mcp:1.0.0 paths to dependency are:
+-com.example:spring-boot-mcp-demo:1.0.0
  +-org.noear:solon-ai-mcp:1.0.0
    +-io.modelcontextprotocol:mcp-spec:1.0.0
and
+-com.example:spring-boot-mcp-demo:1.0.0
  +-org.springframework.boot:spring-boot-starter-web:2.7.0
    +-io.modelcontextprotocol:mcp-spec:0.9.0

根本原因

Solon-AI-MCP与Spring Boot的依赖冲突主要源于：

1. MCP规范版本不兼容：不同版本的Solon-AI-MCP依赖不同版本的MCP规范接口
2. Spring Boot自动依赖管理：Spring Boot的依赖仲裁可能引入低版本MCP相关库
3. 传递依赖冲突：Solon-AI-MCP与Spring Boot的某些公共依赖（如Jackson、Reactor）版本不兼容

解决方案

1. 统一MCP规范版本

在pom.xml中显式声明MCP规范版本：

<dependencyManagement>
    <dependencies>
        <!-- 统一MCP规范版本 -->
        <dependency>
            <groupId>io.modelcontextprotocol</groupId>
            <artifactId>mcp-spec</artifactId>
            <version>1.1.0</version>
        </dependency>
        <!-- 统一Reactor版本 -->
        <dependency>
            <groupId>io.projectreactor</groupId>
            <artifactId>reactor-core</artifactId>
            <version>3.4.18</version>
        </dependency>
    </dependencies>
</dependencyManagement>

2. 排除冲突依赖

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-mcp</artifactId>
    <version>1.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>io.modelcontextprotocol</groupId>
            <artifactId>mcp-spec</artifactId>
        </exclusion>
        <exclusion>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3. 兼容性矩阵

Solon-AI-MCP版本	Spring Boot版本	MCP规范版本	JDK版本
1.0.0	2.6.x-2.7.x	1.1.0	8-17
1.1.0	3.0.x-3.1.x	1.2.0	11-21

问题二：MCP客户端Bean的正确配置

典型症状

使用@Autowired注入MCP客户端时出现：

No qualifying bean of type 'io.modelcontextprotocol.client.McpSyncClient' available

或在启动时出现：

java.lang.IllegalStateException: McpClient transport must not be null

根本原因

Spring Boot的依赖注入机制与MCP客户端的构建模式存在差异：

• McpClient采用builder模式创建，而非传统的构造函数注入
• 传输层(Transport)需要根据环境动态选择（HTTP/SSE/STDIO）
• 客户端需要在应用上下文刷新完成后才能初始化

解决方案

1. 同步客户端配置

@Configuration
public class McpClientConfig {

    @Bean
    @ConditionalOnMissingBean
    public McpSyncClient mcpSyncClient(
            @Value("${mcp.server.url}") String serverUrl,
            @Value("${mcp.request.timeout:20000}") int timeout) {
        
        // 创建HTTP传输层
        McpClientTransport transport = new WebRxSseClientTransport.Builder(
                HttpUtilsBuilder.create())
                .sseEndpoint(serverUrl)
                .objectMapper(new ObjectMapper())
                .build();
                
        // 构建同步客户端
        return McpClient.sync(transport)
                .requestTimeout(Duration.ofMillis(timeout))
                .clientInfo(new Implementation("Spring Boot Client", "1.0.0"))
                .capabilities(ClientCapabilities.builder()
                        .tools(true)
                        .resources(true)
                        .prompts(true)
                        .build())
                .build();
    }
}

2. 异步客户端配置

@Configuration
public class McpAsyncClientConfig {

    @Bean
    @ConditionalOnMissingBean
    public McpAsyncClient mcpAsyncClient(
            @Value("${mcp.server.url}") String serverUrl,
            ObjectMapper objectMapper) {
        
        // 创建WebFlux传输层
        McpClientTransport transport = new WebRxStreamableHttpTransport.Builder(
                HttpUtilsBuilder.create(objectMapper))
                .endpoint(serverUrl)
                .resumableStreams(true)
                .build();
                
        // 构建异步客户端
        return McpClient.async(transport)
                .requestTimeout(Duration.ofSeconds(30))
                .initializationTimeout(Duration.ofSeconds(10))
                .loggingConsumer(log -> {
                    log.info("MCP Log: {}", log.getData());
                    return Mono.empty();
                })
                .build();
    }
}

3. 配置属性类

创建专用配置类管理MCP客户端属性：

@ConfigurationProperties(prefix = "mcp.client")
@Data
public class McpClientProperties {
    private String serverUrl;
    private int requestTimeout = 20000;
    private int initializationTimeout = 10000;
    private String clientName = "Spring Boot MCP Client";
    private String clientVersion = "1.0.0";
    private boolean toolsEnabled = true;
    private boolean resourcesEnabled = true;
    private boolean promptsEnabled = true;
    private int maxConnections = 10;
}

在配置类中引用：

@Configuration
@EnableConfigurationProperties(McpClientProperties.class)
public class McpClientConfig {

    @Bean
    public McpSyncClient mcpSyncClient(McpClientProperties properties) {
        // 使用properties配置客户端
        // ...
    }
}

问题三：连接超时与通信异常

典型症状

调用MCP服务时出现：

io.modelcontextprotocol.spec.McpTransportException: Connection timed out: no further information
    at io.modelcontextprotocol.client.WebRxSseClientTransport.receiveResponse(WebRxSseClientTransport.java:156)

或间歇性连接断开：

reactor.core.Exceptions$ReactiveException: io.netty.channel.AbstractChannel$AnnotatedConnectException: Connection refused: localhost/127.0.0.1:8081

根本原因

MCP客户端连接问题通常涉及以下因素：

1. 传输层配置不当：超时设置过短、未配置代理
2. 服务器端未就绪：MCP服务器启动晚于Spring Boot应用
3. 网络环境限制：防火墙阻止长连接、代理配置错误
4. 资源耗尽：连接池配置不合理导致连接泄露

解决方案

1. 完善的超时与重试机制

@Bean
public McpAsyncClient mcpAsyncClient(McpClientProperties properties) {
    // 创建带重试机制的HTTP客户端构建器
    HttpUtilsBuilder httpBuilder = HttpUtilsBuilder.create()
            .connectTimeout(Duration.ofSeconds(5))
            .readTimeout(Duration.ofSeconds(10))
            .retryWhen(Retry.backoff(3, Duration.ofMillis(500))
                    .filter(e -> e instanceof IOException)
                    .onRetryExhaustedThrow((retryBackoffSpec, retrySignal) -> 
                            new McpTransportException("Failed to connect after 3 retries")));
    
    // 创建传输层
    McpClientTransport transport = new WebRxStreamableHttpTransport.Builder(httpBuilder)
            .endpoint(properties.getServerUrl())
            .resumableStreams(true)
            .openConnectionOnStartup(false) // 延迟连接
            .build();
    
    // 构建客户端
    return McpClient.async(transport)
            .requestTimeout(Duration.ofMillis(properties.getRequestTimeout()))
            .initializationTimeout(Duration.ofMillis(properties.getInitializationTimeout()))
            .build();
}

2. 客户端健康检查

@Component
public class McpClientHealthIndicator implements HealthIndicator {

    private final McpSyncClient mcpClient;
    
    // 注入客户端
    public McpClientHealthIndicator(McpSyncClient mcpClient) {
        this.mcpClient = mcpClient;
    }
    
    @Override
    public Health health() {
        try {
            // 发送ping命令检查连接
            Object result = mcpClient.ping();
            return Health.up()
                    .withDetail("serverTime", System.currentTimeMillis())
                    .withDetail("pingResult", result)
                    .build();
        } catch (Exception e) {
            return Health.down(e)
                    .withDetail("error", e.getMessage())
                    .withDetail("time", System.currentTimeMillis())
                    .build();
        }
    }
}

3. 连接池优化配置

@Bean
public HttpUtilsBuilder httpUtilsBuilder() {
    return HttpUtilsBuilder.create()
            .maxConnections(20) // 最大连接数
            .defaultMaxPerRoute(5) // 每个路由的默认最大连接数
            .connectionTimeout(Duration.ofSeconds(3))
            .idleTimeout(Duration.ofSeconds(30))
            .keepAlive(true);
}

4. 启动依赖控制

使用@DependsOn确保MCP客户端在所需服务之后启动：

@Service
@DependsOn("mcpServerHealthIndicator")
public class McpDependentService {
    // 依赖MCP客户端的服务
}

问题四：工具调用与JSON序列化

典型症状

调用工具时出现JSON解析错误：

com.fasterxml.jackson.databind.exc.MismatchedInputException: Cannot deserialize value of type `java.util.HashMap<java.lang.String,java.lang.Object>` from Array value (token `JsonToken.START_ARRAY`)

或参数验证失败：

io.modelcontextprotocol.util.McpException: Invalid tool arguments: Missing required parameter 'userId'

根本原因

MCP工具调用涉及复杂的JSON序列化与反序列化过程，常见问题包括：

1. 数据类型不匹配：Java对象与JSON Schema定义不一致
2. 参数验证缺失：未正确实现工具输入的校验逻辑
3. 日期时间格式：默认序列化格式与MCP服务器要求不符
4. 泛型类型擦除：复杂泛型类型的序列化问题

解决方案

1. 工具调用DTO设计

@Data
public class UserInfoRequest {
    @NotBlank(message = "userId is required")
    private String userId;
    
    @NotNull(message = "includeDetails must be specified")
    private Boolean includeDetails;
    
    @JsonFormat(pattern = "yyyy-MM-dd")
    private LocalDate startDate;
}

@Data
public class UserInfoResponse {
    private String userId;
    private String name;
    private String email;
    private Map<String, Object> details;
}

2. 自定义ObjectMapper配置

@Configuration
public class JacksonConfig {

    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper objectMapper = new ObjectMapper();
        
        // 配置MCP协议要求的JSON格式
        objectMapper.configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false);
        objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        
        // 日期时间序列化
        objectMapper.registerModule(new JavaTimeModule());
        objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
        objectMapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        
        // 支持JDK8特性
        objectMapper.registerModule(new Jdk8Module());
        
        return objectMapper;
    }
}

3. 工具调用服务实现

@Service
public class UserToolService {

    private final McpSyncClient mcpClient;
    private final ObjectMapper objectMapper;
    
    // 构造函数注入
    public UserToolService(McpSyncClient mcpClient, ObjectMapper objectMapper) {
        this.mcpClient = mcpClient;
        this.objectMapper = objectMapper;
    }
    
    public UserInfoResponse getUserInfo(UserInfoRequest request) throws JsonProcessingException {
        // 验证请求参数
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        Validator validator = factory.getValidator();
        Set<ConstraintViolation<UserInfoRequest>> violations = validator.validate(request);
        
        if (!violations.isEmpty()) {
            String errorMsg = violations.stream()
                    .map(v -> v.getPropertyPath() + ": " + v.getMessage())
                    .collect(Collectors.joining(", "));
            throw new IllegalArgumentException("Invalid request: " + errorMsg);
        }
        
        // 构建工具调用请求
        Map<String, Object> args = objectMapper.convertValue(request, Map.class);
        
        CallToolRequest toolRequest = CallToolRequest.builder()
                .name("getUserInfo")
                .arguments(args)
                .build();
        
        // 调用工具
        CallToolResult result = mcpClient.callTool(toolRequest);
        
        // 处理响应
        if (result.isError()) {
            throw new McpException("Tool call failed: " + result.getContent());
        }
        
        // 转换响应结果
        return objectMapper.convertValue(
                result.getStructuredContent(), UserInfoResponse.class);
    }
}

4. JSON Schema验证

@Component
public class ToolRequestValidator {

    private final JsonSchemaValidator jsonSchemaValidator;
    
    public ToolRequestValidator(JsonSchemaValidator jsonSchemaValidator) {
        this.jsonSchemaValidator = jsonSchemaValidator;
    }
    
    public void validateToolRequest(String toolName, Map<String, Object> arguments) {
        // 获取工具的JSON Schema定义
        String schemaJson = getToolSchema(toolName);
        Map<String, Object> schema = new ObjectMapper().readValue(schemaJson, Map.class);
        
        // 验证参数
        ValidationResponse response = jsonSchemaValidator.validate(schema, arguments);
        
        if (!response.isValid()) {
            throw new IllegalArgumentException("Invalid tool arguments: " + response.getMessage());
        }
    }
    
    private String getToolSchema(String toolName) {
        // 从配置或数据库加载JSON Schema
        // ...
    }
}

问题五：资源访问与权限控制

典型症状

访问资源时出现权限错误：

io.modelcontextprotocol.spec.McpError: Permission denied for resource 'file:///data/sensitive.docx'

或资源加载超时：

java.util.concurrent.TimeoutException: Timeout after 30000ms while reading resource

根本原因

MCP资源访问涉及复杂的权限控制与资源管理问题：

1. 权限模型不匹配：Spring Security与MCP权限体系冲突
2. 资源路径解析：URI格式与文件系统路径转换问题
3. 大文件处理：未实现流式读取导致内存溢出
4. 缓存策略：频繁访问相同资源导致性能问题

解决方案

1. 资源访问服务

@Service
public class ResourceAccessService {

    private final McpSyncClient mcpClient;
    private final CacheManager cacheManager;
    
    public ResourceAccessService(McpSyncClient mcpClient, CacheManager cacheManager) {
        this.mcpClient = mcpClient;
        this.cacheManager = cacheManager;
    }
    
    @Cacheable(value = "mcpResources", key = "#resourceUri", unless = "#result == null")
    public String readTextResource(String resourceUri, int cacheSeconds) {
        try {
            // 创建资源读取请求
            ReadResourceRequest request = ReadResourceRequest.builder()
                    .uri(resourceUri)
                    .build();
            
            // 读取资源
            ReadResourceResult result = mcpClient.readResource(request);
            
            // 检查响应类型
            if (result.getContents() instanceof TextResourceContents) {
                return ((TextResourceContents) result.getContents()).getText();
            } else {
                throw new McpException("Unsupported resource type: " + result.getContents().getClass());
            }
        } catch (Exception e) {
            log.error("Failed to read resource: {}", resourceUri, e);
            throw new McpException("Failed to read resource: " + resourceUri, e);
        }
    }
    
    public Flux<DataBuffer> readBinaryResourceStream(String resourceUri) {
        // 异步流式读取大文件
        McpAsyncClient asyncClient = mcpClient.getAsyncClient();
        
        return asyncClient.readResource(ReadResourceRequest.builder()
                .uri(resourceUri)
                .build())
                .flatMapMany(result -> {
                    if (result.getContents() instanceof BlobResourceContents) {
                        return Flux.fromIterable(
                                ((BlobResourceContents) result.getContents()).getChunks());
                    } else {
                        return Flux.error(new McpException("Not a binary resource"));
                    }
                });
    }
}

2. Spring Security集成

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/mcp/resources/public/**").permitAll()
                .antMatchers("/mcp/resources/protected/**").authenticated()
                .antMatchers("/mcp/tools/**").hasRole("AI_AGENT")
            .and()
                .oauth2ResourceServer()
                .jwt()
                .jwtAuthenticationConverter(jwtAuthenticationConverter());
    }
    
    private JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(jwt -> {
            // 从JWT令牌提取MCP权限信息
            List<String> permissions = jwt.getClaimAsStringList("permissions");
            if (permissions == null) {
                return Collections.emptyList();
            }
            
            return permissions.stream()
                    .map(permission -> new SimpleGrantedAuthority("ROLE_" + permission))
                    .collect(Collectors.toList());
        });
        return converter;
    }
}

3. 资源访问AOP日志

@Aspect
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class ResourceAccessAspect {

    private final Logger log = LoggerFactory.getLogger(ResourceAccessAspect.class);
    
    @Around("execution(* com.example.service.ResourceAccessService.read*(..)) && args(resourceUri,..)")
    public Object logResourceAccess(ProceedingJoinPoint joinPoint, String resourceUri) throws Throwable {
        long startTime = System.currentTimeMillis();
        String username = SecurityContextHolder.getContext().getAuthentication().getName();
        
        log.info("Resource access: user={}, uri={}, method={}", 
                username, resourceUri, joinPoint.getSignature().getName());
        
        try {
            Object result = joinPoint.proceed();
            log.info("Resource access completed: uri={}, time={}ms", 
                    resourceUri, System.currentTimeMillis() - startTime);
            return result;
        } catch (Exception e) {
            log.error("Resource access failed: uri={}, error={}", 
                    resourceUri, e.getMessage(), e);
            throw e;
        }
    }
}

问题六：事件处理与异步通信

典型症状

异步工具调用无响应：

// 无异常抛出，但永远不会执行回调
mcpAsyncClient.callTool(toolRequest).subscribe(
    result -> log.info("Result: {}", result),
    error -> log.error("Error: {}", error)
);

或事件监听重复执行：

// 事件被多次处理
mcpAsyncClient.listTools().subscribe(tools -> {
    // 此代码块被执行多次
    registerTools(tools);
});

根本原因

Spring Boot的异步处理模型与MCP的响应式编程模型存在整合挑战：

1. 订阅管理不当：未正确处理Reactor流的生命周期
2. 背压控制缺失：未处理数据生产快于消费的情况
3. 线程池配置：默认线程池不适应MCP的I/O密集型操作
4. 事件去重：资源变更事件未实现幂等处理

解决方案

1. 响应式工具调用

@Service
public class ReactiveToolService {

    private final McpAsyncClient mcpAsyncClient;
    private final Scheduler mcpScheduler;
    
    public ReactiveToolService(McpAsyncClient mcpAsyncClient) {
        this.mcpAsyncClient = mcpAsyncClient;
        // 创建专用调度器
        this.mcpScheduler = Schedulers.newBoundedElastic(10, 100, "mcp-tool-calls");
    }
    
    public Mono<UserInfoResponse> getUserInfoReactively(UserInfoRequest request) {
        return Mono.just(request)
                .publishOn(mcpScheduler)
                .map(req -> {
                    // 转换请求参数
                    Map<String, Object> args = new ObjectMapper().convertValue(req, Map.class);
                    return CallToolRequest.builder()
                            .name("getUserInfo")
                            .arguments(args)
                            .build();
                })
                .flatMap(mcpAsyncClient::callTool)
                .map(result -> {
                    if (result.isError()) {
                        throw new McpException("Tool error: " + result.getContent());
                    }
                    return new ObjectMapper().convertValue(
                            result.getStructuredContent(), UserInfoResponse.class);
                })
                .timeout(Duration.ofSeconds(30))
                .doOnError(e -> log.error("Tool call failed", e))
                .retry(3)
                .onErrorResume(e -> Mono.just(createFallbackResponse(request.getUserId())));
    }
    
    private UserInfoResponse createFallbackResponse(String userId) {
        UserInfoResponse fallback = new UserInfoResponse();
        fallback.setUserId(userId);
        fallback.setName("Unknown");
        fallback.setEmail("[e-mail]");
        return fallback;
    }
}

2. 工具变更监听

@Component
public class ToolChangeListener implements CommandLineRunner, DisposableBean {

    private final McpAsyncClient mcpAsyncClient;
    private final ToolRegistry toolRegistry;
    private Disposable disposable;
    
    public ToolChangeListener(McpAsyncClient mcpAsyncClient, ToolRegistry toolRegistry) {
        this.mcpAsyncClient = mcpAsyncClient;
        this.toolRegistry = toolRegistry;
    }
    
    @Override
    public void run(String... args) {
        // 监听工具变更事件
        disposable = mcpAsyncClient.listTools()
                .repeatWhen(flux -> Flux.interval(Duration.ofMinutes(5)))
                .distinctUntilChanged()
                .subscribe(tools -> {
                    log.info("Tools updated, total: {}", tools.size());
                    toolRegistry.registerTools(tools);
                }, error -> log.error("Tool list subscription error", error));
    }
    
    @Override
    public void destroy() {
        if (disposable != null && !disposable.isDisposed()) {
            disposable.dispose();
            log.info("Tool change listener disposed");
        }
    }
}

3. 响应式线程池配置

@Configuration
public class ReactorConfig {

    @Bean
    public Scheduler mcpScheduler() {
        // 为MCP操作创建专用线程池
        return Schedulers.newBoundedElastic(
                10,  // 核心线程数
                100, // 最大任务队列
                "mcp-pool" // 线程名前缀
        );
    }
    
    @Bean
    public WebClient webClient(Scheduler mcpScheduler) {
        return WebClient.builder()
                .exchangeStrategies(ExchangeStrategies.builder()
                        .codecs(configurer -> configurer.defaultCodecs()
                                .maxInMemorySize(16 * 1024 * 1024)) // 16MB
                        .build())
                .clientConnector(new ReactorClientHttpConnector(
                        HttpClient.create()
                                .runOn(mcpScheduler)
                                .responseTimeout(Duration.ofSeconds(30))
                                .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000)))
                .build();
    }
}

4. 事件总线集成

@Component
public class McpEventBridge {

    private final ApplicationEventPublisher eventPublisher;
    
    public McpEventBridge(ApplicationEventPublisher eventPublisher) {
        this.eventPublisher = eventPublisher;
    }
    
    @PostConstruct
    public void initEventBridge(McpAsyncClient mcpAsyncClient) {
        // 资源变更事件桥接到Spring事件总线
        mcpAsyncClient.resourcesChangeConsumer(resources -> {
            eventPublisher.publishEvent(new McpResourcesChangedEvent(resources));
            return Mono.empty();
        });
        
        // 工具变更事件桥接
        mcpAsyncClient.toolsChangeConsumer(tools -> {
            eventPublisher.publishEvent(new McpToolsChangedEvent(tools));
            return Mono.empty();
        });
    }
    
    // 自定义Spring事件
    public static class McpResourcesChangedEvent extends ApplicationEvent {
        public McpResourcesChangedEvent(List<Resource> resources) {
            super(resources);
        }
        
        public List<Resource> getResources() {
            return (List<Resource>) getSource();
        }
    }
    
    public static class McpToolsChangedEvent extends ApplicationEvent {
        public McpToolsChangedEvent(List<Tool> tools) {
            super(tools);
        }
        
        public List<Tool> getTools() {
            return (List<Tool>) getSource();
        }
    }
}

问题七：集成测试与故障排查

典型症状

测试时出现连接拒绝：

java.net.ConnectException: Connection refused: connect
    at java.base/sun.nio.ch.Net.connect0(Native Method)

或Mock对象不生效：

// 测试中调用的仍是真实MCP服务
when(mcpSyncClient.callTool(any())).thenReturn(mockResult);

根本原因

MCP集成测试面临特殊挑战：

1. 外部依赖：需要MCP服务器才能完成测试
2. 异步操作：测试异步调用的完成状态
3. 模拟复杂度：MCP协议的消息格式复杂
4. 测试覆盖率：难以模拟所有异常场景

解决方案

1. 嵌入式MCP服务器

@SpringBootTest
@TestPropertySource(properties = {
    "mcp.server.url=http://localhost:8765/mcp",
    "mcp.request.timeout=5000"
})
public class McpIntegrationTest {

    private static McpSyncServer embeddedServer;
    
    @BeforeAll
    public static void startEmbeddedServer() {
        // 创建嵌入式MCP服务器
        McpServerTransport transport = new WebRxStatelessServerTransport.Builder()
                .messageEndpoint("/mcp")
                .objectMapper(new ObjectMapper())
                .build();
                
        // 配置测试工具
        SyncToolSpecification userInfoTool = SyncToolSpecification.builder()
                .tool(Tool.builder()
                        .name("getUserInfo")
                        .description("Get user information")
                        .inputSchema(createUserInfoSchema())
                        .build())
                .callHandler((exchange, request) -> {
                    // 模拟工具调用
                    Map<String, Object> result = Map.of(
                        "userId", request.getArguments().get("userId"),
                        "name", "Test User",
                        "email", "[e-mail]"
                    );
                    
                    return CallToolResult.builder()
                            .structuredContent(result)
                            .build();
                })
                .build();
                
        // 启动服务器
        embeddedServer = McpServer.syncSpec()
                .transport(transport)
                .addTool(userInfoTool)
                .build();
        embeddedServer.start();
    }
    
    @AfterAll
    public static void stopEmbeddedServer() {
        if (embeddedServer != null) {
            embeddedServer.stop();
        }
    }
    
    @Test
    public void testUserInfoTool() {
        // 测试代码
    }
}

2. Mock客户端测试

@ExtendWith(MockitoExtension.class)
public class McpServiceMockTest {

    @Mock
    private McpSyncClient mcpSyncClient;
    
    @InjectMocks
    private UserToolService userToolService;
    
    @Test
    public void testGetUserInfo() throws Exception {
        // 准备测试数据
        UserInfoRequest request = new UserInfoRequest();
        request.setUserId("123");
        request.setIncludeDetails(true);
        
        // Mock MCP客户端响应
        CallToolResult mockResult = CallToolResult.builder()
                .structuredContent(Map.of(
                    "userId", "123",
                    "name", "Mock User",
                    "email", "[e-mail]"
                ))
                .build();
                
        when(mcpSyncClient.callTool(any(CallToolRequest.class))).thenReturn(mockResult);
        
        // 执行测试
        UserInfoResponse response = userToolService.getUserInfo(request);
        
        // 验证结果
        assertNotNull(response);
        assertEquals("123", response.getUserId());
        assertEquals("Mock User", response.getName());
        
        verify(mcpSyncClient).callTool(argThat(request -> 
            "getUserInfo".equals(request.getName()) &&
            "123".equals(request.getArguments().get("userId"))
        ));
    }
}

3. 测试容器集成

@SpringBootTest
@Testcontainers
public class McpContainerTest {

    @Container
    static GenericContainer<?> mcpServer = new GenericContainer<>("solonai/mcp-server:latest")
            .withExposedPorts(8080)
            .withEnv("MCP_TOOLS", "userInfo,productSearch")
            .withStartupTimeout(Duration.ofMinutes(2));
            
    @DynamicPropertySource
    static void registerProperties(DynamicPropertyRegistry registry) {
        registry.add("mcp.server.url", () -> 
            "http://" + mcpServer.getHost() + ":" + mcpServer.getMappedPort(8080) + "/mcp");
    }
    
    @Test
    public void testWithRealServer() {
        // 使用测试容器中的真实MCP服务器进行测试
    }
}

4. 故障排查工具

@Component
public class McpDiagnostics {

    private final McpSyncClient mcpClient;
    private final ObjectMapper objectMapper;
    
    public McpDiagnostics(McpSyncClient mcpClient, ObjectMapper objectMapper) {
        this.mcpClient = mcpClient;
        this.objectMapper = objectMapper;
    }
    
    public String generateDiagnosticReport() {
        StringBuilder report = new StringBuilder();
        report.append("=== MCP Client Diagnostic Report ===\n");
        
        try {
            // 连接测试
            Object pingResult = mcpClient.ping();
            report.append("Connection: OK\n");
            report.append("Ping Result: ").append(pingResult).append("\n");
            
            // 服务器信息
            report.append("Server Info: ").append(mcpClient.getServerInfo()).append("\n");
            
            // 可用工具
            List<Tool> tools = mcpClient.listTools();
            report.append("Available Tools: ").append(tools.size()).append("\n");
            tools.forEach(tool -> report.append("- ").append(tool.getName()).append("\n"));
            
            // 资源列表
            List<Resource> resources = mcpClient.listResources();
            report.append("Available Resources: ").append(resources.size()).append("\n");
            
        } catch (Exception e) {
            report.append("Connection Error: ").append(e.getMessage()).append("\n");
            report.append("Stack Trace: ").append(ExceptionUtils.getStackTrace(e)).append("\n");
        }
        
        return report.toString();
    }
}

生产环境最佳实践

高可用配置

@Configuration
public class McpHaConfig {

    @Bean
    public McpSyncClient mcpSyncClient(McpClientProperties properties) {
        // 创建多个传输层，连接不同的MCP服务器
        List<McpClientTransport> transports = Arrays.stream(properties.getServerUrls())
                .map(url -> new WebRxSseClientTransport.Builder(HttpUtilsBuilder.create())
                        .sseEndpoint(url)
                        .objectMapper(new ObjectMapper())
                        .build())
                .collect(Collectors.toList());
                
        // 创建故障转移客户端
        return new FailoverMcpClient(transports.stream()
                .map(transport -> McpClient.sync(transport)
                        .requestTimeout(Duration.ofMillis(properties.getRequestTimeout()))
                        .build())
                .collect(Collectors.toList()));
    }
    
    // 故障转移客户端实现
    static class FailoverMcpClient implements McpSyncClient {
        private final List<McpSyncClient> clients;
        private int currentIndex = 0;
        
        public FailoverMcpClient(List<McpSyncClient> clients) {
            this.clients = clients;
        }
        
        @Override
        public <T> T callTool(CallToolRequest request) {
            for (int i = 0; i < clients.size(); i++) {
                try {
                    McpSyncClient client = clients.get(currentIndex);
                    return client.callTool(request);
                } catch (Exception e) {
                    log.error("MCP client {} failed", currentIndex, e);
                    currentIndex = (currentIndex + 1) % clients.size();
                }
            }
            throw new McpException("All MCP clients failed");
        }
        
        // 其他方法实现...
    }
}

性能优化

@Configuration
public class McpPerformanceConfig {

    @Bean
    public McpAsyncClient mcpAsyncClient(McpClientProperties properties) {
        // 配置连接池
        ConnectionProvider connectionProvider = ConnectionProvider.builder("mcp-pool")
                .maxConnections(20)
                .pendingAcquireTimeout(Duration.ofSeconds(30))
                .build();
                
        // 配置HTTP客户端
        HttpClient httpClient = HttpClient.create(connectionProvider)
                .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000)
                .responseTimeout(Duration.ofSeconds(10))
                .doOnConnected(conn -> conn
                        .addHandlerLast(new ReadTimeoutHandler(10))
                        .addHandlerLast(new WriteTimeoutHandler(10)));
                
        // 创建传输层
        McpClientTransport transport = new WebRxStreamableHttpTransport.Builder(
                HttpUtilsBuilder.create(httpClient))
                .endpoint(properties.getServerUrl())
                .resumableStreams(true)
                .build();
                
        // 构建客户端
        return McpClient.async(transport)
                .requestTimeout(Duration.ofMillis(properties.getRequestTimeout()))
                .initializationTimeout(Duration.ofMillis(properties.getInitializationTimeout()))
                .build();
    }
    
    // 配置缓存
    @Bean
    public CacheManager cacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
        cacheManager.setCaffeine(Caffeine.newBuilder()
                .expireAfterWrite(5, TimeUnit.MINUTES)
                .maximumSize(1000));
        return cacheManager;
    }
}

总结与展望

通过本文的7大核心问题解析，我们系统地解决了Solon-AI-MCP与Spring Boot集成过程中的常见难题。从依赖管理、客户端配置、连接优化到工具调用、资源访问、事件处理和测试策略，我们覆盖了集成过程的各个方面。

随着AI应用的普及，MCP协议作为AI模型与外部世界交互的标准化接口，其重要性将日益凸显。未来的发展方向包括：

1. 服务网格集成：将MCP客户端集成到Istio等服务网格中
2. 云原生部署：提供MCP客户端的Kubernetes Operator
3. 安全增强：支持mTLS和细粒度的权限控制
4. 可观测性：与Prometheus、Grafana等监控系统深度集成

掌握Solon-AI-MCP与Spring Boot的集成技术，将为你的AI应用开发打开新的可能性。无论是构建智能客服、自动化数据分析还是智能决策系统，MCP协议都能为AI模型提供强大的工具调用能力，而本文提供的解决方案将确保你的集成项目顺利实施。

收藏本文，当你在集成Solon-AI-MCP时遇到问题，它将成为你快速解决问题的实用指南。如有任何疑问或建议，欢迎在评论区留言讨论。

附录：常见错误速查表

错误类型	可能原因	解决方案
ClassNotFoundException	MCP规范版本冲突	统一mcp-spec依赖版本
ConnectionTimeoutException	服务器未启动或网络问题	检查服务器状态，增加超时设置
JsonProcessingException	数据类型不匹配	调整DTO类或自定义ObjectMapper
McpTransportException	传输层配置错误	检查传输层实现和URL配置
IllegalStateException	客户端未正确初始化	确保在应用就绪后使用客户端
NullPointerException	工具参数为空	增加参数校验和默认值
ReactiveException	异步操作未正确处理	使用正确的响应式编程模式
ValidationException	参数验证失败	完善DTO的校验注解