纸飞机调试助手文档 ComAssistant Docs

通过MCP让AI控制软件

通过MCP让AI控制软件

概述

纸飞机调试助手内置本地 Control HTTP API，并通过 MCP 服务把这些能力暴露给 Cursor 等支持 MCP 的 AI 客户端。它不是单纯的“文档问答”，而是让 AI agent 在本机受控访问纸飞机：查询串口、切换通信模式、打开设备、收发数据、读取窗口文本、管理命令面板、操作自由工作区、查询绘图数据等。

本地 Control API 默认关闭，需要用户主动开启；服务仅监听本机地址，并使用 Bearer Token 鉴权。

启用方式

待补充：MCP 服务设置截图

常规方式：

  • 打开纸飞机调试助手。
  • 完成授权验证。
  • 进入 设置 -> MCP 服务设置。
  • 勾选 启用本地 MCP HTTP 服务。
  • 记录服务地址和 Device ID。Device ID 用作 Bearer Token。
  • 释放并部署 MCP Python 服务。
  • 在 AI 客户端的 MCP 配置中填写 Python MCP 服务和环境变量。
  • 部署完成后在功能菜单下启用MCP HTTP服务

    • AI 客户端配置要点

    待补充：AI 客户端 MCP 配置截图

    MCP 服务需要知道两个环境变量：

    COMASSISTANT_URL=http://127.0.0.1:17340
COMASSISTANT_TOKEN=<软件中显示的 Device ID>

    推荐先做健康检查：

  • diag_ping_comassistant()（或 GET /v1/health）：确认纸飞机 Control API 可访问。

    • diag_ping_mcp 仍可通过 mcp_invoke 调用（冷工具），仅返回 MCP Python 进程身份，一般不单独使用。

    如果 MCP 客户端能启动但工具报错，优先检查 COMASSISTANT_URL、COMASSISTANT_TOKEN、软件是否已授权、MCP HTTP 服务是否已启用。

    可自动化的功能

    MCP 能力覆盖以下常见场景：

  • 通信：串口列表、串口打开/关闭、网络连接/断开、HID 打开/关闭。
  • 收发：直发数据、读取接收缓冲、点击发送按钮、读写发送区。
  • 显示：HEX 显示、HEX 发送、文本编码、回车风格、窗口文本读取。
  • 协议：读取当前协议、切换绘图协议、获取协议说明。
  • 命令面板：读取命令树、创建组、添加命令、移动命令、发送单条或整组。
  • 可视化：绘图窗口、曲线数据、数值显示器、频谱图、图像调试状态。
  • 工作区：列出工作区、创建控件、移动控件、更新控件、读取网格信息。
  • 文件与记录：文件发送、实时数据记录、保存原始数据、保存显示数据。
  • 应用控制：窗口置顶、标题后缀、调试日志、24 小时运行模式。

    • 使用边界

    AI agent 操作硬件时要区分三类发送方式：

  • device_send(data, format)：直接向设备发数据，不经过发送区 UI。
  • send_area_set(text) + send_button()：写入发送区，再模拟点击发送按钮。
  • command_panel_send_command() / command_panel_send_group()：模拟命令面板发送。

    • 需要复现用户界面行为时，优先选择 UI 对应接口；需要精确发一包数据时，选择直发接口。不要把三者混用，否则容易出现 HEX 发送状态、换行规则或命令面板延时与预期不一致。

    安全建议

  • Control API 只应暴露在本机，不要映射到公网。
  • 不要把 Device ID / Bearer Token 写进公开仓库。
  • AI 修改 Lua 脚本前，应先读取脚本头部说明，不要删除内置绑定函数。
  • 长时间自动化测试建议开启实时数据记录，并确认输出目录空间充足。

    • 常见问题

    为什么菜单里的 MCP 服务是灰色或不可用？

    MCP HTTP 服务需要授权后使用。先完成在线账户登录或离线授权验证，再打开 MCP 服务设置。

    AI 报 HTTP 502，浏览器打开健康接口却是 unauthorized？

  • 浏览器裸访问 /v1/health 得到 {"ok":false,"error":"unauthorized"} 表示 HTTP 服务已在听（401），不是服务挂了。
  • 纸飞机 不会返回 502；AI/MCP 看到的 502 多半是 Token/代理/端口问题。
  • 让 AI 调用热工具 diag_connectivity()（或先 diag_ping_comassistant），按返回的 cause / next_steps 排查。
  • 核对 MCP 环境变量 COMASSISTANT_TOKEN 是否等于设置里的 Device ID，改完后重启 MCP。

    • MCP 和 Lua 怎么分工？

    Lua 更适合在纸飞机内部处理收发钩子、过滤、自动应答等实时逻辑；MCP 更适合让外部 AI agent 编排调试流程、读写配置、查询状态和整理数据。

    > 本文为 AI 辅助生成内容