本文档定义了基于聆思端云交互链路 ws[s]://api.listenai.com/v1/interaction 的 MCP 协议扩展规范，用于实现云端与设备端的工具调用交互。
在建立 WebSocket 连接时，需要在 param 参数中包含 MCP 标识：
{
"mcp": true
}
云端成功建链后，会下发 initialize 协议帧：
{
"action": "mcp",
"cid": "bc272a9035c8481499e74a909e6305a1",
"sid": "da65b86513ef",
"code": "0",
"data": {
"method": "initialize",
"id": "f8f90dc43fcf46b9b1309a8f1c9035da",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {
"vision": {
"url": "",
"token": ""
}
}
}
},
"desc": "success"
}
设备端收到 initialize 请求后，需要返回能力声明和服务信息：
{
"id": "xxx",
"action": "mcp",
"method": "initialize",
"result": {
"capabilities": {
"tools": {}
},
"serverInfo": {
"name": "arcs-mini",
"version": "1.0.0"
},
"instructions": "设备端MCP服务的简单描述"
}
}
字段说明：
capabilities.tools: 工具能力声明（目前为空对象）serverInfo.name: 设备端服务名称serverInfo.version: 服务版本号instructions: 服务描述信息初始化完成后，云端会请求设备端的可用工具列表：
{
"action": "mcp",
"cid": "cidf415ba9c@dx8d0d18b0d6dd3eef00",
"sid": "7301c705aef84ff6bfacfb56d1e3f2c2",
"code": "0",
"data": {
"method": "tools/list",
"id": "xxx",
"params": {
"cursor": ""
}
},
"desc": "success"
}
参数说明：
cursor: 分页游标，首次请求为空字符串设备端返回所有可用工具的详细信息：
{
"id": "xxx",
"action": "mcp",
"method": "tools/list",
"result": {
"tools": [
{
"name": "set_screen",
"description": "设置屏幕显示内容或状态",
"inputSchema": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "显示内容"
},
"brightness": {
"type": "number",
"description": "亮度值 (0-100)"
}
},
"required": ["content"]
}
},
{
"name": "set_volume",
"description": "调节设备音量",
"inputSchema": {
"type": "object",
"properties": {
"value": {
"type": "number",
"description": "音量值 (0-100)",
"minimum": 0,
"maximum": 100
}
},
"required": ["value"]
}
}
],
"nextCursor": "page_2_token"
}
}
字段说明：
tools: 工具列表数组
name: 工具唯一标识符description: 工具功能描述inputSchema: JSON Schema 格式的参数定义nextCursor: 下一页游标（如无更多数据则省略此字段）当云端需要调用设备端工具时，发送 tools/call 请求：
{
"action": "mcp",
"cid": "cidf415ba9c@dx8d0d18b0d6dd3eef00",
"sid": "7301c705aef84ff6bfacfb56d1e3f2c2",
"code": "0",
"data": {
"method": "tools/call",
"id": "xxx",
"params": {
"name": "set_volume",
"arguments": {
"value": 50
}
}
},
"desc": "success"
}
参数说明：
name: 要调用的工具名称arguments: 传递给工具的参数对象设备端执行工具后，返回执行结果：
{
"id": "xxx",
"action": "mcp",
"method": "tools/call",
"result": {
"content": [
{
"type": "text",
"text": "音量已设置为 50%"
},
{
"type": "image",
"data": "base64-encoded-image-data",
"mimeType": "image/png"
}
],
"isError": false
}
}
当工具执行失败时，返回错误信息：
{
"id": "xxx",
"action": "mcp",
"method": "tools/call",
"result": {
"content": [
{
"type": "text",
"text": "音量设置失败: 参数超出范围 (0-100)"
}
],
"isError": true
}
}
响应字段说明：
content: 结果内容数组，支持多种类型：
text: 文本内容image: Base64 编码的图片数据isError: 执行状态标识
false: 执行成功true: 执行失败| 错误类型 | 描述 | 处理方式 |
|---|---|---|
| 工具不存在 | 调用的工具名称不在可用列表中 | 返回 isError: true 和错误描述 |
| 参数验证失败 | 传入参数不符合 inputSchema 定义 | 返回参数验证错误信息 |
| 工具执行异常 | 工具内部执行出错 | 返回具体异常信息 |
| 连接中断 | WebSocket 连接异常 | 需要重新建立连接和初始化 |
当前协议版本: v1.0
未来版本升级时，将遵循向后兼容原则，新增字段采用可选方式，废弃字段会提前通知并保持一定时间的兼容性。