跳转到主要内容

​
数据层协议

​
2.1 JSON-RPC 2.0基础

MCP的数据层基于 JSON-RPC 2.0 规范。所有消息都是JSON格式，分三类：

​
请求 (Request)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
  • jsonrpc: 固定为 "2.0"
  • id: 请求唯一标识（字符串或数字），用于匹配响应
  • method: 调用的方法名
  • params: 方法参数（可选，Object类型）

​
响应 (Response)

成功响应： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "tools": [] }
}
错误响应： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32601, "message": "Method not found", "data": {} }
}
result 和 error 互斥，一个响应只会包含其中之一。

​
通知 (Notification)

没有 id 字段，不期望响应： 
{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}
通知是单向的，发送方不需要等待任何回复。

​
2.2 Server端 Primitive

MCP Server可以暴露三种核心能力：

​
Tools（工具）— 模型控制

可执行的函数。AI模型自主决定何时调用。
方法方向用途
tools/listClient → Server列出所有可用工具（支持分页）
tools/callClient → Server执行指定工具
notifications/tools/list_changedServer → Client工具列表变更通知
工具定义（协议版本 2025-11-25）: 
{
  "name": "check_inventory",
  "title": "库存查询",
  "description": "查询指定SKU的实时库存数量",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sku": { "type": "string", "description": "商品SKU编号" },
      "warehouse": { "type": "string", "description": "仓库代码（可选）" }
    },
    "required": ["sku"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "sku": { "type": "string" },
      "quantity": { "type": "number" },
      "warehouses": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "code": { "type": "string" },
            "quantity": { "type": "number" }
          }
        }
      }
    }
  }
}
关键字段说明:
  • name: 工具的唯一标识符
  • title: 人类可读的显示名称
  • description: 描述工具用途，直接影响AI模型的选择决策
  • inputSchema: JSON Schema格式的输入参数定义（必需）
  • outputSchema: JSON Schema格式的输出结构定义（可选，2025-11-25 新增）
工具执行结果: 
{
  "content": [
    { "type": "text", "text": "SKU SHOE-001 库存: 北京仓 45件, 上海仓 23件" }
  ],
  "structuredContent": {
    "sku": "SHOE-001",
    "quantity": 68,
    "warehouses": [
      { "code": "BJ", "quantity": 45 },
      { "code": "SH", "quantity": 23 }
    ]
  },
  "isError": false
}
  • content: 内容数组，支持多种类型（text、image、audio、resource_link、embedded_resource）
  • structuredContent: 与 outputSchema 对应的结构化数据（可选，与 content 同时返回，优先用于程序化处理）
  • isError: 标识是否为工具级错误（true 表示工具执行失败但协议层正常）
两种错误类型:
  1. 协议层错误: JSON-RPC error响应，表示请求本身有问题（方法不存在、参数无效等）
  2. 工具层错误: isError: true，表示工具执行了但遇到业务错误（商品不存在、权限不足等）

​
Resources（资源）— 应用控制

数据源，提供上下文信息。和Tools的区别：Tools是”做事”，Resources是”提供信息”。
方法方向用途
resources/listClient → Server列出所有可用资源（支持分页）
resources/readClient → Server读取指定资源
resources/subscribeClient → Server订阅资源变化
resources/unsubscribeClient → Server取消订阅
notifications/resources/list_changedServer → Client资源列表变更通知
notifications/resources/updatedServer → Client已订阅资源内容变更通知
资源定义: 
{
  "uri": "commerce://catalog/categories",
  "name": "商品分类",
  "description": "当前所有商品分类及其层级结构",
  "mimeType": "application/json",
  "annotations": {
    "audience": ["user", "assistant"],
    "priority": 0.8,
    "lastModified": "2026-04-10T08:00:00Z"
  }
}
Annotations字段说明:
  • audience: 目标受众，可选值包括 "user" 和 "assistant"
  • priority: 优先级，0到1之间的浮点数（1为最高优先级）
  • lastModified: 最后修改时间（ISO 8601格式）
URI模板: 资源URI支持RFC 6570 URI模板语法，用于定义动态资源： 
commerce://products/{sku}
commerce://orders/{orderId}/items

​
Prompts（提示词模板）— 用户控制

