使用说明

串行MCP服务器

serial-mcp-server 以两种形式为AI工作流提供串行端口访问：

支持MCP工具的客户端的MCP stdio服务器。
可编写脚本的CLI，无需MCP设置即可直接使用、CI和代理技能。

当前发布目标： 0.3.0.

语言版本：英语 | 中文

0.3.0更新简报

为可重复的串行过程添加了JSON宏DSL自动化。
添加了CLI宏命令： macro validate, macro list, macro plan，以及 macro run.
添加了用于内存包加载/列表/卸载、计划和运行时的MCP宏工具。
为宏验证、规划和执行器烟雾测试添加了明确的无硬件模拟。
将Quick排除在公共API之外。快速样式用例应表示为宏。

宏观自动化

当串行工作流不止一次读取或写入时，请使用宏。许多设备需要定时序列：发送命令，等待几毫秒，读取直到出现提示或确认，然后发送下一个命令。宏包将该过程记录为JSON，以便人类、CLI脚本或AI代理可以验证它、检查计划、在没有硬件的情况下模拟它，并在连接设备时在真实端口上运行它。

典型的宏用例：

需要有序命令和延迟的引导或配置流。
必须等待的协议握手 OK, READY, PONG、提示或其他预期的响应。
回归烟雾测试，其中应重复运行相同的串行程序。
人工智能辅助调试，代理应在接触硬件之前查看完整的发送/延迟/预期计划。

v0.3 DSL有意设计得较小：

send：写入UTF-8、十六进制或base64字节。
delay：等待固定的毫秒数。
expect：读取，直到响应包含或等于预期的字节。
assembly：将命名宏组合成更长的工作流。

AI代理可以从这个README中发现宏支持，从捆绑的 skills/serial-debug 技能，通过跑步 serial-mcp-server macro --help，或者在配置服务器时通过MCP工具发现。不使用MCP的代理仍然可以使用CLI和技能文档。

需求

Rust 1.74或更新版本。
运行硬件操作时的串行设备或USB到串行适配器。
所选串行端口的设备驱动程序和操作系统权限。

从源代码安装

git clone https://github.com/adancurusul/serial-mcp-server.git
cd serial-mcp-server
cargo build --release

二进制文件构建于：

target/release/serial-mcp-server

将CLI安装到您的 PATH 结账时：

cargo install --path . --locked

CLI使用情况

当您希望在没有MCP客户端的情况下进行直接串行操作时，请使用CLI。

serial-mcp-server --help
serial-mcp-server list-ports --json
serial-mcp-server probe --port <port> --baud 115200 --json
serial-mcp-server write --port <port> --baud 115200 --data H --read --timeout-ms 1000 --json
serial-mcp-server read --port <port> --baud 115200 --timeout-ms 1000 --json
serial-mcp-server read --port <port> --baud 115200 --duration-ms 5000 --initial-timeout-ms 30000 --idle-timeout-ms 1500 --json
serial-mcp-server set-control-lines --port <port> --rts high --dtr low --json

捕获窗口读取

timeout-ms 保持其原始含义：等待那么多一次读取操作的毫秒数，然后在字节可用时立即返回。

使用 --duration-ms 当AI或脚本需要一个有界的收集窗口时。捕获模式保持内部读取，并返回一个组合响应 completion_reason, waited_ms, elapsed_ms，以及每个块的元数据。

serial-mcp-server read --port <port> --baud 115200 \
  --duration-ms 5000 \
  --start-trigger first-byte \
  --initial-timeout-ms 30000 \
  --idle-timeout-ms 1500 \
  --max-bytes 8192 \
  --json

捕获选项：

--duration-ms：捕获开始后的收集窗口长度。
--start-trigger first-byte：在启动之前等待第一个字节持续时间时钟。这是捕获模式的默认设置。
--start-trigger immediate：命令启动时启动持续时间时钟。
--initial-timeout-ms：第一字节模式下第一个字节的最大等待时间。如果省略，该命令将使用 --timeout-ms.
--idle-timeout-ms：捕获完成后，在这么多安静的毫秒后停止起动。
--max-bytes：组合响应字节的硬上限。

write --read 写入后接受相同的捕获选项：

serial-mcp-server write --port <port> --baud 115200 --data RUN --read \
  --duration-ms 5000 --initial-timeout-ms 30000 --json

宏自动化命令：

serial-mcp-server macro validate --file examples/macros/ping.json --json
serial-mcp-server macro list --file examples/macros/ping.json --json
serial-mcp-server macro plan --file examples/macros/ping.json --macro ping --json
serial-mcp-server macro run --file examples/macros/ping.json --macro ping --dry-run --json
serial-mcp-server macro run --file examples/macros/ping.json --macro ping --simulate-read PONG --json
serial-mcp-server macro run --file examples/macros/ping.json --macro ping --port <port> --baud 115200 --json

宏包是JSON文件 schema_version 着手 0.3.v0.3支持 send, delay，以及 expect 宏内部的步骤，以及按名称调用宏的程序集。 expect 支持 contains 和 equals.

宏DSL被有意限制。它不运行shell命令、JavaScript、Python、文件操作、循环、变量、if/else分支、快速命令或RTS/DTR宏步骤。

