[JSON/RPC/MCP] JSON-RPC 2.0 : 轻量级远程过程调用协议

0 序

  • 在开发 MCP（SSE模式）、客户端请求mcp server时，发现使用了 json-rpc 2.0 协议，故此研究并总结一二。
【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}}

image

第一部分 概述

  • 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 推荐文献

X 参考文献

posted @ 2026-03-25 13:03  千千寰宇  阅读(62)  评论(0)    收藏  举报