usartMCP

usartMCP 是一个面向 AI Agent 的串口调试 MCP Server 项目。目标是让大模型 Agent 能够通过 MCP 工具安全、可追溯地调试外部硬件系统，例如 STM32、串口模块、AT 模组、Modbus RTU 设备、RS485 设备和自定义二进制协议设备。

当前仓库地址：

https://github.com/qiaodogbear/-.git

当前开发状态

当前阶段：MVP 功能已实现，可作为 MCP Server 启动并提供串口调试工具。

已经完成：

完整 MCP 串口调试工具设计文档
Python 包工程骨架
Pydantic 请求 schema
统一错误码和错误响应
MCP Server 入口和 13 个 MCP Tool 注册
pyserial 串口 session 管理
ASCII / HEX 编解码
串口发送、读取和 request-response
后台串口 monitor
JSONL 日志写入和查询
内置协议 parser
外部 parser 插件加载
受控 Python parser 脚本执行
Markdown 调试报告生成
无硬件单元测试
安全策略配置样例
JSON 示例请求
外部 parser 插件样例
MVP 实施计划
Git 仓库初始化并已推送到 GitHub

还没有完成或仍建议继续增强：

实物串口设备 smoke test
更完整的 Modbus RTU 请求构造工具
DTR/RTS 受控复位工具
人工确认回路
更详细的 Web/HTTP 调试界面
CI 自动测试

也就是说，当前仓库已经不是纯脚手架；它可以启动 MCP Server，并通过 MCP Client 调用串口工具。没有连接实物串口时，测试套件会使用 fake serial 对象验证核心行为。

项目目标

这个项目要解决的问题是：让 AI Agent 不只是“给出串口调试建议”，而是能通过受控 MCP 工具实际完成调试动作。

目标能力包括：

枚举当前系统串口
打开并配置指定串口
发送 ASCII 指令
发送 HEX 指令
读取串口返回数据
支持一次 request-response 调用
支持持续监听串口输出
将 TX/RX 数据写入 JSONL 日志
对接收数据执行协议解析
调用受控 Python 脚本分析数据或日志
生成结构化调试报告
通过安全策略限制危险硬件操作

技术栈

Python 3.10+
pyserial
MCP Python SDK
Pydantic / JSON Schema
JSONL 日志
YAML 安全策略配置
插件式 parser
pytest

工程结构

