摘要

让机器人"听懂人话"这件事,我的第一反应是写一个规则引擎:把"挥挥手"“跳个舞"这些句子枚举进一张配置表,命中就调接口,没命中就回复"我不明白”。这个思路在演示里跑得通,规模一大就露馅:指令组合无穷、口语千变万化,规则表永远追不上用户的嘴。

2026 年情况变了,大模型的工具调用能力已经足够稳,缺的是一个把机器人能力"递"给模型的标准化通道。**MCP(Model Context Protocol)**就是这个通道:机器人侧只需要把自己的能力描述成一组工具,任何 MCP 客户端连上来,模型就能看懂工具清单、自主决定调用顺序,甚至在出错后自己想办法补救。

这篇文章把启元 Q1 的 SDK 封装成一个 MCP 服务器,8 个工具覆盖姿态、动作、语音、表情、灯效、行走与状态查询。文末的实测里,模型面对"机器人处于休眠姿态、动作请求被拒绝"的局面,没有人教它怎么办,它自己读工具说明、自己唤醒、自己重试。

一、先划清边界:MCP 工具面与 SDK 服务面

启元官方 SDK 的能力以** ROS 2 服务和话题**的形式提供,服务名形如 /aimdk_5Fmsgs/srv/SetMcAction,话题名以 /aima/ 开头。这是"服务面":面向机器人开发者,精确、稳定、但要求调用方自己写好每一步。

MCP 服务器做的是把这层服务面翻译成"工具面":每个工具一个动词级的名字(set_posture、speak、walk),参数和前置条件写进工具描述,随协议下发给模型。8 个工具对应 6 个官方服务加 2 个话题,映射,不做任何能力裁剪。

这样分层的好处直接体现在维护上:官方 SDK 升级,工具层跟着改字段就行;换客户端(Claude Code、Cline、Cherry Studio 都支持 MCP),机器人侧一行代码不用动。真机与 mock 也走同一条线。

二、环境搭建:四步跑起来

组件版本(本文实测)
操作系统Ubuntu 22.04
ROS 2Humble
Python3.10.12
MCP 库fastmcp 4.1.4 / mcp 2.3.0
官方 SDKprimebot/q1-sdk(用到 aimdk_msgs 消息包)

第一步,装 MCP 库:

pip3 install --user fastmcp==4.1.4 mcp==2.3.0

第二步,克隆官方 SDK 并构建消息包:

git clone https://atomgit.com/primebot/q1-sdk.git ~/m0-q1-sdk
cd ~/m0-q1-sdk && source /opt/ros/humble/setup.bash
colcon build --packages-select aimdk_msgs

第三步,组工作区。把官方 aimdk_msgs 和本项目的 q1_mcp 包放进同一个 colcon 工作区构建:

mkdir -p ~/ws-mcp/src && cd ~/ws-mcp/src
ln -s ~/m0-q1-sdk/aimdk_msgs aimdk_msgs
ln -s ~/q1-mcp-server q1_mcp        # 本项目克隆自文末仓库
cd ~/ws-mcp && colcon build && source install/setup.bash

第四步,起机器人侧。有真机接真机;没有真机,用项目内置的 mock:

git clone https://atomgit.com/m0_63947499/q1-mcp-server.git ~/q1-mcp-server 
cd ~/ws-mcp
source /opt/ros/humble/setup.bash
colcon build
source install/setup.bash
python3 -m q1_mcp.fake_q1

三、写 MCP 服务器:8 个工具的正确姿势

fastmcp 库把 MCP 协议细节包干净了,剩下真正影响使用效果的是工具设计。我的经验是三条:

名字动词化,描述写清前置条件。 模型选工具靠 docstring,工具描述就是给模型看的说明书。比如预设动作工具的描述里明确写着"机器人处于 store 姿态时会返回 -1004 拒绝码,需先调 set_posture(“stand_up”)",这句话在第七节的实测里直接救了场。

参数用字符串枚举而不是裸数字。 官方预设动作用整数枚举(挥手 Q_WAVE_HAND=3004,跳舞 Q_DANCE_A=3046),工具层接收 motion: str,内部查表转换。模型面对 “wave” 的出错率远低于面对 3004。

