MCP (Model Context Protocol) 协议规范研究与 Hermes 兼容性评估报告

Codex 核验（2026-10-09）：本文的 SDK/Hermes 支持表是原日期观察。现行协议修订为 2026-07-28：移除协议会话和初始化握手，以每请求 _meta 声明版本/能力，增加 server/discover；订阅改为 subscriptions/listen；交互采用 MRTR；Tasks 移到官方扩展，Roots/Sampling/Logging 标为弃用并保留迁移期。旧 SDK 支持版本不能证明当前客户端端到端兼容。另已修正2025-03-26与2025-06-18的特性引入日期、字段名及 sampling 参数；根目录声明不是沙箱。

生成日期：2026-06-18
数据来源：modelcontextprotocol.io 官方文档 + GitHub spec 仓库(specification)
Python MCP SDK 版本：支持至 2025-11-25
Hermes Agent 版本：v0.16.0 (2026.6.5)

目录

1. MCP 协议概述
2. 核心概念详解
   • 2.1 Tools（工具）
   • 2.2 Resources（资源）
   • 2.3 Prompts（提示模板）
   • 2.4 Sampling（采样）
   • 2.5 Roots（根目录）
   • 2.6 Elicitation（引出）
3. 传输层分析
4. 安全模型
5. 最新进展（2025-11-25 版本）
6. Hermes MCP 实现分析
7. 兼容性矩阵
8. 差距分析与建议

1. MCP 协议概述

1.1 架构

MCP 采用 客户端-服务器架构，使用 JSON-RPC 2.0 作为通信协议：

MCP Host (AI 应用, 如 Claude Desktop)
  └── MCP Client #1 ──── MCP Server #1 (本地 stdio)
  └── MCP Client #2 ──── MCP Server #2 (远程 HTTP)
  └── MCP Client #3 ──── MCP Server #3 (远程 HTTP)

参与角色：

• MCP Host：AI 应用，协调多个 MCP Client
• MCP Client：维护与 MCP Server 的连接，获取上下文
• MCP Server：提供上下文数据（工具、资源、提示）

1.2 两层协议架构

1.3 生命周期

1. initialize — 能力协商 (protocol version, capabilities)
2. notifications/initialized — 客户端通知就绪
3. 正常通信 — list/call/get 等操作
4. 断开连接

初始化阶段协商的能力包括：

• 服务器能力：tools、resources、prompts、experimental
• 客户端能力：sampling、roots、elicitation

本报告采集时协议版本：2025-11-25（当前版本见文首核验） 向后兼容默认版本：2025-03-26

2. 核心概念详解

2.1 Tools（工具）

设计哲学：模型控制 (model-controlled) — LLM 自动发现和调用

能力声明：

{
  "capabilities": { "tools": { "listChanged": true } }
}

协议消息：

Tool 定义字段：

• name — 唯一标识符
• title (optional) — 显示名称
• description — 功能描述
• inputSchema — JSON Schema（2020-12 方言）输入参数
• outputSchema (optional) — 输出结构定义
• annotations (optional) — 行为元数据（安全提示、审计用途等）
• icons (optional, 2025-11-25 新增) — 图标

Tool Result 内容类型：

• text — 文本内容
• image — base64 图片 (data + mimeType)
• audio — base64 音频 (data + mimeType)
• resource — 嵌入的资源（包含完整数据）
• resource_link — 资源链接（仅 URI，需客户端获取）
• structuredContent (2025-06-18) — 结构化 JSON 输出

错误处理：

• 协议错误：标准 JSON-RPC 错误码（-32602 参数无效等）
• 工具执行错误：isError: true 在 result 中，允许 LLM 自我纠正

2.2 Resources（资源）

设计哲学：应用驱动 (application-driven) — 宿主应用决定如何使用

能力声明：

{
  "capabilities": {
    "resources": {
      "subscribe": true,     // 支持资源变更订阅
      "listChanged": true    // 支持列表变更通知
    }
  }
}

协议消息：

Resource 字段：

• uri — 唯一 URI 标识
• name — 名称
• title (optional) — 显示名称
• description (optional) — 描述
• mimeType (optional) — MIME 类型
• size (optional) — 字节数
• annotations (optional) — 元数据（audience, priority, lastModified）
• icons (optional, 2025-11-25 新增)

标准 URI 方案： https://, file://, git:// + 自定义

