此版本仍在开发中,尚未被视为稳定版。如需最新的快照版本,请使用 Spring AI 1.1.3spring-doc.cadn.net.cn

MCP Server Boot Starters

模型上下文协议 (MCP) 服务器 是通过标准化协议接口向 AI 应用程序暴露特定能力的程序。 每个服务器为特定领域提供专注的功能。spring-doc.cadn.net.cn

Spring AI MCP Server Boot Starters 为在 Spring Boot 应用程序中设置 MCP 服务器 提供了自动配置功能。 它们实现了 MCP 服务器能力与 Spring Boot 自动配置系统的无缝集成。spring-doc.cadn.net.cn

MCP Server Boot Starters 提供:spring-doc.cadn.net.cn

MCP 服务器Starters

MCP 服务器支持多种协议和传输机制。 请使用专用的 starter 并配置正确的 spring.ai.mcp.server.protocol 属性来设置您的服务器:spring-doc.cadn.net.cn

标准输入输出

服务器类型 依赖 <property> </property>

标准输入/输出 (STDIO)spring-doc.cadn.net.cn

spring-ai-starter-mcp-serverspring-doc.cadn.net.cn

spring.ai.mcp.server.stdio=truespring-doc.cadn.net.cn

Web MVC

服务器类型spring-doc.cadn.net.cn

依赖spring-doc.cadn.net.cn

<property> </property>spring-doc.cadn.net.cn

SSE WebMVCspring-doc.cadn.net.cn

spring-ai-starter-mcp-server-webmvcspring-doc.cadn.net.cn

spring.ai.mcp.server.protocol=SSE 或空spring-doc.cadn.net.cn

可流式传输的 HTTP WebMVCspring-doc.cadn.net.cn

spring-ai-starter-mcp-server-webmvcspring-doc.cadn.net.cn

spring.ai.mcp.server.protocol=STREAMABLEspring-doc.cadn.net.cn

无状态 WebMVCspring-doc.cadn.net.cn

spring-ai-starter-mcp-server-webmvcspring-doc.cadn.net.cn

spring.ai.mcp.server.protocol=STATELESSspring-doc.cadn.net.cn

WebMVC(响应式)

服务器类型spring-doc.cadn.net.cn

依赖spring-doc.cadn.net.cn

<property> </property>spring-doc.cadn.net.cn

SSE WebFluxspring-doc.cadn.net.cn

spring-ai-starter-mcp-server-webfluxspring-doc.cadn.net.cn

spring.ai.mcp.server.protocol=SSE 或空spring-doc.cadn.net.cn

可流式传输的 HTTP WebFluxspring-doc.cadn.net.cn

spring-ai-starter-mcp-server-webfluxspring-doc.cadn.net.cn

spring.ai.mcp.server.protocol=STREAMABLEspring-doc.cadn.net.cn

无状态 WebFluxspring-doc.cadn.net.cn

spring-ai-starter-mcp-server-webfluxspring-doc.cadn.net.cn

spring.ai.mcp.server.protocol=STATELESSspring-doc.cadn.net.cn

服务器能力

根据服务器和传输类型的不同,MCP 服务器可以支持各种功能,例如:spring-doc.cadn.net.cn

  • 工具 - 允许服务器暴露可由语言模型调用的工具spring-doc.cadn.net.cn

  • 资源 - 提供了一种标准化的方式,供服务器向客户端暴露资源spring-doc.cadn.net.cn

  • 提示词 - 为服务器向客户端暴露提示词模板提供了一种标准化方式spring-doc.cadn.net.cn

  • 实用工具/补全 - 为服务器提供一种标准化的方式,以便为提示和资源 URI 提供参数自动补全建议spring-doc.cadn.net.cn

  • 实用工具/日志记录 - 为服务器向客户端发送结构化日志消息提供了一种标准化方式spring-doc.cadn.net.cn

  • 工具/进度 - 通过通知消息为长时间运行的操作提供可选的进度跟踪spring-doc.cadn.net.cn

  • 实用工具/Ping - 服务器报告其状态的可选健康检查机制spring-doc.cadn.net.cn

所有功能默认启用。禁用某项功能将阻止服务器向客户端注册和暴露相应的特性。spring-doc.cadn.net.cn

服务器协议

