最近在调试小智的 MCP 工具时我遇到一个特别容易让人误判的现象工具返回了true我满心以为硬件动作已经完成结果设备根本没动。后来我翻日志才发现这个true只是说MCP Server 成功收到了请求函数不报错地返回了并不等于硬件已经执行到位。这个坑在智能硬件接入 MCP 的场景里非常常见今天就从MCP 工具返回 true这个现象说起聊聊 MCP 协议里工具返回值的真实语义以及怎么设计才能让 AI 真正确认硬件动作完成。如果你是正在做小智 AI 控制台、小智 AI 服务器镜像或者任何用 MCP 协议去控制电机、灯、机械臂的开发者这篇文章应该能帮你省下好几个晚上的排错时间。我会从链路原理、状态拆解、实操改造、问题排查四个部分展开尽量把每一步都说明白哪怕你刚接触 MCP 也能直接照着做。1. 先搞清楚MCP 工具返回值的真实身份1.1 一次 MCP 工具调用到底走过了什么路很多人把 MCPModel Context Protocol理解成AI 直接调用我的函数这句话方向没错但太笼统了。一次完整的 MCP 工具调用中间隔着至少四个角色AI 模型、MCP Host、MCP Server、硬件驱动。以你用小智控制台接一个智能灯为例用户说把灯打开模型会决定调用一个名为turn_on_light的工具这个调用以 JSON-RPC 的形式发给 MCP HostHost 再根据工具名转发给注册好的 MCP Server最后你的工具函数才真正执行。也就是说当 MCP 工具函数执行完并返回一个值这个值要先变成 JSON 字符串再沿着 Server - Host 的路径传回给模型。模型看到的不是一个 Python 的True而是一个 JSON 里的true。所以严格说工具返回true只是这个函数体走完了没有抛异常按约定返回了一个布尔值。至于函数体里到底做了什么事、硬件到底动没动MCP 协议本身完全不关心。这也是为什么很多 SDK 会鼓励 MCP 工具返回结构化对象而不是裸布尔值。FastMCP、官方 Python SDK 都支持返回 dictMCP 会自动序列化成 JSON。返回true在语法上没问题但在语义上丢失了太多信息。你只是告诉 AI调用成功了但没有告诉它成功到什么程度。1.2 true 的本意是函数执行成功不是硬件完成我在小智的硬件控制层里最开始写的工具函数就是这样mcp.tool() def move_servo(angle: int) - bool: 将舵机转到指定角度 hardware.send_command(fSERVO:{angle}) return True看起来没毛病开个串口发送指令然后返回 True。但问题在于hardware.send_command只是把数据写进了串口缓冲串口驱动什么时候把数据发出去、舵机电路有没有正确执行、角度是否真的到位这个函数完全不知道。更麻烦的是串口发送失败时如果代码没检查返回值这个函数还是会返回 True。这里的true实际上只代表了我调用了发送函数没有立刻崩溃。用专业一点的话说这叫指令受理成功而不是动作完成成功。你调用一个 HTTP API 时服务器返回 200也只能代表请求被接收了不能代表业务处理完了。MCP 工具返回 true 是一样的道理本质上只是一个请求已受理的信号。我自己调试小智的 MCP Server 时还在工具函数里特意加了一句日志把返回前的状态打出来mcp.tool() def move_servo(angle: int) - bool: result hardware.send_command(fSERVO:{angle}) print(f[MCP] servo command sent, result{result}) return bool(result)结果发现send_command返回的是串口写入字节数哪怕只写了 0 字节在 Python 里bool(0)是 False但只要字节数大于 0返回 True。可这能代表舵机动了吗不能。它只代表串口驱动收到了这几个字符。1.3 为什么这么容易踩坑同步思维碰上异步硬件做软件的人特别容易默认函数返回了事情就做完了但硬件世界是异步的。你把指令发给电机驱动器驱动器需要时间执行你把开灯指令发给继电器继电器线圈吸合需要几毫秒灯丝点亮还需要时间。更不用说那些带缓启动、带减速过程的电机了执行时间可能是秒级甚至更长。MCP 工具调用本身是同步的AI 模型会一直等着你的工具返回结果。如果你在工具函数里同步等待硬件真正完成那就要阻塞住这个调用。比如舵机转到 180 度需要 2 秒如果你在工具里time.sleep(2)等它到位MCP 调用就会挂起 2 秒。这在简单场景下没问题但遇到机械臂多关节联动、一次调用要执行好几秒的任务模型那边很容易超时。所以很多人图省事工具函数里只把指令发出去立刻返回 True。这就是同步思维碰上异步硬件的典型妥协函数是同步的但我没时间等硬件那我只能撒谎说已经完成了。这个谎言短期能跑通 demo长期就是各种诡异 bug 的来源。AI 模型会根据你的返回结果继续规划下一步它以为动作完成了马上让用户去做下一件事结果硬件还在半路整个交互体验就全崩了。2. 把完成拆成三个阶段你就明白了2.1 指令下发、动作执行中、动作完成要彻底搞明白 true 够不够用我建议你先把硬件动作的状态拆成三个阶段SUBMITTED、RUNNING、COMPLETED这三个阶段里的任意一个都可能被一个粗糙的工具函数用 true 带过去。SUBMITTED指令已经成功写入硬件控制链路比如串口数据发出去了I2C 写入完成了。这时候硬件还没开始动作或者刚开始动作。RUNNING硬件正在执行动作比如电机正在转动、舵机正在移动、机械臂正在抓取。COMPLETED硬件已经执行完成并且你能确认它到达了目标状态比如编码器反馈的角度到位了电流检测显示继电器吸合了传感器读到了目标数值。所以说MCP 工具返回 true最准确的说法是达到了 SUBMITTED 状态。即使你的硬件 API 是同步的、调用后确实执行完了你也需要在工具函数里拿到硬件反馈状态再做判断而不是默认返回 true。比如你调一个支持阻塞到位的电机库它在执行完才返回那你这时返回 true 才有意义否则一律按指令已下发处理。2.2 三种最常见的伪完成现场我见过特别多的 MCP 工具返回 true但硬件实际没完成的现场总结下来主要是这三种。第一种是指令根本没发出去的伪完成。工具函数里调了一个硬件 API但这个 API 内部出错时只是打印日志没有往上抛异常也没有返回错误码。函数走到 return True外面完全看不出来其实串口很早就断开了。这类问题最隐蔽因为你只看 MCP 返回结果会觉得一切正常。第二种是指令发出去了硬件没执行完的伪完成。这个最典型就是前面说的异步执行。你发了一个MOTOR:START指令电机需要 5 秒才能转到位但你的工具函数 10 毫秒就返回了 true。AI 模型立刻告诉用户已经转到位了实际上电机还在嗡嗡响。等电机到位时用户可能已经在问下一件事了。第三种是硬件执行出错了但工具没感知到的伪完成。比如机械臂去抓一个物体抓空了但机械臂控制器只上报了移动命令执行完毕没有上报夹爪内有没有物体。如果你的 MCP 工具只确认了移动完成没有去查夹爪传感器它依然会返回 true。这种完成是片面的只完成了动作没完成目标。所以不要迷信 true要从硬件反馈闭环来定义完成。没有反馈闭环的 true本质上都是盲猜。2.3 从 MCP Server 到硬件驱动每一环都可能丢状态一个完整的链路里状态可能在你没注意的环节悄悄丢掉。我调试小智控制台对接摄像头云台时就是从这条链路上找问题AI 模型 - MCP Host - MCP Server - WebSocket 网关 - 嵌入式设备 - 电机驱动芯片 - 编码器反馈。如果只看 MCP 工具函数它确实向 WebSocket 网关发了一条消息并拿到了 ACK于是返回 true。但仔细看WebSocket 网关只是把这条消息转给了嵌入式设备。嵌入式设备可能断电了、网络断了、或者正在执行上一个任务这条消息根本没到电机驱动芯片。网关收到 ACK 只能说明网关收到了消息不能说明设备收到了。设备收到也不代表电机执行了电机执行了也不代表编码器计数到位了。所以你看从软件到硬件每一层都有可能把完成状态吞掉。这就带出一个设计原则一个 MCP 工具要敢返回硬件动作完成它必须拿到至少一层能反映硬件真实状态的反馈。可以是设备上报的完成事件可以是传感器读值也可以是电机驱动器的到位信号。如果拿不到请老实返回已下发待确认。3. 实操改造让小智的 MCP 工具返回真实完成状态3.1 方案选型轮询、回调还是事件推送既然不能直接返回 true那我们怎么才能确认硬件动作真正完成有三种常见方案轮询、回调、事件推送。轮询是最简单直接的。MCP 工具不负责等待它把任务 ID 返回给模型模型再调用另一个查询工具不停去查这个任务的状态直到查询结果为COMPLETED。适合硬件侧没有主动上报能力的情况你用查询指令去读状态寄存器、读传感器都能做。缺点是白白占用模型多次工具调用而且查询间隔要控制好太频繁浪费资源太慢又不够实时。回调方案是 MCP Server 把自己留成一个 Web 服务给底层硬件一个回调地址。硬件执行完以后通过 HTTP 请求回调 ServerServer 更新任务状态为 completed。这个方案实时性好但需要硬件端或者网关支持回调而且涉及内网穿透、防火墙配置在本地调试时特别麻烦。事件推送本质上和回调类似只是把 HTTP 换成了 WebSocket、MQTT 这类长连接。当前很多智能硬件网关本身就是用 MQTT 上报状态的。如果小智硬件设备已经接入了 MQTT那么 MCP Server 订阅相应 topic收到finished事件时更新任务状态这是最干净的。但前提是设备端要真的会发这个事件而不是发一个笼统的 ACK。我建议你按硬件能力来选。如果硬件已经具备状态反馈接口优先用轮询因为它实现最简单而且不依赖网络环境。如果硬件能主动上报就上 MQTT/WebSocket 事件体验更好。下面我给一个轮询方案的完整示例。3.2 给每个动作发一张任务单task_id我不管用哪种方案都强烈建议你先引入一个 task_id任务 ID。每个硬件动作在被 MCP 工具接收时立刻生成一个唯一 ID并把这个 ID 作为返回结果的一部分。后面查状态、确认完成、对账全靠这个 ID。为什么要这么做因为一次硬件动作从开始到结束可能隔几秒甚至更久你不能靠角度 90 度这种参数去区分是不是同一次任务。task_id 就是这次动作的身份证。你还能在 Server 里维护一张任务表记录每个 task_id 的状态变化历史、时间戳、错误信息排错的时候会非常舒服。生成 task_id 不需要太复杂时间戳加递增序号就行。比如import time _task_seq 0 def new_task_id(prefix: str task) - str: global _task_seq _task_seq 1 return f{prefix}_{int(time.time() * 1000)}_{_task_seq}这样做出来的 ID 在程序生命周期内不会重复。如果你有多个 MCP Server 实例还可以在前面加个实例名避免并发重复。3.3 代码改造示例FastMCP 下的 move 工具我假设你的硬件是一台能接收串口指令、并且能查询运动状态的电机。用 Python 和 FastMCP 来演示怎么把返回 true改成返回任务状态。先看一个改造后的控制器类它维护任务字典模拟硬件异步执行from fastmcp import FastMCP import time import threading mcp FastMCP(xiao_zhi_hardware) class MotorController: def __init__(self): self._tasks {} self._lock threading.Lock() def submit_move(self, position: int, duration: float) - str: task_id new_task_id(move) with self._lock: self._tasks[task_id] { status: SUBMITTED, target_position: position, duration: duration, create_time: time.time(), error: None, } # 模拟把指令发给硬件并启动一个线程模拟异步执行 threading.Thread(targetself._simulate_execution, args(task_id, duration), daemonTrue).start() return task_id def _simulate_execution(self, task_id: str, duration: float): # 这里在真实项目里会阻塞等待硬件反馈 time.sleep(duration) with self._lock: if task_id in self._tasks: self._tasks[task_id][status] COMPLETED def get_status(self, task_id: str) - dict: with self._lock: task self._tasks.get(task_id) if not task: return {status: NOT_FOUND, error: task not found} return dict(task) controller MotorController() mcp.tool() def move_motor(position: int, duration: float 1.0) - dict: 移动电机到指定位置。该工具会立即返回任务ID执行完成后状态会变为COMPLETED。 Args: position: 目标位置整数值 duration: 预计执行时长秒 task_id controller.submit_move(position, duration) return { success: True, task_id: task_id, status: SUBMITTED, message: 移动指令已受理请调用 query_motor_status 查询执行结果 } mcp.tool() def query_motor_status(task_id: str) - dict: 查询电机移动任务的状态。 Args: task_id: move_motor 返回的任务ID return controller.get_status(task_id)在这个例子里move_motor的返回值已经不是裸 true 了而是一个结构化对象包含了task_id和当前状态SUBMITTED。AI 模型看到这个返回值就能明确知道动作还没有完成我需要再查询。模型侧的调用逻辑大概是先调move_motor拿到 task_id然后循环调query_motor_status直到状态变成COMPLETED。为了不让模型乱猜我建议你在工具描述里写清楚查询状态为 COMPLETED 时表示动作完成SUBMITTED/RUNNING 表示还在执行中。这样模型就知道要等。如果你还是希望 MCP 工具本身能阻塞到完成再返回也可以实现一个move_motor_and_wait工具内部轮询状态直到 complete 或超时再返回。这样业务上更直观但要注意不要把超时时间设置得太长免得模型等待太久。我一般控制在 30 秒以内。3.4 对 AI 模型侧的提示词与工具描述优化很多时候工具本身已经返回了任务状态但 AI 模型还是告诉你已经完成了原因出在工具描述写得不够清楚。MCP 工具的描述是给模型看的重要上下文你要明确告诉它这个工具是立即返回还是等待完成。比如move_motor的描述里我特意写了立即返回任务IDquery_motor_status的描述里写了查询任务状态。这能让模型意识到需要多一步查询。还可以在系统提示词里加一句调用硬件控制工具后必须确认状态为 COMPLETED才能向用户报告完成。我在小智控制台里就加过这样一条规则效果很明显模型不再急着说好了而是会回答正在移动请稍等然后继续查询。4. 常见问题与排查技巧实录4.1 明明返回 true硬件却没有动先查哪一环这种问题我在群里见过太多次了。排查顺序我一般建议从底层往外走先看硬件本身能不能独立工作比如用串口助手直接发指令看设备动不动。如果设备不动说明问题在 MCP 工具和硬件之间的通信层比如串口权限、端口被占用、WiFi 网络不通。如果设备动说明硬件正常再去看 MCP 工具调用时是否传对了参数、是否真的调到了硬件 API。有个特别容易忽略的坑MCP Server 进程启动时可能没有打开硬件端口的权限但代码里捕获了异常然后还是返回了 true。所以排查时先在 MCP Server 日志里找PermissionError、SerialException、ConnectionRefused这类关键词不要只看 MCP 返回的布尔值。我就是靠这个找到了问题我的小智 MCP Server 以 systemd 服务运行时/dev/ttyUSB0的权限不对连串口都打不开但旧代码里send_command内部吞掉了异常表面一切正常。另外如果 MCP Server 是通过 HTTP 远程部署的硬件控制指令走网络链路一定要确认网络延迟和丢包情况。我遇到过 WebSocket 网关偶发断了重连重连期间 MCP 工具调用返回 true 了但指令已经丢失。后来我在代码里检查了网关是否处于连接状态不连接就直接返回错误才把问题压住。4.2 返回 false 但硬件还在跑问题出在哪有朋友反过来说我的 MCP 工具已经返回 false 了结果硬件还在继续执行这不是更危险这种情况一般是因为工具函数里先向硬件发了一条不能中断的指令然后因为某个后续步骤出错返回了 false。比如你发了一个电机开始转动的指令电机已经动起来了紧接着你查状态时超时了函数就 return False。但电机没有收到停止指令自然还在转。这暴露了一个设计问题不要把指令是否成功发出和执行结果是否成功混在一个返回值里。处理办法是工具函数里在发指令之前先检查参数和硬件状态检查不过就直接返回 false不要发指令发完指令之后即使后续状态查询失败也只应返回查询失败而不是 return False。更稳妥的是给硬件一个安全策略比如执行任何长时间动作时先发送开始再发送结束/停止如果整个过程出错至少补发一个停止指令。4.3 超时、幂等、并发三个绕不开的深坑先说超时。如果你的 MCP 工具在函数内部阻塞等待硬件完成一定要设置超时。FastMCP 本身没有强制限制工具执行时间但 AI 模型侧往往有自己的 request timeout。你在工具里干等 60 秒模型早断了。我的经验是单次硬件动作同步等待不超过 20-30 秒超过就要用任务 ID 查询模式解耦。再说幂等。模型在生成回复时可能出现重复工具调用或者你前端重试机制导致同一个开关指令被发两次。硬件动作不一定是幂等的比如开灯重复执行没问题但电机转到 90 度重复执行可能因为已经到 90 度而不动也可能因为参数理解问题又转一圈。所以任务 ID 的另一个作用就是去重同一个 task_id 只允许执行一次。最后是并发。多个 MCP 工具同时操作同一个硬件设备特别是如果你给多个 AI 客户端共用一个小智 MCP Server并发冲突的概率非常高。两个指令同时往串口写数据会交错导致解析错误。解决方法是给硬件发送模块加一个全局锁同一时间只允许一个工具函数进入发送区。代码里可以用threading.Lock或者asyncio.Lock简单粗暴但有效。4.4 排查清单速查表现象可能原因排查方向解决建议工具返回 true硬件没动硬件 API 吞异常查看 MCP Server 日志和硬件连接状态检查串口权限、网络连接让异常向上抛工具返回 true硬件动了一部分指令下发后立即返回查设备是否支持状态反馈引入 task_id 和轮询/回调机制工具返回 false硬件还在动发出指令后才发现错误检查指令发送与错误判断顺序先验证参数再发指令出错时补发停止指令模型总说完成了但查状态还没完成工具描述没提示需要二次确认查看模型调用链和工具描述在描述和提示词中明确要求查询 COMPLETED多次调用出现重复动作缺少幂等控制看是否同一 task_id 重复执行加任务表判断去重并发调用导致串口数据乱码多个工具同时写串口看日志时间戳与线程信息加全局锁串行化硬件发送这个小表基本覆盖了我在小智 MCP 项目里遇到的高频问题你可以把它贴在项目文档的 FAQ 里后面别人踩坑了直接查。最后再分享一个小技巧无论你的 MCP 工具设计得多完善在调试阶段都尽量把每一步返回值和硬件状态日志打印出来然后串起来看一遍完整调用链。我习惯在 MCP Server 启动时加一个--debug参数把工具入参、返回结果、任务状态变化都输出到单独的文件。这样一旦出现返回 true 但硬件没动这种问题不用靠猜直接拉日志就能定位。等你把完成状态真正做实了会发现在小智控制台上和 AI 对话时它的回答靠谱多了——因为它不再把一个空头支票式的 true 当成事实了。
