Skip to main content

​
概述

MCP 服务器是模型上下文协议 (MCP) 架构中的基础组件，为客户端提供工具、资源和能力。它实现了协议的服务器端部分，负责：
  • 暴露客户端可以发现和执行的工具
  • 管理具有基于 URI 的访问模式的资源
  • 提供提示模板并处理提示请求
  • 支持与客户端的能力协商
  • 实现服务器端协议操作
  • 管理并发客户端连接
  • 提供结构化日志记录和通知
服务器支持同步和异步 API，允许在不同的应用程序上下文中灵活集成。
  • 同步 API
  • 异步 API
// 创建具有自定义配置的服务器
McpSyncServer syncServer = McpServer.sync(transport)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(true)     // 启用资源支持
        .tools(true)         // 启用工具支持
        .prompts(true)       // 启用提示支持
        .logging()           // 启用日志支持
        .build())
    .build();

// 注册工具、资源和提示
syncServer.addTool(syncToolRegistration);
syncServer.addResource(syncResourceRegistration);
syncServer.addPrompt(syncPromptRegistration);

// 发送日志通知
syncServer.loggingNotification(LoggingMessageNotification.builder()
    .level(LoggingLevel.INFO)
    .logger("custom-logger")
    .data("服务器已初始化")
    .build());

// 完成后关闭服务器
syncServer.close();

​
服务器传输

MCP SDK 中的传输层负责处理客户端和服务器之间的通信。它提供不同的实现以支持各种通信协议和模式。SDK 包含几个内置的传输实现：
  • 标准输入输出
  • SSE (WebFlux)
  • SSE (WebMvc)
  • SSE (Servlet)
创建基于进程内的传输：
StdioServerTransport transport = new StdioServerTransport(new ObjectMapper());
通过标准输入/输出流提供双向 JSON-RPC 消息处理，具有非阻塞消息处理、序列化/反序列化和优雅关闭支持。主要特点：
  • 通过 stdin/stdout 的双向通信
  • 基于进程的集成支持
  • 简单的设置和配置
  • 轻量级实现

​
服务器能力

服务器可以配置各种能力： 
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("自定义日志消息")
    .build());
客户端可以通过 mcpClient.setLoggingLevel(level) 请求控制它们接收的最低日志级别。低于设置级别的消息将被过滤掉。 支持的日志级别（按严重程度递增排序）：DEBUG (0)、INFO (1)、NOTICE (2)、WARNING (3)、ERROR (4)、CRITICAL (5)、ALERT (6)、EMERGENCY (7)

​
工具注册

  • 同步
  • 异步
// 同步工具注册
var syncToolRegistration = new McpServerFeatures.SyncToolRegistration(
    new Tool("calculator", "基础计算器", Map.of(
        "operation", "string",
        "a", "number",
        "b", "number"
    )),
    arguments -> {
        // 工具实现
        return new CallToolResult(result, false);
    }
);

​
资源注册

  • 同步
  • 异步
// 同步资源注册
var syncResourceRegistration = new McpServerFeatures.SyncResourceRegistration(
    new Resource("custom://resource", "名称", "描述", "mime-type", null),
    request -> {
        // 资源读取实现
        return new ReadResourceResult(contents);
    }
);

​
提示注册

  • 同步
  • 异步
// 同步提示注册
var syncPromptRegistration = new McpServerFeatures.SyncPromptRegistration(
    new Prompt("greeting", "描述", List.of(
        new PromptArgument("name", "描述", true)
    )),
    request -> {
        // 提示实现
        return new GetPromptResult(description, messages);
    }
);

​
错误处理

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