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

MCP 服务Starters

spring-doc.cadn.net.cn

Model Context Protocol (MCP) Servers

是程序,通过标准化协议接口向AI应用程序提供特定的能力。spring-doc.cadn.net.cn

每个服务器为特定的领域提供专注于其功能。spring-doc.cadn.net.cn

spring-doc.cadn.net.cn

The Spring AI MCP Server Boot Starters provide auto-configuration for setting up MCP服务器 in Spring Boot应用程序. 它们使MCP服务器功能与Spring Boot的自动配置系统无缝集成。spring-doc.cadn.net.cn

MCP 服务器启动Starters提供:spring-doc.cadn.net.cn

MCP服务器启动Starters

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

标准输出

服务池类型设置 依赖 属性

标准输入输出(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

Spring Boot

服务池类型设置spring-doc.cadn.net.cn

依赖spring-doc.cadn.net.cn

属性spring-doc.cadn.net.cn

Spring Security Extended Web MVCspring-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

Spring的流式HTTP MVC框架spring-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

属性spring-doc.cadn.net.cn

Spring 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

状态less Web Fluxspring-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

服务器协议Server Protocols

MCP提供了几种协议类型,包括: HTTP/1.1、WebSocket和远程过程调用(RPC)。spring-doc.cadn.net.cn

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

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

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

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

按钮Sync/Async Server API Options

MCP服务器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

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

MCP 服务器注释

MCP服务器启动脚本提供全面的支持,允许您通过声明性的Java注解而不是手动配置来创建MCP服务器。spring-doc.cadn.net.cn

关键注释

特殊参数

参数化系统支持[{"Item1":"href","Item2":"mcp-annotations-special-params.html"},{"Item1":"class","Item2":"xref page"}]特殊参数类型,这些类型提供额外的上下文信息: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

By default, the McpTransportContext是空(McpTransportContext.EMPTY). This is by design, to keep the MCP server transport-agnostic.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();
}

Once configured, access the context via McpSyncRequestContext (or McpAsyncRequestContext) in your tool.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.";
}

自动配置

使用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

更多资源

示例应用程序