Model Context Protocol - LLM 上下文标准化协议

0.8.x版本中的重大变更 ⚠️

注意： 0.8.x版本引入了几个重大变更，包括新的基于会话的架构。如果您正在从0.7.0版本升级，请参考迁移指南获取详细说明。

概述

MCP服务器是模型上下文协议(MCP)架构中的一个基础组件，为客户端提供工具、资源和功能。它实现了协议的服务器端，负责：

暴露客户端可以发现和执行的工具
使用基于URI的访问模式管理资源
提供提示模板并处理提示请求
支持与客户端的能力协商
实现服务器端协议操作
管理并发客户端连接
提供结构化日志记录和通知

Spring-AI MCP Server集成扩展了MCP Java SDK，为Spring Boot应用程序提供MCP服务器功能的自动配置。

服务器同时支持同步和异步API，允许在不同的应用场景中灵活集成。

// Create a server with custom configuration
McpSyncServer syncServer = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(true)     // Enable resource support
        .tools(true)         // Enable tool support
        .prompts(true)       // Enable prompt support
        .logging()           // Enable logging support
        .build())
    .build();

// Register tools, resources, and prompts
syncServer.addTool(syncToolSpecification);
syncServer.addResource(syncResourceSpecification);
syncServer.addPrompt(syncPromptSpecification);

// Send logging notifications
syncServer.loggingNotification(LoggingMessageNotification.builder()
    .level(LoggingLevel.INFO)
    .logger("custom-logger")
    .data("Server initialized")
    .build());

// Close the server when done
syncServer.close();

// Create a server with custom configuration
McpSyncServer syncServer = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(true)     // Enable resource support
        .tools(true)         // Enable tool support
        .prompts(true)       // Enable prompt support
        .logging()           // Enable logging support
        .build())
    .build();

// Register tools, resources, and prompts
syncServer.addTool(syncToolSpecification);
syncServer.addResource(syncResourceSpecification);
syncServer.addPrompt(syncPromptSpecification);

// Send logging notifications
syncServer.loggingNotification(LoggingMessageNotification.builder()
    .level(LoggingLevel.INFO)
    .logger("custom-logger")
    .data("Server initialized")
    .build());

// Close the server when done
syncServer.close();

// Create an async server with custom configuration
McpAsyncServer asyncServer = McpServer.async(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(true)     // Enable resource support
        .tools(true)         // Enable tool support
        .prompts(true)       // Enable prompt support
        .logging()           // Enable logging support
        .build())
    .build();

// Register tools, resources, and prompts
asyncServer.addTool(asyncToolSpecification)
    .doOnSuccess(v -> logger.info("Tool registered"))
    .subscribe();

asyncServer.addResource(asyncResourceSpecification)
    .doOnSuccess(v -> logger.info("Resource registered"))
    .subscribe();

asyncServer.addPrompt(asyncPromptSpecification)
    .doOnSuccess(v -> logger.info("Prompt registered"))
    .subscribe();

// Send logging notifications
asyncServer.loggingNotification(LoggingMessageNotification.builder()
    .level(LoggingLevel.INFO)
    .logger("custom-logger")
    .data("Server initialized")
    .build());

// Close the server when done
asyncServer.close()
    .doOnSuccess(v -> logger.info("Server closed"))
    .subscribe();

服务器传输提供者

MCP SDK中的传输层负责处理客户端和服务器之间的通信。它提供不同的实现以支持各种通信协议和模式。 SDK包含几个内置的传输提供者实现：

创建基于进程的传输：

StdioServerTransportProvider transportProvider = new StdioServerTransportProvider(new ObjectMapper());

提供通过标准输入/输出流的双向JSON-RPC消息处理，具有非阻塞消息处理、序列化/反序列化和优雅关闭支持。

主要特性：

通过stdin/stdout的双向通信
进程基础的集成支持
简单的设置和配置
轻量级实现

创建基于进程的传输：

StdioServerTransportProvider transportProvider = new StdioServerTransportProvider(new ObjectMapper());

提供通过标准输入/输出流的双向JSON-RPC消息处理，具有非阻塞消息处理、序列化/反序列化和优雅关闭支持。

主要特性：

通过stdin/stdout的双向通信
进程基础的集成支持
简单的设置和配置
轻量级实现

创建基于WebFlux的SSE服务器传输。
需要 mcp-spring-webflux 依赖。

@Configuration
class McpConfig {
    @Bean
    WebFluxSseServerTransportProvider webFluxSseServerTransportProvider(ObjectMapper mapper) {
        return new WebFluxSseServerTransportProvider(mapper, "/mcp/message");
    }