返回值必须是 JSON 可序列化的纯结构。 这是个实测踩出来的坑:工具函数直接返回 ROS 服务原始响应对象,fastmcp 报 “Unable to serialize unknown type”。正确做法是把响应提炼成 {"ok": bool, "code": int, "detail": str} 的统一结构。

核心实现比想象的短。服务器主体是一个 FastMCP 实例加 8 个装饰器函数,每个函数转发给 RobotClient:

mcp = FastMCP("q1")

@mcp.tool
def play_preset_motion(motion: str) -> dict:
    """播放官方预设全身动作。可用值: wave(挥手), dance_a/b/c(跳舞), make_heart(比心) 等。
    机器人处于 store 姿态时会返回 -1004 拒绝码, 需先调 set_posture("stand_up")。"""
    return _client.play_preset_motion(motion)

def main():
    setup()          # rclpy.init() + RobotClient(自带后台线程)
    try:
        mcp.run()    # stdio 传输
    finally:
        teardown()

**有一个技术点要注意:**MCP 的 asyncio 事件循环与 rclpy 的回调线程如何共存。我的做法是 RobotClient 自带一个 SingleThreadedExecutor 后台线程收服务响应,MCP 工具函数在它之外同步调用。关闭顺序必须是 executor.shutdown、join、destroy_node,顺序反了会 core dump,这是排坑表第一条。

另外,官方接口的响应有两种形态,解析路径不一样,写错一层拿到的一直是 -3 这种假错误码:

  • SetMcAction / SetMcPresetMotion 返回 CommonTaskResponse,状态码在 resp.response.header.code
  • PlayTts / PlayEmotion / LedStripCommand 返回 CommonResponse,状态码在 resp.response.header.header.code(两层 header 嵌套)

四、没有真机怎么办:一个诚实的 mock

本文无真机,机器人侧用 fake_q1 节点顶替,它提供与真机同名的** 6 个服务和 2 个话题**,响应结构完全按官方 srv 定义填充。mock 的行为规则只保留一条,却是精心挑的:

def _on_preset(self, req, resp):
    name = PRESET_NAMES.get(req.motion.value, str(req.motion.value))
    if self.posture == "store":                 # 初始休眠姿态
        resp.response.header.code = -1004       # 官方拒绝码
        return resp
    resp.response.header.code = 0
    resp.response.task_id = self._task()
    return resp

机器人处于收纳姿态(STORE_DEFAULT=1001,即出厂休眠态)时,动作、语音、表情、灯带四类请求全部返回 -1004。这个码不是我编的,官方**《接口说明.md》**第 531 行原文:“机器人姿态不具备切换目标 action 的能力”。保留这条规则,是为了让"模型如何面对拒绝"这件事变得可测。

五、接入客户端:一段 JSON 的事

MCP 客户端侧零代码。以 Claude Code 为例,项目目录放一个 .mcp.json:

{
  "mcpServers": {
    "q1": {
      "command": "bash",
      "args": ["-c",
               "source /opt/ros/humble/setup.bash && source ~/ws-mcp/install/setup.bash && exec python3 -m q1_mcp.server"]
    }
  }
}

首次连接时客户端会请求一次确认,批准后这个项目就记住了这台机器人服务器,之后随用随连。

值得一提的是模型后端。本文的 Claude Code 接的是国产 GLM 模型,工具调用全程稳定。也就是说这条链路不依赖某家特定模型:客户端认 MCP,模型能做工具调用,机器人就能被自然语言指挥。

一句话查机器人电量

六、实测三幕

以下数据全部来自仓库 notes/data.md,每条可复现(脚本随仓库提供)。

幕一:工具基准

进程内客户端逐工具调用,每项 3 次:

工具场景返回码平均往返
set_posture成功09 ms
play_preset_motion / speak / play_emotion / set_led成功03 ms
get_battery / get_status成功02-3 ms
walk成功0504 ms(含 0.5 s 行走时长)
四个动作类工具休眠拒绝-10043 ms

注意口径:这是进程内测试的往返耗时,真实 stdio 客户端跨进程会略高,量级不变。

幕二:多步任务

指令:“让机器人完成一套迎宾流程:站起来,挥挥手,说’你好呀,我是启元Q1’,最后跳个舞。”

