用途
serial-mcp-server 为 AI 工作流提供串口访问能力，适用于需要通过串口与 UART 设备交互自动化的场景，例如启动/配置流程、协议握手、回归冒烟测试以及 AI 辅助调试。它同时以两种形式提供：面向支持 MCP 工具的客户端的 MCP stdio 服务器，以及无需 MCP 配置即可直接使用的可脚本化 CLI（用于 CI 和智能体技能）。
主要能力
- 两种形态：MCP stdio 服务器（适合支持 MCP 工具的客户端，长期运行的 stdio 服务）与直接使用的 CLI。
- JSON 宏自动化（DSL）：将串口步骤记录为 JSON，供人、CLI 脚本或 AI 智能体验证、查看计划、无硬件模拟并运行。v0.3 DSL 支持 send（发送 UTF-8、hex 或 base64 字节）、delay（固定毫秒等待）、expect（读取直到响应包含或等于期望字节）、assembly（将命名宏组合为更长工作流）。
- 宏相关 CLI 命令：macro validate、macro list、macro plan、macro run；MCP 宏工具支持运行时内存中加载/列出/卸载 pack、计划与运行。
- 无硬件模拟：为宏验证、计划和执行器冒烟测试提供显式无硬件模拟。
- 捕获窗口读取：timeout-ms 保留一次读取语义；--duration-ms 提供有界收集窗口，返回包含 completion_reason、waited_ms、elapsed_ms 和逐块元数据的合并响应。捕获选项包括 --start-trigger first-byte / immediate、--initial-timeout-ms、--idle-timeout-ms、--max-bytes。write --read 可接受相同捕获选项。
- 配置命令与输出规则：stdout 保留给命令数据和 JSON，stderr 用于诊断，--json 输出可被 jq 等工具解析，非零退出码表示失败；支持 utf8、hex、base64 数据格式（二进制用 hex 或 base64）。
- 智能体技能：仓库内置与 Claude Code、Codex 兼容的技能（skills/serial-debug），CLI 优先并说明 MCP 为可选配置路径，供智能体列端口、运行串口冒烟测试、运行宏自动化、控制 RTS/DTR 或排查 UART/USB 串口设备。
使用方式
MCP 服务器推荐命令为带 serve 子命令的启动方式；无子命令启动保留为兼容路径，新配置应使用 serve。提供 Claude Desktop（macOS/Linux 与 Windows）配置示例。MCP 宏注册表仅为运行时，重启服务器会清空已加载 pack，且不写入持久宏库。MCP read 在连接 id、timeout_ms、max_bytes、encoding 之外接受可选的捕获字段；未提供 duration_ms 时保持单次读取行为，提供时返回结构化 JSON 文本。
CLI 方面：从源码构建（Rust 1.74+），二进制构建路径见仓库；可从检出目录将 CLI 安装到 PATH。无 MCP 客户端时可直接使用 CLI 进行串口操作。宏 pack 是 schema_version 为 0.3 的 JSON 文件，v0.3 支持宏内的 send、delay、expect 步骤以及按名称调用宏的 assembly，expect 支持 contains 与 equals。宏 DSL 有意受限，不运行 shell 命令、JavaScript、Python、文件操作、循环、变量、if/else 分支、Quick 命令或 RTS/DTR 宏步骤。宏 CLI 帮助可通过 serial-mcp-server macro --help 查看。
适用场景
- 需要有序命令与延时的启动或配置流程。
- 必须等待 OK、READY、PONG、提示符或其他预期响应的协议握手。
- 需要重复运行同一串口过程的回归冒烟测试。
- AI 辅助调试：在接触硬件前审查完整的发送/延时/期望计划。
限制与安全
- 运行硬件操作需要串口设备或 USB 转串口适配器，以及所选串口对应的设备驱动和操作系统权限。
- 宏 DSL 有明确限制（见上），不支持 shell、脚本语言、文件操作、循环、变量、分支、Quick 命令或 RTS/DTR 宏步骤。
- 宏注册表仅存在于运行时，重启即清空，不持久化。
- 硬件安全：串口命令会影响真实硬件，需先通过 serial-mcp-server list-ports --json 确认端口，连接适配器前确认电压电平，写入前确认波特率、数据位、校验、停止位和流控，谨慎处理 RTS 与 DTR（许多板卡将其用于复位或启动模式），验证结论应基于已连接设备的命令输出。
- Claude Code --bare 模式在本地测试中未能解析 /serial-debug，技能触发冒烟测试应使用普通 Claude Code 打印或交互模式。
其他信息
- 当前发布目标：0.3.0。
- 语言版本：英文与中文。
- 提供 STM32 演示示例（examples/STM32_demo/ 下），含交互式串口命令接口的固件；接线、固件命令、MCP 用法与 CLI 冒烟命令见该目录 README。
- 发布工作使用已签入的 Cargo.lock 及相关门禁。
- 许可：MIT，见 LICENSE。
