> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpcn.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 服务器

> 学习如何实现和配置模型上下文协议 (MCP) 服务器

## 概述

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

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

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

<Tabs>
  <Tab title="同步 API">
    ```java theme={null}
    // 使用自定义配置创建服务器
    McpSyncServer syncServer = McpServer.sync(transport)
        .serverInfo("my-server", "1.0.0")
        .capabilities(ServerCapabilities.builder()
            .resources(true)     // 启用资源支持
            .tools(true)         // 启用工具支持
            .prompts(true)       // 启用提示支持
            .logging()           // 启用日志支持
            .build())
        .build();

    // 初始化服务器
    syncServer.initialize();

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

    // 发送日志通知
    syncServer.loggingNotification(LoggingMessageNotification.builder()
        .level(LoggingLevel.INFO)
        .logger("custom-logger")
        .data("Server initialized")
        .build());

    // 完成后关闭服务器
    syncServer.close();
    ```
  </Tab>

  <Tab title="异步 API">
    ```java theme={null}
    // 使用自定义配置创建异步服务器
    McpAsyncServer asyncServer = McpServer.async(transport)
        .serverInfo("my-server", "1.0.0")
        .capabilities(ServerCapabilities.builder()
            .resources(true)     // 启用资源支持
            .tools(true)         // 启用工具支持
            .prompts(true)       // 启用提示支持
            .logging()           // 启用日志支持
            .build())
        .build();

    // 初始化服务器
    asyncServer.initialize()
        .doOnSuccess(v -> logger.info("Server initialized"))
        .subscribe();

    // 注册工具、资源和提示
    asyncServer.addTool(asyncToolRegistration)
        .doOnSuccess(v -> logger.info("Tool registered"))
        .subscribe();

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

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

    // 发送日志通知
    asyncServer.loggingNotification(LoggingMessageNotification.builder()
        .level(LoggingLevel.INFO)
        .logger("custom-logger")
        .data("Server initialized")
        .build());

    // 完成后关闭服务器
    asyncServer.close()
        .doOnSuccess(v -> logger.info("Server closed"))
        .subscribe();
    ```
  </Tab>
</Tabs>

## 服务器传输

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

<Tabs>
  <Tab title="STDIO">
    <>
      创建基于进程的传输：

      ```java theme={null}
      StdioServerTransport transport = new StdioServerTransport(new ObjectMapper());
      ```

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

      关键特性：

      <ul>
        <li>通过 stdin/stdout 的双向通信</li>
        <li>基于进程的集成支持</li>
        <li>简单的设置和配置</li>
        <li>轻量级实现</li>
      </ul>
    </>
  </Tab>

  <Tab title="SSE (WebFlux)">
    <>
      <p>创建基于 WebFlux 的 SSE 服务器传输。<br />需要 <code>mcp-spring-webflux</code> 依赖。</p>

      ```java theme={null}
      @Configuration
      class McpConfig {
          @Bean
          WebFluxSseServerTransport webFluxSseServerTransport(ObjectMapper mapper) {
              return new WebFluxSseServerTransport(mapper, "/mcp/message");
          }

          @Bean
          RouterFunction<?> mcpRouterFunction(WebFluxSseServerTransport transport) {
              return transport.getRouterFunction();
          }
      }
      ```

      <p>实现 MCP HTTP 与 SSE 传输规范，提供：</p>

      <ul>
        <li>使用 WebFlux 的反应式 HTTP 流</li>
        <li>通过 SSE 端点的并发客户端连接</li>
        <li>消息路由和会话管理</li>
        <li>优雅关闭能力</li>
      </ul>
    </>
  </Tab>

  <Tab title="SSE (WebMvc)">
    <>
      <p>创建基于 WebMvc 的 SSE 服务器传输。<br />需要 <code>mcp-spring-webmvc</code> 依赖。</p>

      ```java theme={null}
      @Configuration
      @EnableWebMvc
      class McpConfig {
          @Bean
          WebMvcSseServerTransport webMvcSseServerTransport(ObjectMapper mapper) {
              return new WebMvcSseServerTransport(mapper, "/mcp/message");
          }

          @Bean
          RouterFunction<ServerResponse> mcpRouterFunction(WebMvcSseServerTransport transport) {
              return transport.getRouterFunction();
          }
      }
      ```

      <p>实现 MCP HTTP 与 SSE 传输规范，提供：</p>

      <ul>
        <li>服务器端事件流</li>
        <li>与 Spring WebMVC 的集成</li>
        <li>支持传统 Web 应用程序</li>
        <li>同步操作处理</li>
      </ul>
    </>
  </Tab>

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

      ```java theme={null}
      @Configuration
      @EnableWebMvc
      public class McpServerConfig implements WebMvcConfigurer {

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

          @Bean
          public ServletRegistrationBean customServletBean(HttpServletSseServerTransport servlet) {
              return new ServletRegistrationBean(servlet);
          }
      }
      ```

      <p>
        实现 MCP HTTP 与 SSE 传输规范，使用传统的 Servlet API，提供：
      </p>

      <ul>
        <li>异步消息处理使用 Servlet 6.0 异步支持</li>
        <li>会话管理多个客户端连接</li>

        <li>
          两种类型的端点：

          <ul>
            <li>SSE 端点 (<code>/sse</code>) 服务器到客户端事件</li>
            <li>消息端点 (可配置) 客户端到服务器请求</li>
          </ul>
        </li>

        <li>错误处理和响应格式化</li>
        <li>优雅关闭支持</li>
      </ul>
    </>
  </Tab>
