MCP Server Boot Starter

QWen Max 中英对照 MCP Server Boot Starters MCP Server Boot Starter

Model Context Protocol (MCP) 服务器 是通过标准化协议接口向 AI 应用程序暴露特定功能的程序。每个服务器都为其特定领域提供专注的功能。

Spring AI MCP Server Boot Starters 提供了自动配置功能，用于在 Spring Boot 应用程序中设置 MCP Servers。它们能够将 MCP 服务器功能与 Spring Boot 的自动配置系统无缝集成。

MCP 服务器启动器提供：

• 自动配置 MCP 服务器组件，包括工具、资源和提示

• 支持不同的 MCP 协议版本，包括 STDIO、SSE、Streamable-HTTP 和无状态服务器

• 支持同步和异步操作模式

• 多种传输层选项

• 灵活的工具、资源和提示定义

• 变更通知功能

• 基于注解的服务器开发，支持自动扫描和注册 Bean

MCP Server 启动器

MCP 服务器支持多种协议和传输机制。请使用专用的启动器以及正确的 spring.ai.mcp.server.protocol 属性来配置您的服务器：

STDIO

服务器类型	依赖项	属性
标准输入/输出 (STDIO)	spring-ai-starter-mcp-server	spring.ai.mcp.server.stdio=true

WebMVC

服务器类型	依赖项	属性
SSE WebMVC	spring-ai-starter-mcp-server-webmvc	spring.ai.mcp.server.protocol=SSE 或为空
Streamable-HTTP WebMVC	spring-ai-starter-mcp-server-webmvc	spring.ai.mcp.server.protocol=STREAMABLE
Stateless WebMVC	spring-ai-starter-mcp-server-webmvc	spring.ai.mcp.server.protocol=STATELESS

WebMVC (Reactive)

服务器类型	依赖项	属性
SSE WebFlux	spring-ai-starter-mcp-server-webflux	spring.ai.mcp.server.protocol=SSE 或为空
Streamable-HTTP WebFlux	spring-ai-starter-mcp-server-webflux	spring.ai.mcp.server.protocol=STREAMABLE
Stateless WebFlux	spring-ai-starter-mcp-server-webflux	spring.ai.mcp.server.protocol=STATELESS

服务器功能

根据服务器和传输类型的不同，MCP 服务器可以支持多种功能，例如：

• Tools - 允许服务器暴露可由语言模型调用的工具

• Resources - 为服务器提供一种标准化方式，向客户端暴露资源

• Prompts - 为服务器提供一种标准化方式，向客户端暴露提示模板

• Utility/Completions - 为服务器提供一种标准化方式，针对提示和资源 URI 提供参数自动补全建议

• Utility/Logging - 为服务器提供一种标准化方式，向客户端发送结构化日志消息

• Utility/Progress - 通过通知消息，为长时间运行的操作提供可选的进度跟踪

• Utility/Ping - 可选的健康检查机制，供服务器报告其状态

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

服务器协议

MCP 提供了多种协议类型，包括：

• STDIO - 进程内协议（例如，服务器运行在宿主应用程序内部）。通信通过标准输入和标准输出进行。要启用 STDIO，请设置 spring.ai.mcp.server.stdio=true。

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

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

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

Sync/Async Server API 选项

MCP Server API 支持命令式（即同步）和响应式（例如异步）编程模型。

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

注意： SYNC 服务器仅会注册带有同步 MCP 注解的方法。异步方法将被忽略。

• 异步服务器 - 异步服务器实现使用 McpAsyncServer，并针对非阻塞操作进行了优化。要启用此服务器类型，请在应用中配置 spring.ai.mcp.server.type=ASYNC。该服务器类型会自动设置支持 Project Reactor 的异步工具规范。

注意： ASYNC 服务器将仅注册带有异步 MCP 注解的方法。同步方法将被忽略。

MCP Server 注解

MCP Server Boot Starters 提供了对基于注解的服务器开发的全面支持，允许你使用声明式的 Java 注解来创建 MCP 服务器，而无需手动配置。

关键注解

• @McpTool - 将方法标记为 MCP 工具，并自动生成 JSON Schema

• @McpResource - 通过 URI 模板提供对资源的访问

• @McpPrompt - 为 AI 交互生成提示消息

• @McpComplete - 为提示提供自动补全功能

特殊参数

注解系统支持提供额外上下文的特殊参数类型：

• McpMeta - 访问 MCP 请求的元数据

• @McpProgressToken - 接收长时间运行操作的进度令牌

• McpSyncServerExchange/McpAsyncServerExchange - 用于高级操作的完整服务器上下文

• McpTransportContext - 用于无状态操作的轻量级上下文

• CallToolRequest - 支持灵活工具的动态 schema

简单示例

@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);
    }
}

自动配置

通过 Spring Boot 自动配置，带注解的 Bean 会自动被检测并注册：

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

自动配置将：

1. 扫描带有 MCP 注解的 Bean

2. 创建相应的规范

3. 将其注册到 MCP 服务器

4. 根据配置处理同步和异步实现

配置属性

配置服务器注解扫描器：

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

附加资源

• Server Annotations Reference - Server 注解完整指南

• Special Parameters - 高级参数注入

• Examples - 综合示例与使用场景

示例应用

• 天气服务器 (SSE WebFlux) - 使用 WebFlux 传输的 Spring AI MCP Server Boot Starter

• 天气服务器 (STDIO) - 使用 STDIO 传输的 Spring AI MCP Server Boot Starter

• 天气服务器手动配置 - 不使用自动配置，而是通过 Java SDK 手动配置服务器的 Spring AI MCP Server Boot Starter

• Streamable-HTTP WebFlux/WebMVC 示例 - TODO

• 无状态 WebFlux/WebMVC 示例 - TODO

附加资源

• MCP Server Annotations - 使用注解进行声明式服务器开发

• Special Parameters - 高级参数注入与上下文访问

• MCP Annotations Examples - 综合示例与使用场景

• Spring AI Documentation

• Model Context Protocol Specification

• Spring Boot Auto-configuration

章节总结

📄️ STDIO 与 SSE MCP 服务器

STDIO 和 SSE MCP 服务器支持多种传输机制，每种机制都有其专用的启动器。

📄️ Streamable-HTTP MCP 服务器

Streamable HTTP 传输协议使 MCP 服务器能够作为独立进程运行，通过 HTTP POST 和 GET 请求处理多个客户端连接，并可选择使用 Server-Sent Events (SSE) 流式传输来处理多个服务器消息。它取代了 SSE 传输协议。

📄️ 无状态可流式HTTP MCP服务器

无状态可流式HTTP MCP服务器专为简化部署而设计，其请求之间不维持会话状态。这类服务器是微服务架构和云原生部署的理想选择。