5.4 MCP规范

本章详细介绍MCP协议的规范，包括协议版本历史、技术细节及兼容性考虑。了解MCP规范对于理解协议的工作原理，以及开发符合标准的MCP应用至关重要。

目录

• 协议概述
• 规范结构
• 协议版本历史
• 核心概念详解
• 请求与响应格式
• 传输层规范
• 错误处理规范
• 扩展点
• 兼容性考虑
• 实现指南

协议概述

MCP（模型上下文协议）是一个为大语言模型提供上下文和工具的标准化协议。它定义了客户端和服务器之间的通信方式，使大语言模型能够访问外部资源、使用外部工具，以及利用提示模板。

MCP的设计目标包括：

1. 简洁性：协议应当简单易懂，便于实现和使用
2. 可扩展性：支持不同类型的资源、工具和提示
3. 语言无关性：可以在任何编程语言中实现
4. 安全性：内置安全机制，防止恶意使用
5. 性能：高效的通信和处理，最小化延迟
6. 标准化：提供一致的接口，促进工具和实现之间的互操作性

规范结构

MCP规范主要分为以下几个部分：

1. 核心协议：定义基本概念、消息格式和交互流程
2. 传输层：定义不同的传输方式（stdio、SSE、WebSocket等）
3. 资源规范：定义资源的URI格式、参数和返回值
4. 工具规范：定义工具的注册、调用和返回值处理
5. 提示规范：定义提示模板的格式和用法
6. 扩展点：定义协议的扩展机制

协议版本历史

MCP协议遵循语义化版本控制（Semantic Versioning），其版本号格式为MAJOR.MINOR.PATCH。

版本兼容性

• 主版本（MAJOR）：不兼容的API变更
• 次版本（MINOR）：向后兼容的功能新增
• 补丁版本（PATCH）：向后兼容的问题修复

客户端应当在连接时指定其支持的MCP版本，服务器应当返回其实现的版本。如果版本不兼容，服务器应当返回错误。

核心概念详解

资源 (Resources)

资源是可以被读取的信息源，通过URI标识。

资源URI格式

MCP资源URI遵循以下格式：

scheme://path/to/resource

其中：

• scheme：资源类型，如file、data、http等
• path：资源路径，可包含参数

参数化资源路径使用花括号表示：

data://users/{user_id}/profile

资源请求

资源请求包含URI和可选的参数：

{
  "method": "read_resource",
  "params": {
    "uri": "data://users/123",
    "arguments": {
      "include_details": true
    }
  },
  "id": "req-1"
}

资源响应

资源响应包含内容和元数据：

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "用户资料内容..."
      }
    ],
    "isError": false,
    "meta": {
      "lastModified": "2023-11-25T10:30:00Z"
    }
  },
  "id": "req-1"
}

工具 (Tools)

工具是可以被调用的函数，具有名称、描述和参数。

工具定义

{
  "name": "calculate_bmi",
  "description": "计算BMI值",
  "arguments": {
    "type": "object",
    "properties": {
      "weight_kg": {
        "type": "number",
        "description": "体重（千克）"
      },
      "height_m": {
        "type": "number",
        "description": "身高（米）"
      }
    },
    "required": ["weight_kg", "height_m"]
  }
}

工具请求

{
  "method": "call_tool",
  "params": {
    "name": "calculate_bmi",
    "arguments": {
      "weight_kg": 70,
      "height_m": 1.75
    }
  },
  "id": "req-2"
}

工具响应

{
  "result": {
    "content": [
      {
        "type": "json",
        "json": {
          "bmi": 22.86,
          "category": "正常"
        }
      }
    ],
    "isError": false
  },
  "id": "req-2"
}

提示 (Prompts)

提示是可重用的模板，帮助模型理解特定任务。

提示定义

{
  "name": "code_review",
  "description": "代码审查提示",
  "arguments": {
    "type": "object",
    "properties": {
      "code": {
        "type": "string",
        "description": "要审查的代码"
      },
      "language": {
        "type": "string",
        "description": "编程语言",
        "default": "python"
      }
    },
    "required": ["code"]
  }
}

提示请求

{
  "method": "render_prompt",
  "params": {
    "name": "code_review",
    "arguments": {
      "code": "def hello(): print('world')",
      "language": "python"
    }
  },
  "id": "req-3"
}

提示响应

{
  "result": {
    "content": "请审查以下Python代码，指出潜在的问题和改进建议：\n\n```python\ndef hello(): print('world')\n```",
    "isError": false
  },
  "id": "req-3"
}

请求与响应格式

