Kevin's blog
kevin
2025-06-06
目录

SpringAI-MCP-Server

# Spring AI MCP服务器：核心概念与实现详解

# 引言

Model Context Protocol (MCP) 是一个开放标准，用于AI模型与外部工具和资源的交互。Spring AI提供了对MCP的原生支持，使开发者能够轻松创建MCP服务器，为AI模型提供工具和资源。本文将深入探讨Spring AI MCP服务器的核心概念和实现细节。

# MCP服务器基础

MCP服务器本质上是一个提供工具、资源和提示模板的服务端点，允许AI模型和其他客户端通过标准协议进行交互。Spring AI通过自动装配机制简化了MCP服务器的创建和配置过程。

# 服务器类型

Spring AI支持两种类型的MCP服务器：

  1. 同步服务器(Sync)：基于McpSyncServer实现，适用于请求-响应模式的交互。这是默认模式，适合大多数场景。
  2. 异步服务器(Async)：基于McpAsyncServer实现，支持非阻塞操作，适用于响应式编程模型和高并发场景。

通过配置属性spring.ai.mcp.server.type可以选择服务器类型：

spring:
  ai:
    mcp:
      server:
        type: SYNC  # 或 ASYNC
1
2
3
4
5

# 工具注册机制

MCP服务器的核心功能是提供工具(Tools)，Spring AI提供了两种注册工具的方式：

# 1. 原生MCP方式

直接使用MCP SDK的原生类型创建工具规范：