模型执行序列,四步全对:

1. set_posture(stand_up)
2. play_preset_motion(wave)
3. speak("你好呀, 我是启元Q1")
4. play_preset_motion(dance_a)

5 轮对话,CLI 计费 0.16 美元。一个细节:**指令里说"站起来",但模型的总结里专门解释了为什么第一步是站立,“这一步也确保后续动作不会因 store 姿态被拒绝”。**它读了工具描述里的前置条件,并提前规避了错误。

幕三:错误恢复,两种打开方式

第一幕**(自然指令)**:只说"让机器人跳个舞"。模型先调 get_status 探测到休眠,然后唤醒、切灯效、跳舞,全程零拒绝。它甚至自作主张加了彩虹灯效,算是个没写在需求里的即兴发挥。

第二幕**(强制直调)**:要求"直接调用跳舞工具"。这次撞上了 -1004:

1. play_preset_motion(dance_a)   → 返回 -1004,被拒绝
2. set_posture(stand_up)         → 模型自主决定唤醒
3. play_preset_motion(dance_a)   → 成功

机器人侧日志独立佐证了同一条轨迹:

[WARN] [fake_q1]: REJECT preset(dance_a) -> code -1004 (posture=store)
[INFO] [fake_q1]: SetMcAction -> stand_up (task 1)
[INFO] [fake_q1]: preset(dance_a) OK (task 2)

没有人写过"被拒绝后先唤醒"这条规则。模型的行为来自两处信息:工具描述里的前置条件,加上 -1004 的返回码本身。这正是 MCP 模式与规则引擎的分水岭,处理意外的逻辑从代码搬进了模型。

需要说明:大模型行为有随机性,上述序列是一次实录,重跑可能细节不同(比如它可能像第一幕那样先探测再行动)。但恢复能力本身不依赖运气:前置条件写在工具描述里,拒绝码原样返回给模型,这两处信息在,模型就有依据自己走出死胡同。

七、排坑表

坑现象解法
rclpy 与 MCP 共存的关闭顺序退出时 core dumpexecutor.shutdown → join → destroy_node,反序必炸
工具返回 ROS 原始对象“Unable to serialize unknown type”工具层统一返回纯 dict,detail 用字符串
stream-json 输出Error: requires --verboseclaude -p ... --output-format stream-json --verbose,stdin 显式 < /dev/null
pytest 三体冲突系统自带 6.2.5 加载 anyio 插件即崩;升级后 launch_testing 又不兼容pip3 install --user -U pytest + 运行时 PYTEST_DISABLE_PLUGIN_AUTOLOAD=1
pkill 自杀命令行自身含进程名关键词,把自己 shell 杀了模式加正则括号:pkill -f 'q1_mcp[.]fake_q1'
双重 rclpy.init测试会话复用 context 报 RuntimeErrorsetup() 里 if not rclpy.ok() 再 init

八、边界与真机迁移

如实交代本文的边界:机器人行为来自 mock,它的响应结构按官方接口定义实现,但真机行为以官方固件为准;电量 82%、电压 44V 是 mock 设定值;幕一延迟是进程内口径。这些在文中相应位置都已标注。

迁移到真机只差一步:关掉 fake_q1,让主机与机器人同处一个 ROS 2 域,工具层与客户端零改动。反过来,这套 mock 也意味着任何人不需要两万块的硬件就能把整条链路跑通,包括那个"被拒绝后自己爬起来"的瞬间。

结语

把机器人封装成 MCP 工具后,最直观的变化是开发交互的粒度:从"写代码调接口"变成"说人话等结果",而处理意外的能力从硬编码规则转移给了模型。对于启元 Q1 这样开放完整 SDK 的平台,这是把开发门槛从机器人工程师降到任何会用大模型的开发者的那条路。

仓库地址(含 mock、测试、数据脚本):https://atomgit.com/m0_63947499/q1-mcp-server

更多启元机器人开发资源与文档,见启元机器人开发者社区:https://dev.primebot.com/

Logo

DAMO开发者矩阵,由阿里巴巴达摩院和中国互联网协会联合发起,致力于探讨最前沿的技术趋势与应用成果,搭建高质量的交流与分享平台,推动技术创新与产业应用链接,围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