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

开发 前端
这个协议设计遵循了 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          // 错误处理
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.

2. 客户端实现层 (client 包)

io.modelcontextprotocol.client
├── McpClient.java         // 客户端工厂类
├── McpAsyncClient.java    // 异步客户端实现
├── McpSyncClient.java     // 同步客户端实现
└── McpClientFeatures.java // 客户端功能配置
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.

3. 服务端实现层 (server 包)

io.modelcontextprotocol.server
├── McpServer.java         // 服务端工厂类
├── McpAsyncServer.java    // 异步服务端实现
├── McpSyncServer.java     // 同步服务端实现
└── McpServerFeatures.java // 服务端功能配置
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.

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 服务端传输
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.

主要特性

  1. 双模式支持:
  • 同步 API (McpSyncClient/McpSyncServer)
  • 异步 API (McpAsyncClient/McpAsyncServer)
  1. 核心功能:
  • 工具调用 (Tools)

  • 资源访问 (Resources)

  • 提示模板 (Prompts)

  • 日志系统 (Logging)

  • 根目录管理 (Roots)

  • AI 采样支持 (Sampling)

  1. 传输实现:

  • 标准输入输出 (Stdio)

  • HTTP SSE (Server-Sent Events)

  • WebFlux SSE

  • WebMVC SSE

  1. 设计模式:

  • 工厂模式 (McpClient/McpServer)

  • 构建器模式 (各种 Builder)

  • 装饰器模式 (同步包装异步)

  • 观察者模式 (事件通知)

关键交互流程

  • 初始化流程:
Client/Server -> Transport -> Session -> 协议版本协商 -> 能力协商
  • 1.
  • 消息处理流程:
请求/响应: 生成ID -> 序列化 -> 传输 -> 反序列化 -> 处理
通知: 序列化 -> 传输 -> 反序列化 -> 处理
  • 1.
  • 2.

资源管理流程:

发现 -> URI模板解析 -> 访问控制 -> 内容获取
  • 1.

这种分层架构使得代码结构清晰,各层职责明确,同时提供了良好的扩展性和可维护性。

让我来分析一下 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
  • 1.
  • 2.

2. 协议方法定义

生命周期方法

// 生命周期相关
METHOD_INITIALIZE = "initialize"                    // 初始化
METHOD_NOTIFICATION_INITIALIZED = "notifications/initialized"  // 初始化完成通知
METHOD_PING = "ping"                               // 心跳检测
  • 1.
  • 2.
  • 3.
  • 4.

工具相关方法

// 工具相关
METHOD_TOOLS_LIST = "tools/list"                   // 列出可用工具
METHOD_TOOLS_CALL = "tools/call"                   // 调用工具
METHOD_NOTIFICATION_TOOLS_LIST_CHANGED = "notifications/tools/list_changed"  // 工具列表变更通知
  • 1.
  • 2.
  • 3.
  • 4.

资源相关方法

// 资源相关
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"  // 资源列表变更通知
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.

Prompt 相关方法

// Prompt相关
METHOD_PROMPT_LIST = "prompts/list"                // 列出提示模板
METHOD_PROMPT_GET = "prompts/get"                  // 获取提示模板
METHOD_NOTIFICATION_PROMPTS_LIST_CHANGED = "notifications/prompts/list_changed"  // 提示模板列表变更通知
  • 1.
  • 2.
  • 3.
  • 4.

日志相关方法

// 日志相关
METHOD_LOGGING_SET_LEVEL = "logging/setLevel"      // 设置日志级别
METHOD_NOTIFICATION_MESSAGE = "notifications/message"  // 日志消息通知
  • 1.
  • 2.
  • 3.

3. 主要数据结构

客户端能力

public record ClientCapabilities(
    Experimental experimental,        // 实验性功能
    RootCapabilities roots,          // 根目录能力
    Sampling sampling                // 采样能力
)
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.

服务器能力

public record ServerCapabilities(
    Experimental experimental,       // 实验性功能
    LoggingCapabilities logging,     // 日志能力
    PromptCapabilities prompts,      // 提示模板能力
    ResourceCapabilities resources,  // 资源能力
    ToolCapabilities tools          // 工具能力
)
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.

内容类型

sealed interface Content {
    TextContent      // 文本内容
    ImageContent     // 图片内容
    EmbeddedResource // 嵌入资源
}
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.

根目录定义

public record Root(
    String uri,   // 根目录URI (必须以 file:// 开头)
    String name   // 根目录名称(可选)
)
  • 1.
  • 2.
  • 3.
  • 4.

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     // 参数
)
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.
  • 13.
  • 14.
  • 15.
  • 16.
  • 17.
  • 18.
  • 19.
  • 20.
  • 21.
  • 22.

这个协议设计遵循了 JSON-RPC 2.0 规范,并在此基础上定义了特定的方法和数据结构,主要包括:

  1. 基础通信协议 (初始化、心跳)
  2. 工具管理 (发现、调用)
  3. 资源管理 (列表、读取、订阅)
  4. 提示模板管理 (列表、获取)
  5. 日志系统 (级别设置、消息通知)
  6. 变更通知机制 (工具、资源、提示模板的变更通知)

这种设计使得 AI 模型能够通过标准化的接口与外部工具和资源进行交互。

责任编辑:武晓燕 来源: 海燕技术栈
相关推荐

2014-11-05 10:08:50

2021-07-14 09:48:15

Linux源码Epoll

2020-05-15 10:16:43

HttpHttps网络协议

2021-07-15 14:27:47

LinuxSocketClose

2019-05-10 10:13:10

Windows 功能系统

2019-07-15 09:45:00

华为鸿蒙开发

2021-03-10 08:20:54

设计模式OkHttp

2019-05-08 15:02:11

Android 10安卓谷歌

2022-02-23 12:56:45

框架开发

2017-04-05 20:00:32

ChromeObjectJS代码

2020-10-10 07:00:16

LinuxSocketTCP

2021-06-10 09:52:33

LinuxTCPAccept

2021-10-06 16:21:32

类型对象Typescript

2025-02-25 14:07:25

2018-02-02 15:48:47

ChromeDNS解析

2020-09-23 12:32:18

网络IOMySQL

2017-02-09 15:15:54

Chrome浏览器

2021-11-17 10:09:16

路由器天线频率

2020-06-11 09:18:34

动静分离架构架构设计开发

2021-05-19 08:20:59

ViewGrouplayout作用
点赞
收藏

51CTO技术栈公众号