建站实战干货

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