    @Bean
    RouterFunction<?> mcpRouterFunction(WebFluxSseServerTransportProvider transportProvider) {
        return transportProvider.getRouterFunction();
    }
}

实现MCP HTTP与SSE传输规范，提供：

使用WebFlux的响应式HTTP流
通过SSE端点的并发客户端连接
消息路由和会话管理
优雅关闭功能

创建基于WebMvc的SSE服务器传输。
需要 mcp-spring-webmvc 依赖。

@Configuration
@EnableWebMvc
class McpConfig {
    @Bean
    WebMvcSseServerTransportProvider webMvcSseServerTransportProvider(ObjectMapper mapper) {
        return new WebMvcSseServerTransportProvider(mapper, "/mcp/message");
    }

    @Bean
    RouterFunction<ServerResponse> mcpRouterFunction(WebMvcSseServerTransportProvider transportProvider) {
        return transportProvider.getRouterFunction();
    }
}

实现MCP HTTP与SSE传输规范，提供：

服务器端事件流
与Spring WebMVC集成
支持传统Web应用程序
同步操作处理

创建基于Servlet的SSE服务器传输。它包含在核心 mcp 模块中。
HttpServletSseServerTransport 可以与任何Servlet容器一起使用。
要在Spring Web应用程序中使用它，您可以将其注册为Servlet bean：

@Configuration
@EnableWebMvc
public class McpServerConfig implements WebMvcConfigurer {

    @Bean
    public HttpServletSseServerTransportProvider servletSseServerTransportProvider() {
        return new HttpServletSseServerTransportProvider(new ObjectMapper(), "/mcp/message");
    }

    @Bean
    public ServletRegistrationBean customServletBean(HttpServletSseServerTransportProvider transportProvider) {
        return new ServletRegistrationBean(transportProvider);
    }
}

使用传统Servlet API实现MCP HTTP与SSE传输规范，提供：

使用Servlet 6.0异步支持的异步消息处理
多客户端连接的会话管理
两种类型的端点：
- SSE端点（/sse）用于服务器到客户端的事件
- 消息端点（可配置）用于客户端到服务器的请求
错误处理和响应格式化
优雅关闭支持

服务器能力

服务器可以配置各种能力：

var capabilities = ServerCapabilities.builder()
    .resources(false, true)  // 资源支持，带列表变更通知
    .tools(true)            // 工具支持，带列表变更通知
    .prompts(true)          // 提示支持，带列表变更通知
    .logging()              // 启用日志支持（默认启用，日志级别为INFO）
    .build();

日志支持

服务器提供结构化日志功能，允许以不同的严重级别向客户端发送日志消息：

// 向客户端发送日志消息
server.loggingNotification(LoggingMessageNotification.builder()
    .level(LoggingLevel.INFO)
    .logger("custom-logger")
    .data("Custom log message")
    .build());

客户端可以通过 mcpClient.setLoggingLevel(level) 请求控制它们接收的最低日志级别。低于设置级别的消息将被过滤掉。支持的日志级别（按严重程度递增排序）：DEBUG (0)、INFO (1)、NOTICE (2)、WARNING (3)、ERROR (4)、CRITICAL (5)、ALERT (6)、EMERGENCY (7)

工具规范

模型上下文协议允许服务器暴露工具供语言模型调用。 Java SDK允许实现带有处理函数的工具规范。工具使AI模型能够执行计算、访问外部API、查询数据库和操作文件：

// 同步工具规范
var schema = """
            {
              "type" : "object",
              "id" : "urn:jsonschema:Operation",
              "properties" : {
                "operation" : {
                  "type" : "string"
                },
                "a" : {
                  "type" : "number"
                },
                "b" : {
                  "type" : "number"
                }
              }
            }
            """;
var syncToolSpecification = new McpServerFeatures.SyncToolSpecification(
    new Tool("calculator", "Basic calculator", schema),
    (exchange, arguments) -> {
        // 工具实现
        return new CallToolResult(result, false);
    }
);

// 同步工具规范
var schema = """
            {
              "type" : "object",
              "id" : "urn:jsonschema:Operation",
              "properties" : {
                "operation" : {
                  "type" : "string"
                },
                "a" : {
                  "type" : "number"
                },
                "b" : {
                  "type" : "number"
                }
              }
            }
            """;
var syncToolSpecification = new McpServerFeatures.SyncToolSpecification(
    new Tool("calculator", "Basic calculator", schema),
    (exchange, arguments) -> {
        // 工具实现
        return new CallToolResult(result, false);
    }
);