MCP使用基于JSON-RPC 2.0的请求和响应格式，但有一些特定于MCP的扩展。

基本请求格式

{
  "jsonrpc": "2.0",
  "method": "方法名",
  "params": {
    // 方法参数
  },
  "id": "请求ID"
}

基本响应格式

{
  "jsonrpc": "2.0",
  "result": {
    // 结果内容
  },
  "id": "请求ID"
}

错误响应格式

{
  "jsonrpc": "2.0",
  "error": {
    "code": 错误代码,
    "message": "错误消息",
    "data": {
      // 附加错误信息
    }
  },
  "id": "请求ID"
}

通知格式

通知是无需响应的请求：

{
  "jsonrpc": "2.0",
  "method": "方法名",
  "params": {
    // 方法参数
  }
  // 无ID字段
}

传输层规范

MCP支持多种传输方式，每种方式有其特定的规范。

Stdio传输

标准输入/输出传输使用换行符分隔的JSON消息：

{"jsonrpc":"2.0","method":"initialize","params":{},"id":"1"}\n
{"jsonrpc":"2.0","result":{"version":"0.7.0"},"id":"1"}\n

SSE传输

Server-Sent Events传输使用HTTP长连接，消息格式为：

event: message
data: {"jsonrpc":"2.0","method":"initialize","params":{},"id":"1"}

event: message
data: {"jsonrpc":"2.0","result":{"version":"0.7.0"},"id":"1"}

WebSocket传输

WebSocket传输使用标准WebSocket协议，每条消息包含一个完整的JSON对象。

HTTP传输

HTTP传输使用标准HTTP请求和响应，每个请求都是一个独立的HTTP POST请求。

错误处理规范

MCP定义了标准的错误代码和处理机制：

错误响应示例

{
  "jsonrpc": "2.0",
  "error": {
    "code": 3001,
    "message": "Resource not found",
    "data": {
      "uri": "data://users/999",
      "detail": "用户ID不存在"
    }
  },
  "id": "req-4"
}

扩展点

MCP规范定义了几个关键的扩展点，允许协议在未来增加新功能：

资源类型扩展

新的资源类型可以通过定义新的URI方案（scheme）来添加：

custom://my-resource-type/path

内容类型扩展

除了基本的文本和JSON内容类型，MCP允许定义新的内容类型：

{
  "type": "custom-type",
  "data": {
    // 自定义数据
  }
}

传输层扩展

新的传输方式可以通过实现传输接口来添加。

兼容性考虑

在开发MCP应用时，应当考虑以下兼容性问题：

版本兼容性

• 客户端应当指定其支持的最低和最高MCP版本
• 服务器应当支持一定范围的版本，并在连接时协商版本
• 在版本不兼容时，应当给出明确的错误信息

特性兼容性

• 对于可选特性，应当实现优雅降级
• 服务器应当在初始化响应中指明其支持的特性
• 客户端应当检查服务器支持的特性，并调整其行为

向前兼容性

• 忽略未知字段，这样当未来版本添加新字段时不会导致错误
• 为可选参数提供默认值，以支持未来的新参数
• 使用扩展性好的数据格式，如JSON Schema

实现指南

以下是实现MCP协议的一些指导原则：

服务器实现

1. 资源管理：

   • 实现资源URI解析和路由
   • 支持参数化路径和查询参数
   • 实现资源缓存机制
   • 处理资源读取错误

2. 工具管理：

   • 实现工具注册和发现
   • 验证工具参数
   • 处理工具执行错误
   • 支持异步工具

3. 提示管理：

   • 实现提示模板注册和发现
   • 支持参数化提示
   • 处理提示渲染错误

4. 会话管理：

   • 实现会话创建和跟踪
   • 管理会话状态
   • 处理会话超时和关闭

客户端实现

1. 连接管理：

   • 支持多种传输方式
   • 处理连接错误和重连
   • 实现超时处理

2. 资源访问：

   • 构建合法的资源URI
   • 处理资源读取响应
   • 实现资源缓存

3. 工具调用：

   • 验证工具参数
   • 处理工具响应
   • 支持重试机制

4. 提示渲染：

   • 构建提示参数
   • 处理提示响应

小结

本章详细介绍了MCP协议的规范，包括核心概念、请求和响应格式、传输层规范、错误处理、扩展点和兼容性考虑。通过了解MCP规范，您可以更好地理解协议的工作原理，并开发符合标准的MCP应用。

MCP规范是一个持续发展的标准，随着技术的进步和社区的反馈，未来版本可能会引入新的功能和改进。因此，建议定期关注官方规范文档，了解最新的变更和最佳实践。