# Embedded MCP

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

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
[![Package Manager uv](https://img.shields.io/badge/managed_by-uv-orange.svg)](https://github.com/astral-sh/uv)
[![Code Style ruff](https://img.shields.io/badge/code_style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Tests Passing](https://img.shields.io/badge/tests-20%2F20%20passed-brightgreen.svg)]()

---

## 1. 项目简介 (Overview)

在嵌入式与机器人开发中，传统物理串口（COM / UART）存在以下核心痛点：
1. **Windows 串口强排他性**：一个 COM 口被上位机、VOFA+ 或终端打开后，AI Agent、自动化测试与 CLI 工具均会遭遇拒绝访问（`WinError 5`）。
2. **多端并发写入冲突**：多个 AI Agent 或测试脚本并发操作同一串口时，总线字节交错撕裂，回显混淆。
3. **跨 Chunk 解码乱码**：单片机输出中文或多字节 UTF-8 日志时，若按数据包切割解码，汉字极易损坏变成 `\ufffd`。
4. **高频遥测淹没交互**：单片机持续以 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)

```text
┌──────────────────────────────────────────────────────────┐
│             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`）执行：
```bash
uv sync --extra dev
```

### (2) 安装为全局命令行工具 (任选一种)
- **推荐方法：通过 uv tool 全局链接**
  ```bash
  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.example/` 目录。
本地私有硬件定义存放于 `config/boards/*.json`（已受 `.gitignore` 保护，防止敏感信息泄漏），或通过环境变量 `EMBEDDED_MCP_CONFIG_DIR` 自定义路径。系统在任何目录下运行都会自动优先定位到本地私有目录，支持自动热重载。

首次使用时，可从示例模板复制：
```bash
# 从示例模板快速创建本地配置
cp -r config/boards.example config/boards
```

### 示例配置 (`config/boards.example/board_a.json`):
```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) 硬件与板卡发现
```powershell
# 列出系统中所有已注册板卡与当前匹配的物理端口
embedded-mcp board list

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

### (2) 网关生命周期与状态
```powershell
# 前台启动指定板卡的网关服务（若已有服务在运行，会自动友好提示）
embedded-mcp gateway run board_a

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

### (3) 无锁查看单片机日志
```powershell
# 查看最近 20 行历史日志（不抢占端口）
embedded-mcp serial tail board_a --lines 20

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

### (4) 下发命令与读取回执 (多写多读原子事务)
利用方案二事务池，命令在微秒级短借租约中排队下发，自动剥离回显并返回纯净内容：
```powershell
# 查询当前电池电压
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` 退出）：
  ```powershell
  embedded-mcp console board_a
  # 或
  embedded-mcp serial console board_a
  ```

- **方法 B：Netcat 终端直连**
  宿主机已内置 `nc`，直接连接 5001 端口：
  ```powershell
  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`：
```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 下发测试的同时，使用图形化上位机直连观察波形：
1. 打开 **PuTTY** 或 **VOFA+**。
2. 连接类型选择 **TCP**（或 Raw）。
3. 主机 IP 填 `127.0.0.1`，端口填 `5001`。
4. 点击连接，即可实时接收底层完全相同、无任何延迟的原始数据流，彻底终结“调串口必须先关上位机”的历史。

---

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

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

### (1) 运行完整测试套件
```bash
uv run pytest -v
```
- 包含 20 项测试：单元测试、JSON-RPC 协议解析、跨 Chunk 汉字切片无损性、多客户端高并发多写排队事务、以及对物理硬件（COM4）的生命周期全流程测试。

### (2) 代码质量校验 (Ruff)
```bash
uv run ruff check .
```
- 要求 0 warning / 0 error，保持 100% 格式洁净。

### (3) 添加新板卡流程
1. 在 `config/boards/` 下新建 `<board_id>.json`。
2. 配置 VID/PID 或串口号与波特率。
3. 运行 `embedded-mcp board list` 验证识别。
4. 运行 `embedded-mcp serial tail <board_id>` 验证通信。