小智 AI 设备端 MCP 工具

小智 AI 设备端 MCP 工具

MCP（Model Context Protocol）是新一代推荐用于物联网控制的协议，通过标准 JSON-RPC 2.0 格式在后台与设备间发现和调用「工具」（Tool），实现灵活的设备控制。

会话流程固定为：设备启动后通过基础协议（如 WebSocket/MQTT）与后台建立连接，后台通过 MCP 协议的 initialize 方法初始化会话，再通过 tools/list 获取设备支持的所有工具及参数说明，最后通过 tools/call 调用具体工具，实现对设备的控制。

按官方 README 的能力清单：通过设备端 MCP 实现设备控制（音量、灯光、电机、GPIO 等）；通过云端 MCP 扩展大模型能力（智能家居控制、PC桌面操作、知识搜索、邮件收发等）。本页只讲设备端工具的注册与验证，不展开协议报文与服务端实现。

设备通过 McpServer::AddTool 方法注册可被后台调用的工具，四个参数的含义：

常用函数签名：

void AddTool(
    const std::string& name,
    const std::string& description,
    const PropertyList& properties,
    std::function<ReturnValue(const PropertyList&)> callback
);

1. 在板级代码中实现 InitializeTools()，先获取实例：auto& mcp_server = McpServer::GetInstance();。预期结果：工具注册逻辑挂入板初始化流程，编译通过。
2. 注册无参数工具，官方示例（控制机器人前进）：

   mcp_server.AddTool("self.dog.forward", "机器人向前移动", PropertyList(), [this](const PropertyList&) -> ReturnValue {
       servo_dog_ctrl_send(DOG_STATE_FORWARD, NULL);
       return true;
   });

   预期结果：tools/list 返回的工具清单中出现 self.dog.forward 及其描述。
3. 注册带参数工具，官方示例（设置灯光 RGB 颜色，r/g/b 为 0–255 的整数）：

   mcp_server.AddTool("self.light.set_rgb", "设置RGB颜色", PropertyList({
       Property("r", kPropertyTypeInteger, 0, 255),
       Property("g", kPropertyTypeInteger, 0, 255),
       Property("b", kPropertyTypeInteger, 0, 255)
   }), [this](const PropertyList& properties) -> ReturnValue {
       int r = properties["r"].value<int>();
       int g = properties["g"].value<int>();
       int b = properties["b"].value<int>();
       led_on_ = true;
       SetLedColor(r, g, b);
       return true;
   });

   预期结果：工具带三个整数参数注册成功，被调用时灯光颜色随之改变。
4. 联网验证工具发现：会话建立后，后台发出 tools/list 请求：

   {"jsonrpc":"2.0","method":"tools/list","params":{"cursor":""},"id":1}

   预期结果：设备返回全部已注册工具与参数说明；工具名称、参数及返回值以设备端 AddTool 注册为准。
5. 验证工具调用：tools/call 的官方示例之一是控制底盘前进的 self.chassis.go_forward：

   {"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.chassis.go_forward","arguments":{}},"id":2}

   另有切换灯光模式的 self.chassis.switch_light_mode（arguments 为 {"light_mode": 3}）与摄像头翻转的 self.camera.set_camera_flipped。预期结果：设备执行对应 callback 并返回调用结果。

官方备注两条：其一，工具名称、参数及返回值请以设备端 AddTool 注册为准；其二，推荐所有新项目统一采用 MCP 协议进行物联网控制。

协议细节官方另有 docs/mcp-protocol_zh.md（MCP 协议交互流程）、docs/websocket_zh.md 与 docs/mqtt-udp_zh.md 可作深入阅读，本页不展开协议报文、不写服务端实现。