@Bean
public SyncToolSpecification addTool() {
    return SyncToolSpecification.builder()
        .tool(McpSchema.Tool.builder()
            .name("add")
            .description("将两个数字相加")
            .inputSchema(/* 输入模式 */)
            .build())
        .handler((exchange, arguments) -> {
            // 工具实现逻辑
            double a = arguments.get("a").asDouble();
            double b = arguments.get("b").asDouble();
            return McpSchema.CallToolResult.builder()
                .content(String.valueOf(a + b))
                .build();
        })
        .build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

这种方式直接使用MCP SDK的原生类型，不需要任何转换，适合需要完全控制MCP细节的场景。

# 2. Spring AI抽象方式

使用Spring AI的ToolCallback接口：

@Bean
public ToolCallback calculatorTool() {
    return ToolCallback.builder()
        .toolDefinition(ToolDefinition.builder()
            .name("calculator")
            .description("执行基本数学运算")
            .parameter("operation", String.class, "要执行的操作(add, subtract, multiply, divide)")
            .parameter("a", Double.class, "第一个数字")
            .parameter("b", Double.class, "第二个数字")
            .build())
        .handler(params -> {
            // 工具实现逻辑
            String operation = params.get("operation");
            double a = (Double) params.get("a");
            double b = (Double) params.get("b");
            
            // 执行计算并返回结果
            double result = switch(operation) {
                case "add" -> a + b;
                case "subtract" -> a - b;
                case "multiply" -> a * b;
                case "divide" -> a / b;
                default -> throw new IllegalArgumentException("不支持的操作: " + operation);
            };
            
            return Map.of("result", result);
        })
        .build();
}
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

这种方式使用Spring AI的抽象，更符合Spring生态系统的设计理念，适合与其他Spring AI组件集成的场景。

# 工具转换机制

Spring AI会自动将ToolCallback转换为MCP原生的工具规范：

  • 同步模式下，syncTools方法将ToolCallback转换为SyncToolSpecification
  • 异步模式下，asyncTools方法将ToolCallback转换为AsyncToolSpecification

这种转换是透明的，开发者无需关心具体细节。

# 服务器自动装配

Spring AI通过自动装配机制简化了MCP服务器的创建和配置过程。核心自动装配类是McpServerAutoConfiguration，它负责：

  1. 收集所有工具规范（原生或转换后的）
  2. 创建适当类型的MCP服务器实例
  3. 注册工具、资源、提示和完成规范
  4. 配置服务器能力和其他设置

# 关键Bean方法

McpServerAutoConfiguration中的关键Bean方法包括：

  • syncTools：收集并转换同步工具
  • mcpSyncServer：创建同步MCP服务器实例
  • asyncTools：收集并转换异步工具
  • mcpAsyncServer：创建异步MCP服务器实例

这些方法通过条件注解确保只有一套组件（同步或异步）会被激活。

# 传输层支持

STDIO传输适用场景：

  • 本地工具集成（IDE插件、命令行工具）
  • 进程间通信（同机器内的服务协作）
  • 开发调试环境（快速原型验证）

HTTP传输适用场景（WebMVC SSE、WebFlux SSE）：

  • 微服务架构（跨网络的服务调用）
  • Web应用集成（浏览器端的AI功能）
  • 云原生部署（容器化和分布式环境）

通过配置可以启用一种或多种传输方式：

spring:
  ai:
    mcp:
      server:
        stdio:
          enabled: true
        webmvc:
          enabled: true
          endpoint: "/mcp/sse"
        webflux:
          enabled: true
          endpoint: "/mcp/webflux/sse"
1
2
3
4
5
6
7
8
9
10
11
12

依赖项：

<!-- WebMVC传输必需 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

<!-- STDIO传输必需 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>
1
2
3
4
5
6
7
8
9
10
11

# 传输方式配置冲突

常见问题：配置了WebMVC相关依赖，但HTTP端点返回404错误

问题根源：

spring:
  ai:
    mcp:
      server:
        stdio: true  # ❌ 这会禁用HTTP传输
1
2
3
4
5

解决方案：

spring:
  ai:
    mcp:
      server:
        stdio: false  # ✅ 启用HTTP传输
        sse-message-endpoint: "/mcp/message"
        sse-endpoint: "/sse"
1
2
3
4
5
6
7

# 🏗️ 设计考虑-技术架构限制

# 1. 单一传输提供者设计

从源码可以看到，Spring AI MCP使用了单一传输提供者的设计：

auto-configurations/mcp/spring-ai-autoconfigure-mcp-server/src/main/java/org/springframework/ai/mcp/server/autoconfigure

@Bean
@ConditionalOnMissingBean
public McpServerTransportProvider stdioServerTransport() {
    return new StdioServerTransportProvider();
}
1
2
3
4
5

auto-configurations/mcp/spring-ai-autoconfigure-mcp-server/src/main/java/org/springframework/ai/mcp/server/autoconfigure

@ConditionalOnMissingBean(McpServerTransportProvider.class)  // 关键：互斥条件
@Conditional(McpServerStdioDisabledCondition.class)
public class McpWebMvcServerAutoConfiguration {
1
2
3

设计特点：

  • 使用@ConditionalOnMissingBean(McpServerTransportProvider.class)确保只有一个传输提供者
  • 一旦STDIO传输被创建，HTTP传输就被排除

# 2. MCP服务器实例绑定

每个MCP服务器实例只能绑定到一个传输提供者：

// 伪代码示例
McpSyncServer server = McpServer.sync(transportProvider) // 只能绑定一个传输
  .serverInfo("name", "version")
  .capabilities(capabilities)
  .build();
1
2
3
4
5

# 🎯 设计理念考虑

# 1. 简化配置和管理

  • 避免配置复杂性：不需要管理多个端口、多套安全策略
  • 减少错误配置：防止端口冲突、权限混乱等问题
  • 清晰的职责分离：每个服务实例有明确的通信方式

# 2. 性能和资源优化

  • 避免资源浪费：不需要同时维护多个传输层
  • 减少内存占用：只加载需要的传输组件
  • 简化线程模型：避免多传输方式的并发复杂性

# 3. 安全考虑

  • 攻击面最小化：只暴露必要的通信接口
  • 权限隔离：STDIO（本地）和HTTP（网络）有不同的安全模型
  • 审计简化：单一通信渠道便于监控和日志记录

# 🔄 替代方案

虽然单个服务器不支持多传输，但可以通过以下方式实现类似效果：

# 1. 多实例部署

# 实例1：STDIO传输
spring:
  ai:
    mcp:
      server:
        stdio: true
        
# 实例2：HTTP传输  
spring:
  ai:
    mcp:
      server:
        stdio: false
1
2
3
4
5
6
7
8
9
10
11
12
13

# 2. 代理模式

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│ HTTP Client │───▶│ HTTP-to-STDIO│───▶│ STDIO Server│
└─────────────┘    │    Proxy     │    └─────────────┘
                   └──────────────┘
1
2
3
4

# 3. 网关聚合

┌─────────────┐    ┌─────────────┐
│ HTTP Client │───▶│             │
└─────────────┘    │   Gateway   │
┌─────────────┐    │             │    ┌─────────────┐
│STDIO Client │───▶│             │───▶│ MCP Services│
└─────────────┘    └─────────────┘    └─────────────┘
1
2
3
4
5
6

# 🤔 其他MCP实现的对比

# Claude Desktop MCP

  • 主要使用STDIO传输
  • 专注于本地工具集成
  • 简单、高效的进程间通信

# 自定义MCP服务器

  • 可以实现多传输支持
  • 需要自己处理复杂性
  • 更大的开发和维护成本

# 💡 小结

Spring AI MCP选择单传输设计是基于：

  1. 简化架构：避免多传输的复杂性
  2. 明确用途：STDIO用于本地集成，HTTP用于网络服务
  3. 资源效率：只加载需要的组件
  4. 安全考虑：最小化攻击面
  5. 维护性：降低配置和调试复杂度

这种设计遵循了"单一职责原则"和"最小惊讶原则"，虽然牺牲了一些灵活性，但换来了更好的可维护性和可靠性。

如果确实需要同时支持多种传输方式，建议部署多个专用实例或使用代理/网关模式来实现。

# 资源和提示支持

除了工具，MCP服务器还支持资源和提示模板：

# 资源(Resources)

资源允许AI模型访问文件、数据库和其他外部数据源：

@Bean
public SyncResourceSpecification systemInfo() {
    return SyncResourceSpecification.builder()
        .resource(McpSchema.Resource.builder()
            .uri("system://info")
            .name("系统信息")
            .description("提供系统和JVM信息")
            .build())
        .handler((exchange, uri) -> {
            // 资源实现逻辑
            return McpSchema.ReadResourceResult.builder()
                .contents("系统信息内容...")
                .build();
        })
        .build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 提示模板(Prompts)

提示模板允许服务器提供标准化的提示模式：

@Bean
public SyncPromptSpecification weatherPrompt() {
    return SyncPromptSpecification.builder()
        .prompt(McpSchema.Prompt.builder()
            .name("weather_query")
            .description("天气查询提示模板")
            .build())
        .handler((exchange, name) -> {
            return McpSchema.GetPromptResult.builder()
                .content("请查询{{location}}的天气情况")
                .build();
        })
        .build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 实际应用示例

下面是一个完整的MCP服务器配置示例，包含工具、资源和提示：

@Configuration
public class McpServerConfig {

    @Bean
    public SyncToolSpecification calculatorTool() {
        return SyncToolSpecification.builder()
            .tool(McpSchema.Tool.builder()
                .name("calculator")
                .description("执行基本数学运算")
                .inputSchema(/* 输入模式 */)
                .build())
            .handler((exchange, arguments) -> {
                // 实现逻辑
                return McpSchema.CallToolResult.builder()
                    .content("计算结果...")
                    .build();
            })
            .build();
    }
    
    @Bean
    public SyncResourceSpecification weatherData() {
        return SyncResourceSpecification.builder()
            .resource(McpSchema.Resource.builder()
                .uri("weather://data")
                .name("天气数据")
                .description("提供全球主要城市的天气数据")
                .build())
            .handler((exchange, uri) -> {
                // 实现逻辑
                return McpSchema.ReadResourceResult.builder()
                    .contents("天气数据内容...")
                    .build();
            })
            .build();
    }
    
    @Bean
    public SyncPromptSpecification queryTemplate() {
        return SyncPromptSpecification.builder()
            .prompt(McpSchema.Prompt.builder()
                .name("query_template")
                .description("通用查询模板")
                .build())
            .handler((exchange, name) -> {
                return McpSchema.GetPromptResult.builder()
                    .content("请查询关于{{topic}}的信息")
                    .build();
            })
            .build();
    }
}
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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

# 配置属性

Spring AI提供了丰富的配置选项，通过 application.yml或``application.properties`文件进行配置：

spring:
  ai:
    mcp:
      server:
        enabled: true
        name: "AI工具服务器"
        version: "1.0.0"
        type: SYNC
        instructions: "这个服务器提供各种工具和资源"
        request-timeout: PT30S
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
        tool-change-notification: true
        resource-change-notification: true
        prompt-change-notification: true
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 最佳实践

  1. 选择合适的服务器类型：对于大多数应用，同步服务器足够；对于高并发或响应式应用，考虑使用异步服务器。

  2. 工具注册方式

    • 使用原生MCP方式获得最大控制权
    • 使用Spring AI抽象方式获得更好的Spring生态集成

  3. 工具命名：确保工具名称唯一且描述性强，便于AI模型理解和使用。

  4. 错误处理：在工具处理器中实现健壮的错误处理，返回有意义的错误信息。

  5. 性能考虑：对于耗时操作，考虑使用异步服务器或在工具内部实现异步处理。

# 总结

Spring AI MCP服务器提供了一种标准化的方式，使AI模型能够与外部工具和资源交互。通过Spring Boot的自动装配机制，开发者可以轻松创建和配置MCP服务器，无需深入了解底层协议细节。

无论是构建简单的工具集合，还是复杂的AI辅助系统，Spring AI MCP服务器都提供了灵活且强大的基础设施，帮助开发者将AI能力与现有系统无缝集成。

通过理解这些核心概念和实现细节，开发者可以充分利用Spring AI MCP服务器的功能，为AI模型提供丰富的工具和资源，实现更智能、更强大的应用程序。

上次更新: 2025/06/05, 15:56:13
MCP 开发完整指南
Spring AI MCP 依赖配置指南

← Spring AI MCP 依赖配置指南→

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