SpringAI-MCP Server Boot Starter-AI中文站

Spring AI MCP（模型上下文协议）服务器启动器 (Spring AI MCP Server Boot Starter) 为在 Spring Boot 应用程序中设置 MCP 服务器提供自动配置。它使 MCP 服务器功能能够与 Spring Boot 的自动配置系统无缝集成。

MCP 服务器启动器提供：

MCP 服务器组件的自动配置
支持同步和异步操作模式
多种传输层选项
灵活的工具、资源和提示规范
变更通知能力

启动器 (Starters)

Spring AI 的自动配置、启动器模块的工件名称发生了重大变化。请参阅升级说明以获取更多信息。

根据您的传输需求选择以下启动器之一：

标准 MCP 服务器 (Standard MCP Server)

支持完整 MCP 服务器功能，带有 STDIO 服务器传输。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
</dependency>

-适用于命令行和桌面工具
-无需额外的 Web 依赖项
该启动器激活负责以下工作的 McpServerAutoConfiguration 自动配置：

配置基本服务器组件
处理工具、资源和提示规范
管理服务器能力和变更通知
提供同步和异步服务器实现

WebMVC 服务器传输 (WebMVC Server Transport)

支持完整 MCP 服务器功能，带有基于 Spring MVC 的 SSE（服务器发送事件）服务器传输以及可选的 STDIO 传输。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>
该启动器激活 McpWebMvcServerAutoConfiguration 和 McpServerAutoConfiguration 自动配置，以提供：

使用 Spring MVC 的基于 HTTP 的传输 (WebMvcSseServerTransportProvider)
自动配置的 SSE 端点
可选的 STDIO 传输（通过设置 spring.ai.mcp.server.stdio=true 启用）
包含 spring-boot-starter-web 和 mcp-spring-webmvc 依赖项

WebFlux 服务器传输 (WebFlux Server Transport)

支持完整 MCP 服务器功能，带有基于 Spring WebFlux 的 SSE（服务器发送事件）服务器传输以及可选的 STDIO 传输。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>
该启动器激活 McpWebFluxServerAutoConfiguration 和 McpServerAutoConfiguration 自动配置，以提供：

使用 Spring WebFlux 的反应式传输 (WebFluxSseServerTransportProvider)
自动配置的反应式 SSE 端点
可选的 STDIO 传输（通过设置 spring.ai.mcp.server.stdio=true 启用）
包含 spring-boot-starter-webflux 和 mcp-spring-webflux 依赖项

配置属性 (Configuration Properties)

所有属性都以 spring.ai.mcp.server 为前缀：

属性 (Property)	描述 (Description)	默认值 (Default)
`enabled`	启用/禁用 MCP 服务器	`true`
`stdio`	启用/禁用 stdio 传输	`false`
`name`	用于标识的服务器名称	`mcp-server`
`version`	服务器版本	`1.0.0`
`instructions`	可选的指令，用于向客户端提供如何与此服务器交互的指导	`null`
`type`	服务器类型 (`SYNC`/`ASYNC`)	`SYNC`
`capabilities.resource`	启用/禁用资源能力	`true`
`capabilities.tool`	启用/禁用工具能力	`true`
`capabilities.prompt`	启用/禁用提示能力	`true`
`capabilities.completion`	启用/禁用补全能力	`true`
`resource-change-notification`	启用资源变更通知	`true`
`prompt-change-notification`	启用提示变更通知	`true`
`tool-change-notification`	启用工具变更通知	`true`
`tool-response-mime-type`	(可选) 按工具名称指定的响应 MIME 类型。例如 `spring.ai.mcp.server.tool-response-mime-type.generateImage=image/png` 会将 `image/png` MIME 类型与 `generateImage()` 工具名称关联	`-`
`sse-message-endpoint`	用于 Web 传输的自定义 SSE 消息端点路径，客户端使用此路径发送消息	`/mcp/message`
`sse-endpoint`	用于 Web 传输的自定义 SSE 端点路径	`/sse`
`base-url`	可选的 URL 前缀。例如 `base-url=/api/v1` 意味着客户端应在 `/api/v1` + `sse-endpoint` 访问 SSE 端点，消息端点是 `/api/v1` + `sse-message-endpoint`	`-`
`request-timeout`	服务器响应超时时长。适用于通过客户端发出的所有请求，包括工具调用、资源访问和提示操作。	`20` 秒