配置命令：

serial-mcp-server generate-config
serial-mcp-server validate-config --config serial-mcp.toml
serial-mcp-server show-config --config serial-mcp.toml

CLI输出规则：

stdout保留用于命令数据和JSON。
stderr保留用于诊断。
--json 输出应该可以通过以下工具进行解析 jq.
非零退出代码表示命令失败。

支持的CLI数据格式包括 utf8, hex，以及 base64.使用 hex 或 base64 对于二进制有效载荷。

MCP使用

当您的客户端支持MCP工具并且您想要一个长时间运行的stdio服务器时，请使用MCP。

建议的服务器命令：

serial-mcp-server serve

不保留子命令启动作为现有MCP设置的兼容路径，但新配置应使用 serve.

macOS/Linux的Claude桌面示例：

{
  "mcpServers": {
    "serial": {
      "command": "/path/to/serial-mcp-server/target/release/serial-mcp-server",
      "args": ["serve"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Windows示例：

{
  "mcpServers": {
    "serial": {
      "command": "C:\\path\\to\\serial-mcp-server\\target\\release\\serial-mcp-server.exe",
      "args": ["serve"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

MCP工具

工具	目的
`list_ports`	发现可用的串行端口。
`open`	打开串行连接。
`write`	将UTF-8、十六进制或base64数据写入打开的连接。
`read`	使用超时处理或有界捕获窗口从打开的连接中读取数据。
`close`	关闭打开的连接。
`set_control_lines`	在打开的连接上设置RTS和/或DTR。
`macro_load`	验证内联宏包或包文件路径并将其加载到服务器的内存注册表中。
`macro_list`	列出加载的宏包、宏和程序集。
`macro_unload`	从内存注册表中删除加载的宏包。
`macro_plan`	在不打开硬件的情况下展开已加载、内联或文件支持的宏或程序集。
`macro_run`	对现有连接或显式模拟输入运行加载的宏或程序集。
`macro_run_inline`	验证、计划和运行内联宏包，而不将其存储在注册表中。

MCP宏注册表仅在运行时使用。重新启动服务器会清除加载的包，并且服务器不会写入持久宏库。

主控程序 read 除了接受以下可选捕获字段外 connection_id, timeout_ms, max_bytes，以及 encoding:

{
  "connection_id": "...",
  "duration_ms": 5000,
  "start_trigger": "first_byte",
  "initial_timeout_ms": 30000,
  "idle_timeout_ms": 1500,
  "max_bytes": 8192,
  "encoding": "utf8"
}

当 duration_ms 缺席，MCP read 保持现有的单次读取行为。当 duration_ms 如果存在，该工具将返回结构化的JSON文本与 completion_reason, waited_ms, elapsed_ms，以及 chunks.

代理技能

该存储库包括克劳德代码和Codex兼容的技能，具体如下：

skills/serial-debug/

该技能首先是CLI，并将MCP记录为可选的配置路径。它适用于需要列出端口、运行串行烟雾测试、运行宏自动化、控制RTS/DTR或对UART/USB串行设备进行故障排除的代理。

对于本地开发，将技能文件夹复制到代理技能根中：

mkdir -p ~/.codex/skills ~/.claude/skills ~/.agents/skills
cp -R skills/serial-debug ~/.codex/skills/
cp -R skills/serial-debug ~/.claude/skills/
cp -R skills/serial-debug ~/.agents/skills/

经过测试的显式触发器：

Codex: Use $serial-debug
Claude Code: /serial-debug

克劳德代码 --bare 模式未解析 /serial-debug 在本地测试中；使用正常的克劳德代码打印或交互模式进行技能触发烟雾测试。

硬件安全

串行命令会影响实际硬件。

确认从中选择的端口 serial-mcp-server list-ports --json.
在将适配器连接到目标板之前，请确认电压水平。
写入前确认波特率、数据位、奇偶校验、停止位和流控制。
小心对待RTS和DTR。许多电路板将这些线路连接到重置或启动模式。
验证声明应基于连接设备的命令输出。

STM32演示

STM32演示如下：

examples/STM32_demo/

它为交互式串行命令接口提供固件。看示例/STM32_demo/README.md 用于布线、固件命令、MCP使用和CLI冒烟命令。

质量门

发布工作使用签入 Cargo.lock 这些门：

cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-targets --all-features
cargo doc --locked --all-features --no-deps

CLI烟雾：

cargo run --locked -- --help
cargo run --locked -- list-ports --json
cargo run --locked -- write --help
cargo run --locked -- set-control-lines --help
cargo run --locked -- macro validate --file examples/macros/ping.json --json
cargo run --locked -- macro run --file examples/macros/ping.json --macro ping --simulate-read PONG --json

许可证

该项目根据MIT许可证获得许可。看许可证.

使用说明

串行MCP服务器

0.3.0更新简报

宏观自动化

需求

从源代码安装

CLI使用情况

捕获窗口读取

MCP使用

MCP工具

代理技能

硬件安全

STM32演示

质量门

许可证

相关 MCP

学术论文搜索与下载服务

Qdrant向量搜索MCP服务器

MCP命令执行服务

串口AI控制工具

AI工作流管理工具

Shell命令执行服务