MCP 註解

Spring AI MCP 註解模組為模型上下文協議 (MCP) 伺服器和客戶端在 Java 中提供了基於註解的方法處理。它透過使用 Java 註解的清晰、宣告式方法，簡化了 MCP 伺服器方法和客戶端處理程式的建立和註冊。

 The MCP Annotations enable developers to create and register MCP operation handlers using declarative annotations.
This approach simplifies implementing MCP server and client functionality by reducing boilerplate code and improving maintainability.

該庫構建在 MCP Java SDK 之上，提供了一個更高階的、基於註解的程式設計模型，用於實現 MCP 伺服器和客戶端。

架構

MCP 註解模組包括：

伺服器註解

對於 MCP 伺服器，提供了以下註解：

@McpTool - 實現 MCP 工具並自動生成 JSON 模式
@McpResource - 透過 URI 模板提供對資源的訪問
@McpPrompt - 生成提示訊息
@McpComplete - 提供自動補全功能

客戶端註解

對於 MCP 客戶端，提供了以下註解：

@McpLogging - 處理日誌訊息通知
@McpSampling - 處理取樣請求
@McpElicitation - 處理用於收集額外資訊的啟發式請求
@McpProgress - 處理長時間執行操作期間的進度通知
@McpToolListChanged - 處理工具列表更改通知
@McpResourceListChanged - 處理資源列表更改通知
@McpPromptListChanged - 處理提示列表更改通知

特殊引數和註解

McpSyncRequestContext - 用於同步操作的特殊引數型別，提供一個統一介面來訪問 MCP 請求上下文，包括原始請求、伺服器交換（用於有狀態操作）、傳輸上下文（用於無狀態操作），以及用於日誌記錄、進度、取樣和啟發式方法的便捷方法。此引數會自動注入並排除在 JSON 模式生成之外。支援 Complete、Prompt、Resource 和 Tool 方法。
McpAsyncRequestContext - 用於非同步操作的特殊引數型別，提供與 McpSyncRequestContext 相同的統一介面，但返回型別為響應式（基於 Mono）。此引數會自動注入並排除在 JSON 模式生成之外。支援 Complete、Prompt、Resource 和 Tool 方法。
McpTransportContext - 用於無狀態操作的特殊引數型別，提供對傳輸級別上下文的輕量級訪問，無需完整的伺服器交換功能。此引數會自動注入並排除在 JSON 模式生成之外。
@McpProgressToken - 標記一個方法引數以接收來自請求的進度令牌。此引數會自動注入並排除在生成的 JSON 模式之外。注意：當使用 McpSyncRequestContext 或 McpAsyncRequestContext 時，可以透過 ctx.request().progressToken() 訪問進度令牌，而不是使用此註解。
McpMeta - 特殊引數型別，提供對 MCP 請求、通知和結果中元資料的訪問。此引數會自動注入並排除在引數計數限制和 JSON 模式生成之外。注意：當使用 McpSyncRequestContext 或 McpAsyncRequestContext 時，可以透過 ctx.requestMeta() 獲取元資料。

入門

依賴關係

將 MCP 註解依賴項新增到您的專案

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-annotations</artifactId>
</dependency>

當您使用任何 MCP Boot Starters 時，MCP 註解會自動包含在內

spring-ai-starter-mcp-client
spring-ai-starter-mcp-client-webflux
spring-ai-starter-mcp-server
spring-ai-starter-mcp-server-webflux
spring-ai-starter-mcp-server-webmvc

配置

使用 MCP Boot Starters 時，註解掃描預設啟用。您可以使用以下屬性配置掃描行為：

客戶端註解掃描器

spring:
  ai:
    mcp:
      client:
        annotation-scanner:
          enabled: true  # Enable/disable annotation scanning

伺服器註解掃描器

spring:
  ai:
    mcp:
      server:
        annotation-scanner:
          enabled: true  # Enable/disable annotation scanning

快速示例

這是一個使用 MCP 註解建立計算器工具的簡單示例

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

    @McpTool(name = "multiply", description = "Multiply two numbers")
    public double multiply(
            @McpToolParam(description = "First number", required = true) double x,
            @McpToolParam(description = "Second number", required = true) double y) {
        return x * y;
    }
}

以及一個用於日誌記錄的簡單客戶端處理程式

@Component
public class LoggingHandler {

    @McpLogging(clients = "my-server")
    public void handleLoggingMessage(LoggingMessageNotification notification) {
        System.out.println("Received log: " + notification.level() +
                          " - " + notification.data());
    }
}

透過 Spring Boot 自動配置，這些帶註解的 Bean 會自動檢測並註冊到 MCP 伺服器或客戶端。

文件

客戶端註解 - 客戶端註解的詳細指南
伺服器註解 - 伺服器端註解的詳細指南
特殊引數 - 特殊引數型別的指南
示例 - 綜合示例和用例