// 异步工具规范
var schema = """
            {
              "type" : "object",
              "id" : "urn:jsonschema:Operation",
              "properties" : {
                "operation" : {
                  "type" : "string"
                },
                "a" : {
                  "type" : "number"
                },
                "b" : {
                  "type" : "number"
                }
              }
            }
            """;
var asyncToolSpecification = new McpServerFeatures.AsyncToolSpecification(
    new Tool("calculator", "Basic calculator", schema),
    (exchange, arguments) -> {
        // 工具实现
        return Mono.just(new CallToolResult(result, false));
    }
);

工具规范包括带有名称、描述和参数模式的工具定义，后跟实现工具逻辑的调用处理程序。函数的第一个参数是用于客户端交互的McpAsyncServerExchange，第二个参数是工具参数的映射。

资源规范

资源及其处理函数的规范。资源通过暴露以下数据为AI模型提供上下文：文件内容、数据库记录、API响应、系统信息、应用程序状态。示例资源规范：

// 同步资源规范
var syncResourceSpecification = new McpServerFeatures.syncResourceSpecification(
    new Resource("custom://resource", "name", "description", "mime-type", null),
    (exchange, request) -> {
        // 资源读取实现
        return new ReadResourceResult(contents);
    }
);

// 同步资源规范
var syncResourceSpecification = new McpServerFeatures.syncResourceSpecification(
    new Resource("custom://resource", "name", "description", "mime-type", null),
    (exchange, request) -> {
        // 资源读取实现
        return new ReadResourceResult(contents);
    }
);

// 异步资源规范
var asyncResourceSpecification = new McpServerFeatures.asyncResourceSpecification(
    new Resource("custom://resource", "name", "description", "mime-type", null),
    (exchange, request) -> {
        // 资源读取实现
        return Mono.just(new ReadResourceResult(contents));
    }
);

资源规范由资源定义和资源读取处理程序组成。资源定义包括名称、描述和MIME类型。处理资源读取请求的函数的第一个参数是McpAsyncServerExchange，服务器可以通过它与连接的客户端交互。第二个参数是McpSchema.ReadResourceRequest。

提示规范

作为提示功能的一部分，MCP为服务器提供了向客户端暴露提示模板的标准化方式。提示规范是AI模型交互的结构化模板，支持一致的消息格式化、参数替换、上下文注入、响应格式化和指令模板化。

// 同步提示规范
var syncPromptSpecification = new McpServerFeatures.syncPromptSpecification(
    new Prompt("greeting", "description", List.of(
        new PromptArgument("name", "description", true)
    )),
    (exchange, request) -> {
        // 提示实现
        return new GetPromptResult(description, messages);
    }
);

// 同步提示规范
var syncPromptSpecification = new McpServerFeatures.syncPromptSpecification(
    new Prompt("greeting", "description", List.of(
        new PromptArgument("name", "description", true)
    )),
    (exchange, request) -> {
        // 提示实现
        return new GetPromptResult(description, messages);
    }
);

// 异步提示规范
var asyncPromptSpecification = new McpServerFeatures.asyncPromptSpecification(
    new Prompt("greeting", "description", List.of(
        new PromptArgument("name", "description", true)
    )),
    (exchange, request) -> {
        // 提示实现
        return Mono.just(new GetPromptResult(description, messages));
    }
);

提示定义包括名称（提示的标识符）、描述（提示的用途）和参数列表（用于模板化的参数）。处理函数处理请求并返回格式化的模板。第一个参数是用于客户端交互的McpAsyncServerExchange，第二个参数是GetPromptRequest实例。

从服务器使用采样

要使用采样功能，请连接到支持采样的客户端。不需要特殊的服务器配置，但在发出请求之前要验证客户端的采样支持。了解客户端采样支持。

一旦连接到兼容的客户端，服务器就可以请求语言模型生成：

// 创建服务器
McpSyncServer server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