同步/异步服务器类型 (Sync/Async Server Types)

同步服务器 (Synchronous Server) - 使用 McpSyncServer 实现的默认服务器类型。它专为应用程序中的直接请求-响应模式而设计。要在配置中启用此服务器类型，请设置 spring.ai.mcp.server.type=SYNC。激活时，它会自动处理同步工具规范的配置。

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

服务器能力 (Server Capabilities)

MCP 服务器支持四种主要能力类型，可以单独启用或禁用：

工具 (Tools) - 使用 spring.ai.mcp.server.capabilities.tool=true|false 启用/禁用工具能力
资源 (Resources) - 使用 spring.ai.mcp.server.capabilities.resource=true|false 启用/禁用资源能力
提示 (Prompts) - 使用 spring.ai.mcp.server.capabilities.prompt=true|false 启用/禁用提示能力
补全 (Completions) - 使用 spring.ai.mcp.server.capabilities.completion=true|false 启用/禁用补全能力

所有能力默认启用。禁用某项能力将阻止服务器向客户端注册和暴露相应的功能。

传输选项 (Transport Options)

MCP 服务器支持三种传输机制，每种都有其专用的启动器：

标准输入输出 (STDIO) - spring-ai-starter-mcp-server
Spring MVC (服务器发送事件 - SSE) - spring-ai-starter-mcp-server-webmvc
Spring WebFlux (反应式 SSE) - spring-ai-starter-mcp-server-webflux

特性和能力 (Features and Capabilities)

MCP 服务器启动器允许服务器向客户端公开工具、资源和提示。它会自动将注册为 Spring Bean 的自定义能力处理程序根据服务器类型转换为同步/异步规范：

工具 (Tools)

允许服务器公开可由语言模型调用的工具。MCP 服务器启动器提供：

变更通知支持
Spring AI Tools 根据服务器类型自动转换为同步/异步规范

通过 Spring Bean 自动配置工具规范：

@Bean
public ToolCallbackProvider myTools(...) {
    List<ToolCallback> tools = ...
    return ToolCallbackProvider.from(tools);
}

或使用低级 API：

@Bean
public List<McpServerFeatures.SyncToolSpecification> myTools(...) {
    List<McpServerFeatures.SyncToolSpecification> tools = ...
    return tools;
}

自动配置将从以下位置自动检测并注册所有工具回调：

单个 ToolCallback bean
ToolCallback bean 的列表
ToolCallbackProvider bean
工具按名称去重，使用每个工具名称的首次出现。

工具上下文支持 (Tool Context Support)
支持 ToolContext，允许将上下文信息传递给工具调用。它包含 exchange 键下的 McpSyncServerExchange 实例，可通过 McpToolUtils.getMcpExchange(toolContext) 访问。参见演示 exchange.loggingNotification(…) 和 exchange.createMessage(…) 的示例。

资源管理 (Resource Management)

为服务器向客户端公开资源提供标准化方法。

静态和动态资源规范
可选的变更通知
支持资源模板
同步/异步资源规范之间的自动转换

通过 Spring Bean 自动配置资源规范：

@Bean
public List<McpServerFeatures.SyncResourceSpecification> myResources(...) {
    var systemInfoResource = new McpSchema.Resource(...);
    var resourceSpecification = new McpServerFeatures.SyncResourceSpecification(systemInfoResource, (exchange, request) -> {
        try {
            var systemInfo = Map.of(...);
            String jsonContent = new ObjectMapper().writeValueAsString(systemInfo);
            return new McpSchema.ReadResourceResult(
                    List.of(new McpSchema.TextResourceContents(request.uri(), "application/json", jsonContent)));
        }
        catch (Exception e) {
            throw new RuntimeException("Failed to generate system info", e);
        }
    });
    return List.of(resourceSpecification);
}

提示管理 (Prompt Management)

为服务器向客户端公开提示模板提供标准化方法。

