JSON-RPC 2.0 协议详解

什么是 JSON-RPC 2.0？

JSON-RPC 2.0 就是一个简单的通信协议 ，用 JSON 格式让两个程序相互调用函数。简单点说就是JSON的一种特殊规则。

基本格式

请求（调用函数）

TypeScript 复制代码

{
  "jsonrpc": "2.0",    // 固定写法
  "id": 1,             // 请求编号，用来匹配响应
  "method": "sum",     // 要调用的函数名
  "params": {          // 函数参数
    "a": 10,
    "b": 20
  }
}

响应（返回结果）

TypeScript 复制代码

{
  "jsonrpc": "2.0",
  "id": 1,             // 与请求的 id 一致
  "result": 30         // 函数执行结果
}

错误（调用失败）

TypeScript 复制代码

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,    // 错误码
    "message": "参数错误"
  }
}

关键规则

1. 三种消息类型

请求：有 id，需要响应
通知：没有 id，不需要响应
响应：必须有对应的 id

2. 参数传递方式

TypeScript 复制代码

// 方式1：按位置（数组）
{"method": "sum", "params": [10, 20]}

// 方式2：按名称（对象）
{"method": "sum", "params": {"a": 10, "b": 20}}

完整协议规范

请求对象规范

字段	类型	必填	描述
`jsonrpc`	string	是	必须为 "2.0"
`method`	string	是	要调用的方法名
`params`	array/object	否	方法参数（按位置或按名称）
`id`	string/number/null	否	请求标识符（null 表示通知）

响应对象规范

字段	类型	必填	描述
`jsonrpc`	string	是	必须为 "2.0"
`id`	string/number	是	必须与请求中的 id 相同
`result`	any	条件	成功时返回的结果
`error`	object	条件	失败时返回的错误信息

标准错误码

错误码	含义	描述
-32700	Parse error	JSON 解析错误
-32600	Invalid Request	不是有效的 JSON-RPC 2.0 请求
-32601	Method not found	请求的方法不存在
-32602	Invalid params	参数无效或不正确
-32603	Internal error	服务器内部错误
-32000 to -32099	Server error	服务器定义的错误（保留范围）

MCP 如何使用 JSON-RPC

MCP 的 JSON-RPC 消息流

TypeScript 复制代码

Client                              Server
  │                                    │
  │  { "jsonrpc":"2.0",                │
  │    "id":1,                         │
  │    "method":"initialize",          │
  │    "params":{...} }                │
  │ ──────────────────────────────────>│
  │                                    │
  │  { "jsonrpc":"2.0",                │
  │    "id":1,                         │
  │    "result":{...} }                │
  │ <──────────────────────────────────│
  │                                    │
  │  { "jsonrpc":"2.0",                │
  │    "id":2,                         │
  │    "method":"tools/list",          │
  │    "params":{} }                   │
  │ ──────────────────────────────────>│
  │                                    │
  │  { "jsonrpc":"2.0",                │
  │    "id":2,                         │
  │    "result":{...} }                │
  │ <──────────────────────────────────│

MCP 就是用 JSON-RPC 2.0 来做三件事：

TypeScript 复制代码

// 1. 打招呼（初始化）
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}

// 2. 问有什么工具
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

// 3. 使用工具
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name": "sum",
  "arguments": {"a": 5, "b": 3}
}}

方法	用途	请求示例
`initialize`	初始化连接	`{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05",...}}`
`tools/list`	获取可用工具	`{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}`
`tools/call`	调用工具	`{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"sum","arguments":{"a":10,"b":20}}}`

总结要点

协议简单：就是 JSON 格式的函数调用
双向通信：可以请求，也可以通知
错误处理：有标准错误码
批量支持：一次发多个请求
传输灵活：可以用 HTTP、WebSocket、标准输入输出等

JSON-RPC 2.0 是一个实用而不是复杂的协议。MCP 基于它，让 AI 工具可以和外部程序安全地对话。