// 定义使用采样的工具
var calculatorTool = new McpServerFeatures.SyncToolSpecification(
    new Tool("ai-calculator", "Performs calculations using AI", schema),
    (exchange, arguments) -> {
        // 检查客户端是否支持采样
        if (exchange.getClientCapabilities().sampling() == null) {
            return new CallToolResult("Client does not support AI capabilities", false);
        }
        
        // 创建采样请求
        McpSchema.CreateMessageRequest request = McpSchema.CreateMessageRequest.builder()
            .content(new McpSchema.TextContent("Calculate: " + arguments.get("expression")))
            .modelPreferences(McpSchema.ModelPreferences.builder()
                .hints(List.of(
                    McpSchema.ModelHint.of("claude-3-sonnet"),
                    McpSchema.ModelHint.of("claude")
                ))
                .intelligencePriority(0.8)  // 优先考虑智能性
                .speedPriority(0.5)         // 中等速度重要性
                .build())
            .systemPrompt("You are a helpful calculator assistant. Provide only the numerical answer.")
            .maxTokens(100)
            .build();
        
        // 向客户端请求采样
        McpSchema.CreateMessageResult result = exchange.createMessage(request);
        
        // 处理结果
        String answer = result.content().text();
        return new CallToolResult(answer, false);
    }
);

// 将工具添加到服务器
server.addTool(calculatorTool);

// 创建服务器
McpSyncServer server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

// 定义使用采样的工具
var calculatorTool = new McpServerFeatures.SyncToolSpecification(
    new Tool("ai-calculator", "Performs calculations using AI", schema),
    (exchange, arguments) -> {
        // 检查客户端是否支持采样
        if (exchange.getClientCapabilities().sampling() == null) {
            return new CallToolResult("Client does not support AI capabilities", false);
        }
        
        // 创建采样请求
        McpSchema.CreateMessageRequest request = McpSchema.CreateMessageRequest.builder()
            .content(new McpSchema.TextContent("Calculate: " + arguments.get("expression")))
            .modelPreferences(McpSchema.ModelPreferences.builder()
                .hints(List.of(
                    McpSchema.ModelHint.of("claude-3-sonnet"),
                    McpSchema.ModelHint.of("claude")
                ))
                .intelligencePriority(0.8)  // 优先考虑智能性
                .speedPriority(0.5)         // 中等速度重要性
                .build())
            .systemPrompt("You are a helpful calculator assistant. Provide only the numerical answer.")
            .maxTokens(100)
            .build();
        
        // 向客户端请求采样
        McpSchema.CreateMessageResult result = exchange.createMessage(request);
        
        // 处理结果
        String answer = result.content().text();
        return new CallToolResult(answer, false);
    }
);

// 将工具添加到服务器
server.addTool(calculatorTool);

// 创建服务器
McpAsyncServer server = McpServer.async(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

// 定义使用采样的工具
var calculatorTool = new McpServerFeatures.AsyncToolSpecification(
    new Tool("ai-calculator", "Performs calculations using AI", schema),
    (exchange, arguments) -> {
        // 检查客户端是否支持采样
        if (exchange.getClientCapabilities().sampling() == null) {
            return Mono.just(new CallToolResult("Client does not support AI capabilities", false));
        }
        
        // 创建采样请求
        McpSchema.CreateMessageRequest request = McpSchema.CreateMessageRequest.builder()
            .content(new McpSchema.TextContent("Calculate: " + arguments.get("expression")))
            .modelPreferences(McpSchema.ModelPreferences.builder()
                .hints(List.of(
                    McpSchema.ModelHint.of("claude-3-sonnet"),
                    McpSchema.ModelHint.of("claude")
                ))
                .intelligencePriority(0.8)  // 优先考虑智能性
                .speedPriority(0.5)         // 中等速度重要性
                .build())
            .systemPrompt("You are a helpful calculator assistant. Provide only the numerical answer.")
            .maxTokens(100)
            .build();
        
        // 向客户端请求采样
        return exchange.createMessage(request)
            .map(result -> {
                // 处理结果
                String answer = result.content().text();
                return new CallToolResult(answer, false);
            });
    }
);

// 将工具添加到服务器
server.addTool(calculatorTool)
    .subscribe();

CreateMessageRequest对象允许您指定：Content - 模型的输入文本或图像， Model Preferences - 模型选择的提示和优先级，System Prompt - 模型行为的指令，以及 Max Tokens - 生成响应的最大长度。

错误处理

SDK通过McpError类提供全面的错误处理，涵盖协议兼容性、传输通信、JSON-RPC消息传递、工具执行、资源管理、提示处理、超时和连接问题。这种统一的错误处理方法确保在同步和异步操作中都能一致可靠地管理错误。

Java

​0.8.x版本中的重大变更 ⚠️

​概述

​服务器传输提供者

​服务器能力

​日志支持

​工具规范

​资源规范

​提示规范

​从服务器使用采样

​错误处理

0.8.x版本中的重大变更 ⚠️

概述

服务器传输提供者

服务器能力

日志支持

工具规范

资源规范

提示规范

从服务器使用采样

错误处理