0 序
- 在开发 MCP（SSE模式）、客户端请求mcp server时，发现使用了 json-rpc 2.0 协议，故此研究并总结一二。
- MCP Server/Tool 开发指南 - 博客园/数据知音
【request】
curl -X POST "http://127.0.0.1:18001/messages/?session_id=$SESSION_ID" \-H "Content-Type: application/json" \-d '{"jsonrpc": "2.0","method": "tools/call","params": {"name": "calculate","arguments": { "expression" : "1+3+6" }},"id": 1}'【response】success
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"10"}],"structuredContent":{"result":"10"},"isError":false}}【response】error
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Error executing tool get_date: module 'darabonba.date' has no attribute 'today'"}],"isError":true}}
第一部分 概述
JSON-RPC 2.0是一种基于JSON（JavaScript Object Notation）的远程过程调用（RPC）协议。它是一种轻量级的、无状态的、跨语言的通信协议，常用于客户端与服务端之间的交互。- 官方定义: JSON-RPC是一个无状态且轻量级的远程过程调用(RPC)协议。 本规范主要定义了一些数据结构及其相关的处理规则。它允许运行在基于socket,http等诸多不同消息传输环境的同一进程中。其使用JSON（RFC 4627）作为数据格式。
https://www.jsonrpc.org/specification
-
协议作者: JSON-RPC工作组< json-rpc@googlegroups.com >
-
协议诞生日期/Origin Date: 2010-03-26 (based on the 2009-05-24 version)
-
协议诞生日期/Updated Date:2013-01-04
第二部分 基本特点
- 简单直观：消息结构清晰，仅由JSON对象组成。
- 双向通信：支持客户端调用服务端方法，服务端也可通知客户端。
- 无状态：协议本身不维护会话状态。
- 支持批量请求：允许在一个JSON数组中发送多个请求，提升效率。
- 错误处理：定义了标准的错误对象，便于排查和处理异常。
第三部分 消息格式
在JSON-RPC 2.0中，有以下三种主要的消息类型：
- 请求对象（Request Object）
- 响应对象（Response Object）
- 通知对象（Notification Object）
3.1 请求对象
用于客户端调用服务端的方法，结构如下：
{"jsonrpc": "2.0","method": "methodName","params": ["param1", "param2"],"id": 1
}
jsonrpc：协议版本，固定为2.0。method：调用的远程方法名。params：方法参数，可以是数组或对象。id：唯一标识请求的ID，用于匹配响应。可为数字、字符串或null。
示例：
{"jsonrpc": "2.0","method": "add","params": [4, 5],"id": 123
}
3.2 响应对象
用于服务端返回结果或错误信息，结构如下：
成功响应：
{"jsonrpc": "2.0","result": 9,"id": 123
}
jsonrpc：协议版本。result：调用方法的返回结果。id：与请求对象中的id一致，用于匹配响应。
错误响应：
{"jsonrpc": "2.0","error": {"code": -32600,"message": "Invalid Request","data": "Additional information if available"},"id": null
}
-
error：包含错误信息的对象。
code：标准错误码。message：错误描述信息。data：可选的额外错误信息。
-
id：如果无法解析请求或无法响应，则id设为null。
3.3 通知对象
通知是一种特殊的请求，不需要响应。用于不关心结果的场景，例如日志记录等。
通知对象示例：
{"jsonrpc": "2.0","method": "logMessage","params": ["User logged in"]
}
- 没有
id字段。 - 不会有响应对象返回。
第四部分 错误码列表
JSON-RPC 2.0定义了一组标准错误码：
| 错误码 | 错误类型 | 描述 |
|---|---|---|
| -32700 | Parse Error | 无法解析 JSON 数据 |
| -32600 | Invalid Request | 请求对象无效 |
| -32601 | Method Not Found | 方法不存在或不可用 |
| -32602 | Invalid Params | 参数无效 |
| -32603 | Internal Error | 服务端内部错误 |
| -32000~-32099 | Server Error | 自定义服务器错误 |
第五部分 批量请求与响应
JSON-RPC 2.0支持在一个请求中发送多个调用，服务端也会以数组形式返回响应。
批量请求示例：
[{"jsonrpc": "2.0","method": "add","params": [1, 2],"id": 1},{"jsonrpc": "2.0","method": "subtract","params": [5, 3],"id": 2}
]
批量响应示例：
[{"jsonrpc": "2.0","result": 3,"id": 1},{"jsonrpc": "2.0","result": 2,"id": 2}
]
如果某个请求是通知或者出错，也会在响应中反映：
[{"jsonrpc": "2.0","result": 3,"id": 1},{"jsonrpc": "2.0","error": {"code": -32601,"message": "Method not found"},"id": 2}
]
第六部分 示例场景
场景1：简单调用 客户端请求服务端进行加法运算：
{"jsonrpc": "2.0","method": "add","params": [10, 20],"id": 100
}
服务端返回结果：
{"jsonrpc": "2.0","result": 30,"id": 100
}
场景2：错误处理 客户端请求一个不存在的方法：
{"jsonrpc": "2.0","method": "unknownMethod","params": [],"id": 101
}
服务端返回错误：
{"jsonrpc": "2.0","error": {"code": -32601,"message": "Method not found"},"id": 101
}
场景3：通知 客户端发送通知，不需要返回结果：
{"jsonrpc": "2.0","method": "notifyEvent","params": ["EventData"]
}
服务端不会返回任何响应。
第七部分 总结
JSON-RPC 2.0提供了一种简洁、灵活且强大的通信方式，特别适用于：
- 分布式系统中的服务调用
- 微服务架构下的跨语言交互
- 物联网设备与后端服务的通信
通过JSON-RPC 2.0，可以高效地管理远程方法调用、错误处理和批量操作，提升系统的整体性能和可靠性。
Y 推荐文献
-
JSON-RPC 2.0- jsonrpc.org- https://www.jsonrpc.org/specification (官方)
- https://wiki.geekdream.com/Specification/json-rpc_2.0.html (第三方-中文版)
-
MCP Server/Tool 开发指南 - 博客园/数据知音
X 参考文献
- JSON-RPC 2.0详解 - jianggujin.com
