從源碼看MCP Java SDK，這里面究竟定義了啥樣的協議
作者：demo123567
這個協議設計遵循了 JSON-RPC 2.0 規范，并在此基礎上定義了特定的方法和數據結構，主要包括：基礎通信協議 (初始化、心跳)工具管理 (發現、調用)資源管理 (列表、讀取、訂閱)提示模板管理 (列表、獲取)日志系統 (級別設置、消息通知)變更通知機制 (工具、資源、提示模板的變更通知)。
整體架構
MCP SDK 采用分層架構,主要分為以下幾層:
1. 核心規范層 (spec 包)
io.modelcontextprotocol.spec
├── McpSchema.java // 協議數據模型定義
├── McpSession.java // 會話接口定義
├── McpTransport.java // 傳輸層抽象接口
├── ClientMcpTransport.java // 客戶端傳輸接口
├── ServerMcpTransport.java // 服務端傳輸接口
├── DefaultMcpSession.java // 默認會話實現
└── McpError.java // 錯誤處理2. 客戶端實現層 (client 包)
io.modelcontextprotocol.client
├── McpClient.java // 客戶端工廠類
├── McpAsyncClient.java // 異步客戶端實現
├── McpSyncClient.java // 同步客戶端實現
└── McpClientFeatures.java // 客戶端功能配置3. 服務端實現層 (server 包)
io.modelcontextprotocol.server
├── McpServer.java // 服務端工廠類
├── McpAsyncServer.java // 異步服務端實現
├── McpSyncServer.java // 同步服務端實現
└── McpServerFeatures.java // 服務端功能配置4. 傳輸實現層 (transport 包)
io.modelcontextprotocol.client.transport
├── StdioClientTransport.java // 標準輸入輸出傳輸
├── HttpClientSseClientTransport.java // HTTP SSE 客戶端傳輸
├── FlowSseClient.java // SSE 流式客戶端
└── ServerParameters.java // 服務器參數配置
io.modelcontextprotocol.server.transport
├── StdioServerTransport.java // 標準輸入輸出傳輸
└── HttpServletSseServerTransport.java // HTTP SSE 服務端傳輸主要特性
- 雙模式支持:
- 同步 API (McpSyncClient/McpSyncServer)
- 異步 API (McpAsyncClient/McpAsyncServer)
- 核心功能:
工具調用 (Tools)
資源訪問 (Resources)
提示模板 (Prompts)
日志系統 (Logging)
根目錄管理 (Roots)
AI 采樣支持 (Sampling)
傳輸實現:
標準輸入輸出 (Stdio)
HTTP SSE (Server-Sent Events)
WebFlux SSE
WebMVC SSE
設計模式:
工廠模式 (McpClient/McpServer)
構建器模式 (各種 Builder)
裝飾器模式 (同步包裝異步)
觀察者模式 (事件通知)
關鍵交互流程
- 初始化流程:
Client/Server -> Transport -> Session -> 協議版本協商 -> 能力協商- 消息處理流程:
請求/響應: 生成ID -> 序列化 -> 傳輸 -> 反序列化 -> 處理
通知: 序列化 -> 傳輸 -> 反序列化 -> 處理資源管理流程:
發現 -> URI模板解析 -> 訪問控制 -> 內容獲取這種分層架構使得代碼結構清晰,各層職責明確,同時提供了良好的擴展性和可維護性。
讓我來分析一下 McpSchema.java 中定義的 MCP 協議內容：
1. 協議基本信息
public static final String LATEST_PROTOCOL_VERSION = "2024-11-05"; // 最新協議版本
public static final String JSONRPC_VERSION = "2.0"; // 使用 JSON-RPC 2.02. 協議方法定義
生命周期方法
// 生命周期相關
METHOD_INITIALIZE = "initialize" // 初始化
METHOD_NOTIFICATION_INITIALIZED = "notifications/initialized" // 初始化完成通知
METHOD_PING = "ping" // 心跳檢測工具相關方法
// 工具相關
METHOD_TOOLS_LIST = "tools/list" // 列出可用工具
METHOD_TOOLS_CALL = "tools/call" // 調用工具
METHOD_NOTIFICATION_TOOLS_LIST_CHANGED = "notifications/tools/list_changed" // 工具列表變更通知資源相關方法
// 資源相關
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 相關方法
// Prompt相關
METHOD_PROMPT_LIST = "prompts/list" // 列出提示模板
METHOD_PROMPT_GET = "prompts/get" // 獲取提示模板
METHOD_NOTIFICATION_PROMPTS_LIST_CHANGED = "notifications/prompts/list_changed" // 提示模板列表變更通知日志相關方法
// 日志相關
METHOD_LOGGING_SET_LEVEL = "logging/setLevel" // 設置日志級別
METHOD_NOTIFICATION_MESSAGE = "notifications/message" // 日志消息通知3. 主要數據結構
客戶端能力
public record ClientCapabilities(
Experimental experimental, // 實驗性功能
RootCapabilities roots, // 根目錄能力
Sampling sampling // 采樣能力
)服務器能力
public record ServerCapabilities(
Experimental experimental, // 實驗性功能
LoggingCapabilities logging, // 日志能力
PromptCapabilities prompts, // 提示模板能力
ResourceCapabilities resources, // 資源能力
ToolCapabilities tools // 工具能力
)內容類型
sealed interface Content {
TextContent // 文本內容
ImageContent // 圖片內容
EmbeddedResource // 嵌入資源
}根目錄定義
public record Root(
String uri, // 根目錄URI (必須以 file:// 開頭)
String name // 根目錄名稱(可選)
)4. 消息格式
JSON-RPC 消息
// 請求消息
public record JSONRPCRequest(
String jsonrpc, // JSON-RPC 版本
String method, // 方法名
String id, // 請求ID
Object params // 參數
)
// 響應消息
public record JSONRPCResponse(
String jsonrpc, // JSON-RPC 版本
String id, // 請求ID
Object result, // 響應結果
JSONRPCError error // 錯誤信息
)
// 通知消息
public record JSONRPCNotification(
String jsonrpc, // JSON-RPC 版本
String method, // 方法名
Object params // 參數
)這個協議設計遵循了 JSON-RPC 2.0 規范，并在此基礎上定義了特定的方法和數據結構，主要包括：
- 基礎通信協議 (初始化、心跳)
- 工具管理 (發現、調用)
- 資源管理 (列表、讀取、訂閱)
- 提示模板管理 (列表、獲取)
- 日志系統 (級別設置、消息通知)
- 變更通知機制 (工具、資源、提示模板的變更通知)
這種設計使得 AI 模型能夠通過標準化的接口與外部工具和資源進行交互。
責任編輯：武曉燕
來源：
海燕技術棧
