Embedded MCP

Universal Embedded AI Infrastructure & Serial over TCP Gateway for Antigravity & AI Agents

Python 3.12+ Package Manager uv Code Style ruff Tests Passing

1. 项目简介 (Overview)

在嵌入式与机器人开发中，传统物理串口（COM / UART）存在以下核心痛点：

Windows 串口强排他性：一个 COM 口被上位机、VOFA+ 或终端打开后，AI Agent、自动化测试与 CLI 工具均会遭遇拒绝访问（WinError 5）。
多端并发写入冲突：多个 AI Agent 或测试脚本并发操作同一串口时，总线字节交错撕裂，回显混淆。
跨 Chunk 解码乱码：单片机输出中文或多字节 UTF-8 日志时，若按数据包切割解码，汉字极易损坏变成 \ufffd。
高频遥测淹没交互：单片机持续以 50Hz/10Hz 吐出红外或电机遥测流时，命令回执会被瞬间淹没。

Embedded MCP 通过 Serial over TCP Gateway 架构，将物理串口抽象为双端口微服务网络：

5001 纯数据透传端口 (Raw Sniffer)：PuTTY / VOFA+ 零配置直连监听波形与日志，无锁多读。
5101 JSON-RPC 控制端口 (Control & Multiplexing)：为 Antigravity AI Agent、自动化脚本与 CLI 提供结构化管控。
方案二：微秒级原子事务排队池 (Transaction Multiplexing)：并发下发命令无需手动申请锁，自动在异步 FIFO 队列中借还租约并剥离回显。
单调偏移防乱码环形缓冲区 (ChunkedRingBuffer)：在 Raw Bytes 空间反向定位边界，多字节 100% 完整，高频遥测下精准捕获命令回执。

2. 系统架构 (Architecture)

┌──────────────────────────────────────────────────────────┐
│             Antigravity Agent / Claude Client            │
└────────────────────────────┬─────────────────────────────┘
                             │ stdio (JSON-RPC 2.0)
                             ▼
┌──────────────────────────────────────────────────────────┐
│                   embedded-mcp Server                    │
│   (board_list, board_status, serial_tail, serial_exchange)│
└────────────────────────────┬─────────────────────────────┘
                             │
                  ┌──────────┴──────────┐
                  ▼                     ▼
     JSON-RPC 2.0 (Port 5101)    Raw Stream (Port 5001)
     [Control & Leased Writes]   [PuTTY / VOFA+ Sniffer]
                  │                     ▲
                  └──────────┬──────────┘
                             ▼
┌──────────────────────────────────────────────────────────┐
│                  SerialGateway Engine                    │
│  ├── LeaseArbiter (FIFO Transaction Multiplexing Queue)  │
│  ├── ChunkedRingBuffer (Monotonic Byte Sliced Safe Buffer)│
│  └── SerialWorker (Dedicated Thread, Win32 Auto-Heal)    │
└────────────────────────────┬─────────────────────────────┘
                             │ pyserial (dtr=None, rts=None)
                             ▼
               COM4 (ATK-HSWL-CMSIS-DAP 04D8:00DF)

3. 环境准备与全局安装 (Installation)

本项目遵循 uv 环境规范，禁止使用传统 pip。

(1) 安装依赖与构建虚拟环境

在项目根目录（e:\WorkSpace\embedded-mcp）执行：

uv sync --extra dev

(2) 安装为全局命令行工具 (任选一种)

推荐方法：通过 uv tool 全局链接
```
uv tool install --editable . --force
```
全局 PATH 支持：若当前终端未包含 ~/.local/bin，系统已在全局 PATH（C:\Users\Administrator\.gemini\antigravity\bin\）配置了二进制包装器，可直接在任意目录（如 E:\Chassis control）执行 embedded-mcp。

4. 板卡配置规范 (Board Configuration)