内容格式： text（文本）或 blob（base64 二进制）

错误码： 资源未找到 → -32002

2.3 Prompts（提示模板）

设计哲学：用户控制 (user-controlled) — 用户显式选择

能力声明：

{
  "capabilities": { "prompts": { "listChanged": true } }
}

协议消息：

Prompt 字段： name, title(optional), description(optional), arguments(optional) PromptMessage： role (user/assistant) + content (text/image/audio/resource)

2.4 Sampling（采样）

设计哲学：服务器通过客户端请求 LLM 生成 — 让无 API Key 的服务器也能使用 LLM

能力声明（客户端）：

{
  "capabilities": { "sampling": {} }
}

协议消息：

参数：

• messages — 对话消息（text, image, audio）
• modelPreferences — 模型偏好（intelligencePriority, speedPriority, costPriority + model hints）
• systemPrompt (optional)
• maxTokens (required)
• stopReason（响应字段，不是请求参数）
• includeContext (optional) — 是否包含 MCP 上下文
• tools (optional, 2025-11-25 新增) — 采样时可用的工具
• toolChoice (optional, 2025-11-25 新增)

安全要求： 必须有用户审核批准 UI

2.5 Roots（根目录）

设计哲学：客户端向服务器暴露文件系统边界

能力声明（客户端）：

{
  "capabilities": { "roots": { "listChanged": true } }
}

协议消息：