.
|-- README.md
|-- pyproject.toml
|-- LICENSE
|-- config/
|   `-- safety.example.yaml
|-- docs/
|   |-- serial-mcp-design.md
|   `-- superpowers/
|       `-- plans/
|           `-- 2026-05-10-usart-mcp-implementation.md
|-- examples/
|   |-- transceive_ascii.json
|   `-- transceive_modbus_hex.json
|-- logs/
|   `-- .gitkeep
|-- parsers/
|   `-- my_protocol.py
|-- src/
|   `-- usart_mcp/
|       |-- __init__.py
|       |-- errors.py
|       |-- schemas.py
|       `-- server.py
`-- tests/
    `-- README.md

设计文档

详细设计文档在：

docs/serial-mcp-design.md

实施计划在：

docs/superpowers/plans/2026-05-10-usart-mcp-implementation.md

如果后续继续开发，建议按实施计划逐步完成，每个任务都配套单元测试。

规划中的 MCP Tools

1. list_serial_ports

枚举当前系统可用串口。

返回信息包括：

串口名，例如 COM5
描述
硬件 ID
厂商
序列号
是否可用
是否被安全策略允许

2. open_serial_port

打开并配置指定串口，返回 session_id。

核心参数：

port
baudrate
bytesize
parity
stopbits
timeout_ms
write_timeout_ms
rtscts
xonxoff
dsrdtr

3. close_serial_port

关闭指定串口 session，并返回本 session 的收发统计。

4. send_ascii

向指定串口发送 ASCII 文本。

支持：

指定编码，例如 utf-8
自动追加 CRLF
自动追加 LF
TX HEX 回显
TX ASCII 回显
写入 JSONL 日志

5. send_hex

向指定串口发送 HEX 字节流。

支持输入格式：

01 03 00 00 00 02 C4 0B
01:03:00:00:00:02:C4:0B
01-03-00-00-00-02-C4-0B
010300000002C40B

6. read_serial

从指定串口读取返回数据。

支持：

总超时
最大读取长度
ASCII 帧尾
HEX 帧尾
半包保留
粘包处理
RX JSONL 日志

7. transceive_serial

完成一次 request-response 调用：先发送一条指令，再等待返回数据。

适合：

AT 指令
Modbus RTU 请求
自定义二进制协议查询
Bootloader 状态查询

8. start_serial_monitor

启动后台监听任务，将串口输出持续写入 JSONL 日志。

支持：

指定日志文件
读取间隔
最大日志文件大小
日志轮转
可选 parser

9. stop_serial_monitor

停止后台监听任务。

返回：

监听时长
日志路径
接收总字节数

10. parse_serial_data

对已有数据执行协议解析。

输入可以是：

data_hex
data_ascii

11. run_python_parser

调用白名单目录下的外部 Python 脚本，对单条数据或日志文件做复杂分析。

安全要求：

禁止任意路径执行
禁止 shell 拼接命令
支持超时终止
返回 stdout、stderr、exit_code
如果 stdout 是 JSON，自动解析为 parsed_result

12. get_serial_log

读取指定 session 或指定日志文件中的结构化 JSONL 日志。

支持：

按 session 过滤
按 TX/RX 方向过滤
按时间过滤
限制返回条数

13. generate_debug_report

根据日志和解析结果生成 Markdown 调试报告。

报告内容包括：

TX/RX 统计
超时统计
parser 错误
CRC 错误
异常帧
建议下一步调试动作

内置协议解析器规划

MVP 计划内置以下 parser：

raw_hex：返回原始 HEX 和字节数
ascii_line：按文本行解析 ASCII 输出
regex_ascii：用正则提取 ASCII 字段
modbus_rtu：解析 Modbus RTU 响应并校验 CRC16
custom_frame：解析带帧头、长度、校验的自定义二进制帧

外部 parser 约定接口：

def parse(data: bytes, options: dict) -> dict:
    return {
        "byte_count": len(data),
        "payload_hex": data.hex(" ").upper(),
    }

样例文件：

parsers/my_protocol.py

JSONL 日志格式

所有串口原始数据都必须可追溯。规划中的日志格式是一行一个 JSON 对象：

{
  "record_id": "018f-rx-000001",
  "timestamp": "2026-05-10T10:30:00.180+08:00",
  "session_id": "com5-001",
  "tool_call_id": "call-abc123",
  "port": "COM5",
  "baudrate": 115200,
  "direction": "RX",
  "mode": "hex",
  "raw_hex": "01 03 04 00 64 00 C8 BA 7A",
  "raw_ascii": null,
  "byte_count": 9,
  "parser": "modbus_rtu",
  "parsed": {
    "slave_id": 1,
    "function_code": 3,
    "registers": [100, 200],
    "crc_ok": true
  },
  "error": null,
  "meta": {
    "timeout": false,
    "elapsed_ms": 57
  }
}

安全策略

安全控制是本项目的核心模块。AI Agent 可以自主调用串口，如果没有约束，可能误触发复位、擦除、烧录、写 Flash 等危险操作。

规划中的安全能力：

串口白名单
命令白名单
危险命令黑名单
最大发送频率限制
最大单次发送字节数限制
最大监听时长限制
最大日志文件大小限制
Python parser 脚本目录白名单
高风险指令人工确认机制
禁止 Agent 执行任意系统命令

配置样例：

config/safety.example.yaml

当前如何使用

当前仓库已经可以作为 MCP Server 启动。没有硬件时，可以先运行测试；连接硬件前，请先修改 config/safety.yaml 里的串口白名单。

1. 克隆仓库

git clone https://github.com/qiaodogbear/-.git usartMCP
cd usartMCP

2. 创建虚拟环境

Windows PowerShell：

python -m venv .venv
.\.venv\Scripts\Activate.ps1

3. 安装开发依赖

pip install -e ".[dev]"

4. 查看已注册 MCP Tools

usart-mcp --list-tools

当前预期会列出：

list_serial_ports
open_serial_port
close_serial_port
send_ascii
send_hex
read_serial
transceive_serial
start_serial_monitor
stop_serial_monitor
parse_serial_data
run_python_parser
get_serial_log
generate_debug_report

5. 查看设计和计划

type docs\serial-mcp-design.md
type docs\superpowers\plans\2026-05-10-usart-mcp-implementation.md

6. 执行当前语法检查

python -m compileall src

MCP 使用方式

典型使用方式如下：

1. 配置安全策略

复制配置：

copy config\safety.example.yaml config\safety.yaml

修改允许的串口：

serial:
  allowed_ports:
    - COM5
  default_baudrate: 115200
  max_send_bytes: 256

2. 启动 MCP Server

usart-mcp --config config/safety.yaml

3. 在 MCP Client 中配置

示例配置形态：

{
  "mcpServers": {
    "usartMCP": {
      "command": "usart-mcp",
      "args": ["--config", "config/safety.yaml"]
    }
  }
}

具体配置文件位置取决于你的 MCP Client，例如 Codex、Claude Desktop、Cursor 或其他 Agent 工具。

4. 典型 Agent 调用流程

list_serial_ports
open_serial_port
transceive_serial
get_serial_log
generate_debug_report
close_serial_port

示例请求

ASCII AT 指令

{
  "session_id": "com5-001",
  "mode": "ascii",
  "data": "AT+GMR",
  "append_crlf": true,
  "timeout_ms": 1000,
  "max_bytes": 512,
  "end_pattern_ascii": "OK\r\n",
  "parser": {
    "name": "ascii_line",
    "options": {
      "strip": true
    }
  },
  "log": true
}

仓库中的样例文件：

examples/transceive_ascii.json

Modbus RTU HEX 指令

{
  "session_id": "com5-001",
  "mode": "hex",
  "data": "01 03 00 00 00 02 C4 0B",
  "append_crlf": false,
  "timeout_ms": 1000,
  "max_bytes": 256,
  "parser": {
    "name": "modbus_rtu",
    "options": {
      "expected_slave_id": 1,
      "expected_function_code": 3
    }
  },
  "log": true
}

仓库中的样例文件：

examples/transceive_modbus_hex.json

统一错误格式

规划中的所有工具失败时都返回统一结构：

{
  "ok": false,
  "error_code": "SERIAL_READ_TIMEOUT",
  "error_message": "Read timeout after 1000 ms",
  "details": {
    "session_id": "com5-001",
    "timeout_ms": 1000
  }
}

主要错误码：

SERIAL_PORT_NOT_FOUND
SERIAL_PORT_BUSY
SERIAL_OPEN_FAILED
SERIAL_WRITE_FAILED
SERIAL_READ_TIMEOUT
SERIAL_READ_FAILED
INVALID_HEX_STRING
INVALID_ENCODING
PARSER_NOT_FOUND
PARSER_FAILED
PYTHON_SCRIPT_NOT_ALLOWED
PYTHON_SCRIPT_TIMEOUT
PYTHON_SCRIPT_FAILED
SAFETY_POLICY_BLOCKED
LOG_WRITE_FAILED

GitHub / gh 说明

本项目已经推送到 GitHub。gh 已安装，但当前机器上的 GitHub CLI 还没有登录成功。由于普通 git push 已经能工作，当前不影响项目上传。

gh 后续的作用：

创建仓库
登录 GitHub
创建 Pull Request
查看 issue
查看 CI 状态
管理 release

许可证

仓库当前包含 LGPL 2.1 许可证文件，pyproject.toml 中的 license 也设置为：

LGPL-2.1-only

Name		Name	Last commit message	Last commit date
config		config
docs		docs
examples		examples
logs		logs
parsers		parsers
src/usart_mcp		src/usart_mcp
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation