從源碼看MCP Java SDK，這里面究竟定義了啥樣的協(xié)議

作者：demo123567 2025-03-12 00:45:25

這個(gè)協(xié)議設(shè)計(jì)遵循了 JSON-RPC 2.0 規(guī)范，并在此基礎(chǔ)上定義了特定的方法和數(shù)據(jù)結(jié)構(gòu)，主要包括：基礎(chǔ)通信協(xié)議 (初始化、心跳)工具管理 (發(fā)現(xiàn)、調(diào)用)資源管理 (列表、讀取、訂閱)提示模板管理 (列表、獲取)日志系統(tǒng) (級(jí)別設(shè)置、消息通知)變更通知機(jī)制 (工具、資源、提示模板的變更通知)。

整體架構(gòu)

MCP SDK 采用分層架構(gòu),主要分為以下幾層:

1. 核心規(guī)范層 (spec 包)

io.modelcontextprotocol.spec
├── McpSchema.java          // 協(xié)議數(shù)據(jù)模型定義
├── McpSession.java         // 會(huì)話接口定義  
├── McpTransport.java       // 傳輸層抽象接口
├── ClientMcpTransport.java // 客戶端傳輸接口
├── ServerMcpTransport.java // 服務(wù)端傳輸接口
├── DefaultMcpSession.java  // 默認(rèn)會(huì)話實(shí)現(xiàn)
└── McpError.java          // 錯(cuò)誤處理

2. 客戶端實(shí)現(xiàn)層 (client 包)

io.modelcontextprotocol.client
├── McpClient.java         // 客戶端工廠類
├── McpAsyncClient.java    // 異步客戶端實(shí)現(xiàn)
├── McpSyncClient.java     // 同步客戶端實(shí)現(xiàn)
└── McpClientFeatures.java // 客戶端功能配置

3. 服務(wù)端實(shí)現(xiàn)層 (server 包)

io.modelcontextprotocol.server
├── McpServer.java         // 服務(wù)端工廠類
├── McpAsyncServer.java    // 異步服務(wù)端實(shí)現(xiàn)
├── McpSyncServer.java     // 同步服務(wù)端實(shí)現(xiàn)
└── McpServerFeatures.java // 服務(wù)端功能配置

4. 傳輸實(shí)現(xiàn)層 (transport 包)

io.modelcontextprotocol.client.transport
├── StdioClientTransport.java        // 標(biāo)準(zhǔn)輸入輸出傳輸
├── HttpClientSseClientTransport.java // HTTP SSE 客戶端傳輸
├── FlowSseClient.java               // SSE 流式客戶端
└── ServerParameters.java            // 服務(wù)器參數(shù)配置

io.modelcontextprotocol.server.transport
├── StdioServerTransport.java        // 標(biāo)準(zhǔn)輸入輸出傳輸
└── HttpServletSseServerTransport.java // HTTP SSE 服務(wù)端傳輸

主要特性

雙模式支持:

同步 API (McpSyncClient/McpSyncServer)
異步 API (McpAsyncClient/McpAsyncServer)

核心功能:

工具調(diào)用 (Tools)
資源訪問 (Resources)
提示模板 (Prompts)
日志系統(tǒng) (Logging)
根目錄管理 (Roots)
AI 采樣支持 (Sampling)

傳輸實(shí)現(xiàn):

標(biāo)準(zhǔn)輸入輸出 (Stdio)
HTTP SSE (Server-Sent Events)
WebFlux SSE
WebMVC SSE

設(shè)計(jì)模式:

工廠模式 (McpClient/McpServer)
構(gòu)建器模式 (各種 Builder)
裝飾器模式 (同步包裝異步)
觀察者模式 (事件通知)

關(guān)鍵交互流程

初始化流程:

Client/Server -> Transport -> Session -> 協(xié)議版本協(xié)商 -> 能力協(xié)商

消息處理流程:

請(qǐng)求/響應(yīng): 生成ID -> 序列化 -> 傳輸 -> 反序列化 -> 處理
通知: 序列化 -> 傳輸 -> 反序列化 -> 處理

資源管理流程:

發(fā)現(xiàn) -> URI模板解析 -> 訪問控制 -> 內(nèi)容獲取

這種分層架構(gòu)使得代碼結(jié)構(gòu)清晰,各層職責(zé)明確,同時(shí)提供了良好的擴(kuò)展性和可維護(hù)性。

讓我來分析一下 McpSchema.java 中定義的 MCP 協(xié)議內(nèi)容：

1. 協(xié)議基本信息

public static final String LATEST_PROTOCOL_VERSION = "2024-11-05";  // 最新協(xié)議版本
public static final String JSONRPC_VERSION = "2.0";                 // 使用 JSON-RPC 2.0

2. 協(xié)議方法定義

生命周期方法

// 生命周期相關(guān)
METHOD_INITIALIZE = "initialize"                    // 初始化
METHOD_NOTIFICATION_INITIALIZED = "notifications/initialized"  // 初始化完成通知
METHOD_PING = "ping"                               // 心跳檢測

工具相關(guān)方法

// 工具相關(guān)
METHOD_TOOLS_LIST = "tools/list"                   // 列出可用工具
METHOD_TOOLS_CALL = "tools/call"                   // 調(diào)用工具
METHOD_NOTIFICATION_TOOLS_LIST_CHANGED = "notifications/tools/list_changed"  // 工具列表變更通知

資源相關(guān)方法

// 資源相關(guān)
METHOD_RESOURCES_LIST = "resources/list"           // 列出資源
METHOD_RESOURCES_READ = "resources/read"           // 讀取資源
METHOD_RESOURCES_TEMPLATES_LIST = "resources/templates/list"  // 列出資源模板
METHOD_RESOURCES_SUBSCRIBE = "resources/subscribe"    // 訂閱資源
METHOD_RESOURCES_UNSUBSCRIBE = "resources/unsubscribe"  // 取消訂閱
METHOD_NOTIFICATION_RESOURCES_LIST_CHANGED = "notifications/resources/list_changed"  // 資源列表變更通知

Prompt 相關(guān)方法

// Prompt相關(guān)
METHOD_PROMPT_LIST = "prompts/list"                // 列出提示模板
METHOD_PROMPT_GET = "prompts/get"                  // 獲取提示模板
METHOD_NOTIFICATION_PROMPTS_LIST_CHANGED = "notifications/prompts/list_changed"  // 提示模板列表變更通知

日志相關(guān)方法

// 日志相關(guān)
METHOD_LOGGING_SET_LEVEL = "logging/setLevel"      // 設(shè)置日志級(jí)別
METHOD_NOTIFICATION_MESSAGE = "notifications/message"  // 日志消息通知

3. 主要數(shù)據(jù)結(jié)構(gòu)

客戶端能力

public record ClientCapabilities(
    Experimental experimental,        // 實(shí)驗(yàn)性功能
    RootCapabilities roots,          // 根目錄能力
    Sampling sampling                // 采樣能力
)

服務(wù)器能力

public record ServerCapabilities(
    Experimental experimental,       // 實(shí)驗(yàn)性功能
    LoggingCapabilities logging,     // 日志能力
    PromptCapabilities prompts,      // 提示模板能力
    ResourceCapabilities resources,  // 資源能力
    ToolCapabilities tools          // 工具能力
)

內(nèi)容類型

sealed interface Content {
    TextContent      // 文本內(nèi)容
    ImageContent     // 圖片內(nèi)容
    EmbeddedResource // 嵌入資源
}

根目錄定義

public record Root(
    String uri,   // 根目錄URI (必須以 file:// 開頭)
    String name   // 根目錄名稱(可選)
)

4. 消息格式

JSON-RPC 消息

// 請(qǐng)求消息
public record JSONRPCRequest(
    String jsonrpc,    // JSON-RPC 版本
    String method,     // 方法名
    String id,        // 請(qǐng)求ID
    Object params     // 參數(shù)
)

// 響應(yīng)消息
public record JSONRPCResponse(
    String jsonrpc,    // JSON-RPC 版本
    String id,        // 請(qǐng)求ID
    Object result,    // 響應(yīng)結(jié)果
    JSONRPCError error // 錯(cuò)誤信息
)

// 通知消息
public record JSONRPCNotification(
    String jsonrpc,    // JSON-RPC 版本
    String method,     // 方法名
    Object params     // 參數(shù)
)

這個(gè)協(xié)議設(shè)計(jì)遵循了 JSON-RPC 2.0 規(guī)范，并在此基礎(chǔ)上定義了特定的方法和數(shù)據(jù)結(jié)構(gòu)，主要包括：