Root 字段： uri (必须是 file:// URI) + name(optional)

2026-07-28 版本根据 SEP-2577 弃用 Roots、Sampling 和 Logging（迁移期仍可用）

2.6 Elicitation（引出）

2025-11-25 版本新增的客户端特性

设计哲学：服务器向用户请求额外信息或确认，替代原先手动设计的交互模式

能力声明（客户端）：

{
  "capabilities": { "elicitation": {} }
}

协议消息：

特性：

• URL 模式引出 (URL Mode Elicitation) — 安全的外部带外交互
• 枚举模式改进 — 单/多选、有标题/无标题枚举
• 所有原始类型的默认值支持

3. 传输层分析

3.1 stdio 传输

3.2 Streamable HTTP 传输

从 2025-03-26 版本开始取代旧的 HTTP+SSE 传输

Streamable HTTP vs 旧 HTTP+SSE：

3.3 自定义传输

协议传输无关，可通过任何双向通信通道实现，前提是保持 JSON-RPC 消息格式和生命周期要求。

4. 安全模型

4.1 认证与授权

• OAuth 2.1 — 推荐认证方式
• Bearer Token — HTTP 标准 Authorization 头
• API Key — 自定义 Header
• OpenID Connect Discovery 1.0 (2025-11-25 新增)
• OAuth Client ID Metadata Documents (2025-11-25 新增)
• 增量 Scope 同意 (增量授权, 2025-11-25 新增)

4.2 安全最佳实践

服务器端：

• 验证所有输入参数
• 实现访问控制
• Rate limit 工具调用
• 清理输出内容
• 验证 Origin 头（防 DNS rebinding）
• 本地运行绑定 ${LOCALIP}

客户端端：

• 敏感操作前请用户确认
• 调用前展示工具参数给用户
• 验证工具结果
• 实现工具调用超时
• 记录工具审计日志
• 输入验证错误作为工具执行错误而非协议错误（SEP-1303）

4.3 Tool Annotations（2025-03-26）

工具注解提供安全相关元数据：

• readOnlyHint — 工具是否只读
• idempotentHint — 是否幂等
• openWorldHint — 是否需开放世界访问
• destructiveHint — 是否可能造成破坏

客户端必须将工具注解视为不可信数据（除非来自可信服务器）

5. 最新进展（2025-11-25 版本）

5.1 自 2025-06-18 以来的主要变更

5.2 活跃的 SEP（正在进行中）

5.3 扩展生态

• MCP Apps — 在 MCP 宿主（如 Claude Desktop）内部渲染的交互式 UI 应用
• Registry — MCP 服务器注册表，支持发布、搜索、版本管理
• Tasks — 异步任务执行扩展
• File Uploads — 文件上传工作组进行中
• Triggers and Events — 触发器和事件工作组进行中

6. Hermes MCP 实现分析

6.1 整体架构

Hermes 的 MCP 实现分为三个主要部分：

tools/mcp_tool.py         → MCP 客户端（连接外部 MCP 服务器）
mcp_serve.py              → MCP 服务器（对外暴露 Hermes 功能）
hermes_cli/mcp_config.py  → MCP 服务器管理 CLI
hermes_cli/mcp_catalog.py → MCP 目录（预配置精选 MCP 服务器）

6.2 客户端实现 (tools/mcp_tool.py ~3500 行)

支持的传输方式：

• ✅ stdio — 启动子进程 MCP 服务器
• ✅ Streamable HTTP — 新的 HTTP 传输协议
• ✅ SSE — 旧的 HTTP+SSE 传输（通过 transport: sse 配置，向后兼容）

支持的协议版本：

• 2024-11-05（历史）
• 2025-03-26（默认向后兼容）
• 2025-06-18（文档版）
• 2025-11-25（最新，通过 Python MCP SDK LATEST_PROTOCOL_VERSION）

实现的客户端功能：

6.3 服务器实现 (mcp_serve.py)

使用 FastMCP（MCP Python SDK 的高级 API）实现，暴露 Hermes 消息平台作为 MCP 服务器。

暴露的工具（9 + 1）：

1. conversations_list
2. conversation_get
3. messages_read
4. attachments_fetch
5. events_poll
6. events_wait
7. messages_send
8. permissions_list_open
9. permissions_respond
10. channels_list（Hermes 特有扩展）

6.4 配置与管理

MCP 服务器配置 (config.yaml)：

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    env: {}
    timeout: 120
  remote_api:
    url: "https://my-mcp-server.example.com/mcp"
    headers:
      Authorization: "Bearer sk-..."

CLI 命令： hermes mcp add|remove|list|test|configure

MCP 目录 (Catalog)： 预装精选 MCP 服务器，通过 hermes mcp install <name> 安装

7. 兼容性矩阵

7.1 MCP 规范 vs Hermes 实现

7.2 版本支持谱系

MCP 规范版本:         Hermes SDK 支持:
2024-11-05  ───────  ✅ (旧 HTTP+SSE)
2025-03-26  ───────  ✅ (默认兼容版本)
2025-06-18  ───────  ✅ (Streamable HTTP)
2025-11-25  ───────  ✅ (原日期 SDK 支持快照)

8. 差距分析与建议

8.1 关键差距

8.2 优势 (Hermes 做得好的)

1. 全面的传输支持 — stdio + Streamable HTTP + SSE 三种传输全部覆盖
2. 最新 SDK 版本 — 已经支持到 2025-11-25 协议版本
3. Sampling 实现完整 — 支持文本和工具调用响应，速率限制
4. OAuth 支持 — 自动 401 重新认证流
5. 安全实践扎实 — 凭据剥离、环境变量过滤、输入验证
6. MCP 目录 — 精选服务器便于用户发现和安装
7. 双角色架构 — 既是客户端（调用外部 MCP）又是服务器（暴露自身功能）

8.3 建议路线图

近期（1-2 周）：

1. 实现 Elicitation 客户端回调 — 支持新版交互模式
2. 评估 Resources/Prompts 是否需要从工具形式迁移到原生形式

中期（1-2 月）： 3. 追踪 SEP-2577 (弃用 Roots/Sampling/Logging) 的方向 4. 实现工具注解支持 5. 追踪 SEP-2567/2575 (无状态 MCP) 的进展

长期： 6. 如果规范化支持，实现 Tasks 扩展 7. 评估支持 MCP Apps 的可行性 8. 跟踪 SEP-2322 (MRTR 多轮往返请求) 的标准化

8.4 总结

Hermes 的 MCP 实现在 工具调用 和 传输层 方面非常完善，覆盖从 stdio 到 Streamable HTTP 的所有传输方式，并已同步到最新协议版本 (2025-11-25)。主要差距在于 Elicitation（新版交互模式）和部分客户端特性未实现。整体兼容性评级为 A-（优秀），能够满足绝大多数 MCP 集成需求。

附录

A. 参考来源

• modelcontextprotocol.io/docs/learn/architecture
• modelcontextprotocol.io/specification/2025-11-25
• GitHub: modelcontextprotocol/specification
• Hermes Agent v0.16.0: tools/mcp_tool.py, mcp_serve.py, hermes_cli/mcp_*.py

B. 相关 SEPS 索引