变更通知支持
模板版本控制
同步/异步提示规范之间的自动转换

通过 Spring Bean 自动配置提示规范：

@Bean
public List<McpServerFeatures.SyncPromptSpecification> myPrompts() {
    var prompt = new McpSchema.Prompt("greeting", "一个友好的问候提示",
        List.of(new McpSchema.PromptArgument("name", "要问候的名字", true)));

    var promptSpecification = new McpServerFeatures.SyncPromptSpecification(prompt, (exchange, getPromptRequest) -> {
        String nameArgument = (String) getPromptRequest.arguments().get("name");
        if (nameArgument == null) { nameArgument = "朋友"; }
        var userMessage = new PromptMessage(Role.USER, new TextContent("你好 " + nameArgument + "！今天我能为你做些什么？"));
        return new GetPromptResult("一条个性化的问候消息", List.of(userMessage));
    });
    return List.of(promptSpecification);
}

补全管理 (Completion Management)

为服务器向客户端公开补全能力提供标准化方法。

支持同步和异步补全规范

通过 Spring Bean 自动注册：

@Bean
public List<McpServerFeatures.SyncCompletionSpecification> myCompletions() {
    var completion = new McpServerFeatures.SyncCompletionSpecification(
        "code-completion",
        "提供代码补全建议",
        (exchange, request) -> {
            // 返回补全建议的实现
            return new McpSchema.CompletionResult(List.of(
                new McpSchema.Completion("suggestion1", "第一个建议"),
                new McpSchema.Completion("suggestion2", "第二个建议")
            ));
        }
    );
    return List.of(completion);
}

根变更消费者 (Root Change Consumers)

当根目录发生变更时，支持 listChanged 的客户端会发送根变更通知。

支持监控根变更
自动转换为用于反应式应用程序的异步消费者

通过 Spring Bean 可选注册

@Bean
public BiConsumer<McpSyncServerExchange, List<McpSchema.Root>> rootsChangeHandler() {
    return (exchange, roots) -> {
        logger.info("注册根资源: {}", roots);
    };
}

使用示例 (Usage Examples)

标准 STDIO 服务器配置

spring:
  ai:
    mcp:
      server:
        name: stdio-mcp-server
        version: 1.0.0
        type: SYNC

WebMVC 服务器配置

spring:
  ai:
    mcp:
      server:
        name: webmvc-mcp-server
        version: 1.0.0
        type: SYNC
        instructions: "此服务器提供天气信息工具和资源"
        sse-message-endpoint: /mcp/messages
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true

WebFlux 服务器配置

spring:
  ai:
    mcp:
      server:
        name: webflux-mcp-server
        version: 1.0.0
        type: ASYNC  # 推荐用于反应式应用程序
        instructions: "此反应式服务器提供天气信息工具和资源"
        sse-message-endpoint: /mcp/messages
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true

创建带有 MCP 服务器的 Spring Boot 应用程序

@Service
public class WeatherService {

    @Tool(description = "按城市名称获取天气信息")
    public String getWeather(String cityName) {
        // 实现
    }
}

@SpringBootApplication
public class McpServerApplication {

    private static final Logger logger = LoggerFactory.getLogger(McpServerApplication.class);

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

    @Bean
    public ToolCallbackProvider weatherTools(WeatherService weatherService) {
        return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
    }
}

自动配置将自动将工具回调注册为 MCP 工具。您可以有多个生成 ToolCallbacks 的 bean。自动配置会将它们合并。

示例应用程序 (Example Applications)

天气服务器 (WebFlux) - 带有 WebFlux 传输的 Spring AI MCP 服务器启动器。
天气服务器 (STDIO) - 带有 STDIO 传输的 Spring AI MCP 服务器启动器。
天气服务器手动配置 - 不使用自动配置而是使用 Java SDK 手动配置服务器的 Spring AI MCP 服务器启动器。

其他资源 (Additional Resources)

[Spring AI 文档](Spring AI Documentation)
[模型上下文协议规范](Model Context Protocol Specification)
[Spring Boot 自动配置](Spring Boot Auto-configuration)

目录CONTENT

SpringAI-MCP Server Boot Starter