2025年6月9日

从源码看MCP Java SDK，这里面究竟定义了啥样的协议

分析 MCP (Model Context Protocol) Java SDK 的代码结构:

整体架构

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.0

2. 协议方法定义

生命周期方法

// 生命周期相关
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 模型能够通过标准化的接口与外部工具和资源进行交互。