diff --git a/docs/xrobot/mcp/hardware-mcp.md b/docs/xrobot/mcp/hardware-mcp.md index 1d77356..cc1d7cd 100644 --- a/docs/xrobot/mcp/hardware-mcp.md +++ b/docs/xrobot/mcp/hardware-mcp.md @@ -11,13 +11,19 @@ MCP(Model Context Protocol)是新一代推荐用于物联网控制的协议 ## 目录 - [概述](#概述) +- [目录](#目录) - [典型使用流程](#典型使用流程) + - [流程图](#流程图) - [协议格式规范](#协议格式规范) + - [整体消息结构](#整体消息结构) + - [JSON-RPC 2.0字段说明](#json-rpc-20字段说明) - [详细交互流程](#详细交互流程) - - [连接建立与能力通告](#连接建立与能力通告) - - [初始化MCP会话](#初始化mcp会话) - - [发现设备工具列表](#发现设备工具列表) - - [调用设备工具](#调用设备工具) + - [步骤1:连接建立与能力通告](#步骤1连接建立与能力通告) + - [步骤2:初始化MCP会话](#步骤2初始化mcp会话) + - [步骤3:发现设备工具列表](#步骤3发现设备工具列表) + - [响应格式一:标准工具列表(向后兼容)](#响应格式一标准工具列表向后兼容) + - [响应格式二:带类型标识的工具列表(推荐)](#响应格式二带类型标识的工具列表推荐) + - [步骤4:调用设备工具](#步骤4调用设备工具) - [设备端工具注册方法](#设备端工具注册方法) - [AddTool方法说明](#addtool方法说明) - [典型注册示例](#典型注册示例) @@ -211,6 +217,8 @@ MCP协议的交互主要围绕客户端(灵矽AI平台)发现和调用设备 **📨 设备端 → 灵矽平台** +#### 响应格式一:标准工具列表(向后兼容) + ```json { "jsonrpc": "2.0", @@ -249,6 +257,55 @@ MCP协议的交互主要围绕客户端(灵矽AI平台)发现和调用设备 } ``` +#### 响应格式二:带类型标识的工具列表(推荐) + +为了同时支持标准工具(tool)和 RPC 函数调用(rpc),新增 `type` 字段用于区分工具类型: + +```json +{ + "jsonrpc": "2.0", + "id": 2, // 匹配请求 ID + "result": { + "tools": [ // 工具对象列表 + { + "name": "self.get_device_status", + "description": "获取设备当前状态信息", + "type": , // 函数类型,0 表示 tool 函数,1 表示 rpc 函数 + "inputSchema": { + "type": "object", + "properties": {}, + "required": [] + } + }, + { + "name": "self.audio_speaker.set_volume", + "description": "设置音箱音量", + "type": 0, // 函数类型,0 表示 tool 函数 + "inputSchema": { + "type": "object", + "properties": { + "volume": { + "type": "integer", + "minimum": 0, + "maximum": 100, + "description": "音量大小,范围0-100" + } + }, + "required": ["volume"] + } + } + // ... 更多工具 + ], + "nextCursor": null // 如果列表很大需要分页,这里会包含下一个请求的 cursor 值 + } +} +``` + +**字段说明**: + +- `type`:函数类型标识,0 表示 tool 函数,1 表示 rpc 函数 +- 其他字段与标准 MCP 工具定义保持一致 + **分页处理**:如果 `nextCursor` 字段非空,客户端需要再次发送 `tools/list` 请求,并在 `params` 中带上这个 cursor 值以获取下一页工具。 ### 步骤4:调用设备工具 diff --git a/docs/xrobot/platform/websocket.md b/docs/xrobot/platform/websocket.md index f045d91..1234b90 100644 --- a/docs/xrobot/platform/websocket.md +++ b/docs/xrobot/platform/websocket.md @@ -399,6 +399,14 @@ WebSocket 支持 **🎵 音频数据帧**(二进制方式)以及 **文本帧 } ``` +##### 5. Notify 消息 +```json +{ + "type": "notify", + "event": "config_updated" // 智能体配置已更新,建议设备重新连接生效 +} +``` + ### 2. MCP 相关消息 MCP(Model Control Protocol)是物联网控制的新一代协议,用于设备能力发现、状态同步和控制指令。