</Tabs>

## 服务器能力

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

```java theme={null}
var capabilities = ServerCapabilities.builder()
    .resources(false, true)  // 资源支持与列表更改通知
    .tools(true)            // 工具支持与列表更改通知
    .prompts(true)          // 提示支持与列表更改通知
    .logging()              // 启用日志支持 (默认启用，日志级别为 INFO)
    .build();
```

### 日志支持

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

```java theme={null}
// 发送日志消息给客户端
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)

### 工具注册

<Tabs>
  <Tab title="同步">
    ```java theme={null}
    // 同步工具注册
    var syncToolRegistration = new McpServerFeatures.SyncToolRegistration(
        new Tool("计算器", "基本计算器", Map.of(
            "operation", "string",
            "a", "number",
            "b", "number"
        )),
        arguments -> {
            // 工具实现
            return new CallToolResult(result, false);
        }
    );
    ```
  </Tab>

  <Tab title="异步">
    ```java theme={null}
    // 异步工具注册
    var asyncToolRegistration = new McpServerFeatures.AsyncToolRegistration(
        new Tool("计算器", "基本计算器", Map.of(
            "operation", "string",
            "a", "number",
            "b", "number"
        )),
        arguments -> {
            // 工具实现
            return Mono.just(new CallToolResult(result, false));
        }
    );
    ```
  </Tab>
</Tabs>

### 资源注册

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

  <Tab title="异步">
    ```java theme={null}
    // 异步资源注册
    var asyncResourceRegistration = new McpServerFeatures.AsyncResourceRegistration(
        new Resource("custom://resource", "名称", "描述", "mime-type", null),
        request -> {
            // 资源读取实现
            return Mono.just(new ReadResourceResult(contents));
        }
    );
    ```
  </Tab>
</Tabs>

### 提示注册

<Tabs>
  <Tab title="同步">
    ```java theme={null}
    // 同步提示注册
    var syncPromptRegistration = new McpServerFeatures.SyncPromptRegistration(
        new Prompt("问候", "描述", List.of(
            new PromptArgument("名称", "描述", true)
        )),
        request -> {
            // 提示实现
            return new GetPromptResult(description, messages);
        }
    );
    ```
  </Tab>

  <Tab title="异步">
    ```java theme={null}
    // 异步提示注册
    var asyncPromptRegistration = new McpServerFeatures.AsyncPromptRegistration(
        new Prompt("问候", "描述", List.of(
            new PromptArgument("名称", "描述", true)
        )),
        request -> {
            // 提示实现
            return Mono.just(new GetPromptResult(description, messages));
        }
    );
    ```
  </Tab>
</Tabs>

## 错误处理

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