所有板卡定义存放于 config/boards/*.json 中，系统在任何目录下运行都会自动定位到本目录，支持自动热重载。

示例配置 (`config/boards/board_a.json`):

{
  "id": "board_a",
  "name": "ATK-HSWL-CMSIS-DAP Board",
  "adapter": "generic",
  "match": {
    "vid": 1240,
    "pid": 223,
    "serial_number": "ATK_20190528",
    "port": "COM4"
  },
  "serial": {
    "baudrate": 115200,
    "bytesize": 8,
    "parity": "N",
    "stopbits": 1,
    "dtr": null,
    "rts": null,
    "timeout": 0.05,
    "gateway": {
      "bind": "127.0.0.1",
      "data_port": 5001,
      "control_port": 5101
    }
  },
  "metadata": {
    "description": "Robot chassis main control board",
    "controller": "STM32",
    "shell_prompt": "dock:/$ "
  }
}

match：支持基于 vid / pid、serial_number 或显式 port 自动过滤并热插拔寻址，自动过滤 Windows 虚假 ACPI 端口。
dtr: null, rts: null：严格杜绝 Windows 串口打开时拉低引脚意外复位单片机。

5. 命令行使用指南 (CLI Manual)

你可以在系统中的任何目录（例如 E:\Chassis control 或任意项目文件夹）打开终端直接使用：

(1) 硬件与板卡发现

# 列出系统中所有已注册板卡与当前匹配的物理端口
embedded-mcp board list

# 扫描宿主机当前可用的物理串口（已过滤虚假 ACPI 端口）
embedded-mcp board ports

(2) 网关生命周期与状态

# 前台启动指定板卡的网关服务（若已有服务在运行，会自动友好提示）
embedded-mcp gateway run board_a

# 查询指定板卡的网关运行状态、波特率、收发字节数与控制器租约
embedded-mcp gateway status board_a

(3) 无锁查看单片机日志

# 查看最近 20 行历史日志（不抢占端口）
embedded-mcp serial tail board_a --lines 20

# 持续跟随实时输出（类似 Linux 的 tail -f，按 Ctrl+C 退出）
embedded-mcp serial tail board_a -f

(4) 下发命令与读取回执 (多写多读原子事务)

利用方案二事务池，命令在微秒级短借租约中排队下发，自动剥离回显并返回纯净内容：

# 查询当前电池电压
embedded-mcp serial exchange board_a "bat"

# 查询充电状态
embedded-mcp serial exchange board_a "charge_status"

# 查询底盘 Shell 支持的所有命令列表
embedded-mcp serial exchange board_a "help"

# 带自定义 Prompt 与超时时间的命令交互
embedded-mcp serial exchange board_a "status" --timeout 2000 --prompt "dock:/$ "

(5) 终端直接访问与全双工交互控制台 (Terminal / Console)

除了原子单次命令外，支持像物理串口助手/串口终端一样直接交互敲命令：

方法 A：内置交互控制台（纯终端无依赖） 在任何终端中输入以下指令，直接进入板卡全双工 Shell 会话（按回车发送指令，输入 exit 或 Ctrl+C 退出）：
```
embedded-mcp console board_a
# 或
embedded-mcp serial console board_a
```
方法 B：Netcat 终端直连 宿主机已内置 nc，直接连接 5001 端口：
```
nc 127.0.0.1 5001
```
直接键盘敲入 bat、help 等指令，单片机实时回显并输出。
方法 C：PuTTY / MobaXterm / SecureCRT 直连
- 协议选择：Raw 或 Telnet
- 主机 IP：127.0.0.1，端口：5001
- 打开即是标准串口终端，支持快捷键输入与实时波形/日志回显。

6. Antigravity & AI Agent 集成

本项目完整支持官方 MCP (Model Context Protocol) 2.x 协议标准，通过 stdio 与 Google Antigravity / Claude 互通。

(1) MCP 配置文件

位于 C:\Users\Administrator\.gemini\config\mcp_config.json：

{
  "mcpServers": {
    "embedded-mcp": {
      "command": "C:\\Users\\Administrator\\.gemini\\antigravity\\bin\\embedded-mcp.exe",
      "args": ["mcp"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

(2) 专属 Skill

位于 C:\Users\Administrator\.gemini\config\skills\embedded-mcp\SKILL.md，AI Agent 自动加载并具备底层硬件诊断与无锁协同操作能力。

(3) 暴露的 MCP Tools 列表

Tool 名称	核心用途
`board_list`	获取注册的所有板卡及配置元数据
`board_status`	查询目标板卡串口连通性、收发计数、活跃租约与缓冲区指标
`serial_connect`	幂等确保板卡网关已启动连接物理串口
`serial_tail`	安全跨多字节边界读取最近历史日志（N 读无需持锁）
`serial_exchange`	核心交互工具：原子微事务下发指令、匹配 Prompt、剥离回显
`serial_read`	等待并读取最近串口输出
`serial_write`	受控写入串口（需 Lease）
`serial_reset`	触发硬件复位（DTR/RTS 脉冲）
`ssh_connect`	建立 SSH 会话并启动后台日志追踪流（如 tail -f enor.log）
`ssh_tail`	高速无锁获取远程日志最新 N 行（UTF-8 边界安全、防乱码）
`ssh_exec`	在远程嵌入式 Linux 主机上执行 Shell 命令并获取输出
`ssh_status`	查询 SSH 连接状态、目标主机、日志文件及环形缓冲区指标
`firmware_release`	固件一键发布：Keil 命令行编译 -> 产物新鲜度时间戳校验 -> MD5 -> FTP 上传 -> MQTT `mcu_up` 下发
`firmware_build`	Keil 命令行编译，自动发现并校验最新生成的新鲜 .bin 产物
`firmware_upload`	上传固件至 FTP 服务器并返回下载 URL 与 MD5 校验和
`firmware_notify`	下发 MQTT `mcu_up` OTA 升级命令至目标设备
`firmware_get_version`	从 `APP/config/config.h` 解析当前固件版本号（major.min.build）
`firmware_get_config`	查看当前激活的固件发布配置参数

7. 第三方工具并发协同 (PuTTY / VOFA+)

你可以在 AI 持续监视、CLI 下发测试的同时，使用图形化上位机直连观察波形：

打开 PuTTY 或 VOFA+。
连接类型选择 TCP（或 Raw）。
主机 IP 填 127.0.0.1，端口填 5001。
点击连接，即可实时接收底层完全相同、无任何延迟的原始数据流，彻底终结“调串口必须先关上位机”的历史。

8. 自动化测试与质量维护规范 (Maintenance & Testing)

后续对本库进行迭代、扩展适配新板卡或重构时，必须执行以下维护流程：

(1) 运行完整测试套件

uv run pytest -v

包含 20 项测试：单元测试、JSON-RPC 协议解析、跨 Chunk 汉字切片无损性、多客户端高并发多写排队事务、以及对物理硬件（COM4）的生命周期全流程测试。

(2) 代码质量校验 (Ruff)

uv run ruff check .

要求 0 warning / 0 error，保持 100% 格式洁净。

(3) 添加新板卡流程

在 config/boards/ 下新建 <board_id>.json。
配置 VID/PID 或串口号与波特率。
运行 embedded-mcp board list 验证识别。
运行 embedded-mcp serial tail <board_id> 验证通信。