MCP 提供多种协议类型,包括:spring-doc.cadn.net.cn

  • 标准输入输出 - 进程内(例如,服务器在宿主应用程序内部运行)协议。通信通过标准输入和标准输出进行。要启用STDIO,请设置spring.ai.mcp.server.stdio=truespring-doc.cadn.net.cn

  • SSE - 用于实时更新的服务端发送事件协议。服务器作为独立进程运行,可处理多个客户端连接。spring-doc.cadn.net.cn

  • 可流式传输的 HTTP - 可流式传输的 HTTP 传输 允许 MCP 服务器作为独立进程运行,能够使用 HTTP POST 和 GET 请求处理多个客户端连接,并支持可选的服务器发送事件 (SSE) 流式传输以发送多条服务器消息。它取代了 SSE 传输。要启用 STREAMABLE 协议,请设置 spring.ai.mcp.server.protocol=STREAMABLEspring-doc.cadn.net.cn

  • 无状态 - 无状态 MCP 服务器专为简化部署而设计,不在请求之间维护会话状态。 它们非常适合微服务架构和云原生部署。要启用 STATELESS 协议,请设置 spring.ai.mcp.server.protocol=STATELESSspring-doc.cadn.net.cn

同步/异步服务器 API 选项

MCP Server API 支持命令式(即同步)和响应式(例如异步)编程模型。spring-doc.cadn.net.cn

  • 同步服务器 - 使用 McpSyncServer 实现的默认服务器类型。 它专为应用程序中简单的请求 - 响应模式而设计。 要启用此服务器类型,请在配置中设置 spring.ai.mcp.server.type=SYNC。 激活后,它将自动处理同步工具规范的配置。spring-doc.cadn.net.cn

注意:SYNC 服务器仅注册同步的 MCP 注解方法。异步方法将被忽略。spring-doc.cadn.net.cn

  • 异步服务器 - 异步服务器实现使用 McpAsyncServer 并针对非阻塞操作进行了优化。 要启用此服务器类型,请使用 spring.ai.mcp.server.type=ASYNC 配置您的应用程序。 此服务器类型会自动设置带有内置 Project Reactor 支持的异步工具规范。spring-doc.cadn.net.cn

注意:ASYNC 服务器仅注册带有异步 MCP 注解的方法。同步方法将被忽略。spring-doc.cadn.net.cn

MCP 服务器注解

MCP Server Boot Starters 为基于注解的服务器开发提供了全面支持,使您能够使用声明式的 Java 注解来创建 MCP 服务器,而无需手动配置。spring-doc.cadn.net.cn

关键注解

特殊参数

注解系统支持 特殊参数类型,以提供额外的上下文:spring-doc.cadn.net.cn

简单示例

@Component
public class CalculatorTools {

    @McpTool(name = "add", description = "Add two numbers together")
    public int add(
            @McpToolParam(description = "First number", required = true) int a,
            @McpToolParam(description = "Second number", required = true) int b) {
        return a + b;
    }

    @McpResource(uri = "config://{key}", name = "Configuration")
    public String getConfig(String key) {
        return configData.get(key);
    }
}

向 McpTransportContext 添加数据

默认情况下,McpTransportContext 为空(McpTransportContext.EMPTY)。 这是设计使然,旨在保持 MCP 服务器与传输方式无关。spring-doc.cadn.net.cn

如果您的工具需要特定于传输的元数据(例如,HTTP 头、远程主机等), 请在您的传输提供者上配置一个 TransportContextExtractorspring-doc.cadn.net.cn

@Bean
public WebMvcStreamableServerTransportProvider transport(ObjectMapper objectMapper) {
    return WebMvcStreamableServerTransportProvider.builder()
        .contextExtractor(serverRequest -> {
            String authorization = serverRequest.headers().firstHeader("Authorization");
            return McpTransportContext.create(Map.of("authorization", authorization));
        })
        .build();
}

配置完成后,在您的工具中通过 McpSyncRequestContext(或 McpAsyncRequestContext)访问上下文。spring-doc.cadn.net.cn

@McpTool
public String accessProtectedResource(McpSyncRequestContext requestContext) {
    McpTransportContext context = requestContext.transportContext();
    String authorization = (String) context.get("authorization");

    return "Successfully accessed protected resource.";
}

Auto-Configuration

借助 Spring Boot 自动配置,带注解的 Bean 会被自动检测并注册:spring-doc.cadn.net.cn

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

自动配置将:spring-doc.cadn.net.cn

  1. 扫描带有 MCP 注解的 Beanspring-doc.cadn.net.cn

  2. 创建适当的规范spring-doc.cadn.net.cn

  3. 将它们注册到 MCP 服务器spring-doc.cadn.net.cn

  4. 根据配置同时支持同步和异步实现spring-doc.cadn.net.cn

配置属性

配置服务器注解扫描器:spring-doc.cadn.net.cn

spring:
  ai:
    mcp:
      server:
        type: SYNC  # or ASYNC
        annotation-scanner:
          enabled: true

附加资源

示例应用