可复用的交互模板。Server可以提供预定义的提示词，用户在Host应用中主动选择使用。
方法方向用途
prompts/listClient → Server列出所有可用提示词（支持分页）
prompts/getClient → Server获取指定提示词（支持arguments参数化）
notifications/prompts/list_changedServer → Client提示词列表变更通知
提示词定义: 
{
  "name": "product_recommendation",
  "description": "根据用户需求推荐商品",
  "arguments": [
    { "name": "category", "description": "商品类别", "required": true },
    { "name": "budget", "description": "预算范围", "required": false }
  ]
}
获取提示词: 
// Client → Server
{
  "method": "prompts/get",
  "params": {
    "name": "product_recommendation",
    "arguments": { "category": "运动鞋", "budget": "500-1000" }
  }
}

// Server → Client
{
  "result": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "请推荐500-1000元价位的运动鞋，考虑性价比、舒适度和品牌口碑。"
        }
      }
    ]
  }
}

​
2.3 Client端 Primitive

MCP Client也可以暴露能力给Server（需在初始化时声明）：

​
Sampling — Server请求LLM推理

Server无需内置AI SDK，可以请求Host的LLM完成推理。 
// Server → Client
{
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      { "role": "user", "content": { "type": "text", "text": "将以下文本翻译为英文：你好世界" } }
    ],
    "maxTokens": 100,
    "modelPreferences": {
      "hints": [{ "name": "claude-sonnet" }],
      "costPriority": 0.3,
      "speedPriority": 0.8,
      "intelligencePriority": 0.5
    }
  }
}
modelPreferences字段:
  • hints: 模型提示列表，Server建议使用的模型（Host可以忽略）
  • costPriority: 成本优先级（0-1，越高越倾向低成本模型）
  • speedPriority: 速度优先级（0-1，越高越倾向快速模型）
  • intelligencePriority: 智能优先级（0-1，越高越倾向高能力模型）

​
Elicitation — Server请求用户输入

Server需要用户确认或补充信息时使用。 
// Server → Client
{
  "method": "elicitation/request",
  "params": {
    "message": "退货需要确认以下信息",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "reason": { "type": "string", "description": "退货原因" },
        "confirm": { "type": "boolean", "description": "确认退货" }
      },
      "required": ["reason", "confirm"]
    }
  }
}

​
Roots — 文件系统边界

Server查询可访问的文件系统范围。 
// Server → Client
{ "method": "roots/list" }

// Client → Server
{
  "result": {
    "roots": [
      { "uri": "file:///home/user/project", "name": "项目目录" }
    ]
  }
}

​
Logging — 日志消息

Server向Client发送日志消息，用于调试和监控。 
// Server → Client (通知)
{
  "method": "notifications/message",
  "params": {
    "level": "warning",
    "logger": "inventory-service",
    "data": "SKU SHOE-001 库存低于阈值"
  }
}
日志级别: debug、info、notice、warning、error、critical、alert、emergency。

​
2.4 能力协商

初始化时，双方声明支持的能力。只有声明的能力才能使用。 Server能力: 
{
  "capabilities": {
    "tools": { "listChanged": true },
    "resources": { "subscribe": true, "listChanged": true },
    "prompts": { "listChanged": true },
    "logging": {}
  }
}
  • listChanged: Server会在列表变化时发送通知
  • subscribe: 支持资源订阅（内容变化时通知Client）
Client能力: 
{
  "capabilities": {
    "sampling": {},
    "elicitation": {},
    "roots": { "listChanged": true }
  }
}
  • sampling: Client支持Server请求LLM推理
  • elicitation: Client支持Server请求用户输入
  • roots.listChanged: Client会在文件系统边界变化时通知Server

​
2.5 错误处理

MCP使用JSON-RPC 2.0标准错误码加上MCP自定义扩展：

​
标准JSON-RPC错误码

错误码含义
-32700JSON解析错误（Parse error）
-32600无效的请求（Invalid Request）
-32601方法不存在（Method not found）
-32602无效的参数（Invalid params）
-32603内部错误（Internal error）

​
MCP自定义错误码

错误码含义说明
-32001请求超时Server处理时间过长
-32002资源不存在请求的资源URI无效

​
工具层错误

工具执行中的业务错误不使用JSON-RPC error，而是通过正常响应中的 isError 标志传递： 
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      { "type": "text", "text": "订单 ORD-001 不存在或已取消" }
    ],
    "isError": true
  }
}
这种设计让AI模型能看到错误信息并据此调整行为（比如换一个订单号重试）。
下一章: 传输层 — stdio和Streamable HTTP两种传输方式详解