woooooooooolf/ser2mcp
UART serial port MCP server: expose local serial ports to AI assistants as standard MCP tools（串口转 MCP 服务器，以最适合 AI 的方式提供串口读写支持）
安装Install
dsh plugin --profile web add github:woooooooooolf/ser2mcp把 woooooooooolf/ser2mcp 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
ser2mcp
简体中文 | English
ser2mcp 是一个本地 UART 串口 MCP 服务器，把串口枚举、配置、读写、输出匹配和文件发送封装为标准 MCP 工具，供支持 stdio MCP 的 AI 客户端调用。
核心能力
- 提供 14 个
uart_*工具，支持多串口、运行时重配置、写后读取和按输出 pattern 编排时序 - 后台持续读取串口数据，使用有界环形缓冲保存未读内容，并报告
overflow_delta / overflow_total - 支持 hex、UTF-8 text 和仅用于返回侧的 text-escaped，适配二进制协议与终端日志
- 通过一次
uart_send_file流式发送本地文件，支持连续 base64、进度查询、估算和取消 - Windows、Linux、macOS 单可执行文件交付，无需安装 Rust 运行时
安装与接入
可从 Releases 下载对应平台的预编译包，也可以从源码构建：
git clone https://github.com/woooooooooolf/ser2mcp.git
cd ser2mcp
# Debian/Ubuntu 构建依赖；Windows/macOS 跳过
sudo apt-get install -y libudev-dev
cargo build --release
target/release/ser2mcp --list-ports
不带参数运行 ser2mcp 即进入 MCP stdio 服务模式。通用客户端配置：
{
"mcpServers": {
"ser2mcp": {
"command": "/absolute/path/to/ser2mcp",
"args": []
}
}
}
Windows 路径示例："command": "C:\\tools\\ser2mcp.exe"。日志写入 stderr，可用 RUST_LOG 调整级别，默认 info。
Reasonix 插件安装
仓库根目录包含 reasonix-plugin.json，bin/ 内含三平台预编译文件与 POSIX 启动脚本。Manifest 统一使用 bin/ser2mcp：Windows 自动解析同名 ser2mcp.exe，Linux/macOS 由脚本选择对应二进制。在 Reasonix 中让 Agent 执行：
Install the ser2mcp plugin package from https://github.com/woooooooooolf/ser2mcp. Use install_source with kind="auto" (or "plugin").
安装后调用 uart_list_ports 验证；返回空数组也表示服务器已正常工作，只是当前没有可枚举串口。离线安装时下载完整源码仓库，并把仓库目录作为 install_source 的本地路径。
DeepSeek-Harness 接入
在 DSH 中对 Agent 说：
请从 https://github.com/woooooooooolf/ser2mcp 安装 ser2mcp 到 DSH，并按照 docs/DSH_INTEGRATION.md 完成部署。
Agent 应以当前 DSH 版本的配置和目录约定为准，完成 stdio MCP 服务器注册，并安装仓库内的两个 SKILL。
工具
| 工具 | 用途 |
|---|---|
uart_list_ports |
枚举串口名称、类型与 USB 描述 |
uart_open / uart_configure / uart_close |
打开、运行时重配置和关闭端口 |
uart_write |
只发送数据，不等待回复 |
uart_read |
按 idle、字节上限或总超时拉取上行缓冲 |
uart_exchange |
在同一 I/O 临界区完成短命令的写入与 idle 收尾读取 |
uart_expect |
可选发送数据，并等待输出出现指定 pattern |
uart_expect_send |
命中 pattern 后立即发送 reply |
uart_available / uart_clear |
查询状态、溢出、错误与发送进度；清空未读缓冲 |
uart_send_estimate |
无需打开串口，估算文件发送字节数和耗时 |
uart_send_file / uart_send_cancel |
同步阻塞地流式发送本地文件；请求取消仍在进行的传输 |
除 uart_list_ports 和 uart_send_estimate 外，其余工具都需要 port。端口名（如 COM3、/dev/ttyUSB0）就是句柄。普通 I/O、配置、expect 和 close 共享全局 I/O 锁；文件发送期间这些调用会排队，uart_available / uart_clear 仍可并发执行。宿主允许并发调用或后续任务仍能访问同一服务时，可用 uart_send_cancel 请求取消仍在进行的发送。
AI 使用指南
仓库内含两个通用 Agent Skills：
ser2mcp-usage：串口交互工具的完整参数、选择、编码、完成判定、缓冲与故障处理ser2mcp-file-transfer：文件工具的完整参数、发送授权、估算、接收端准备、EOF、取消和端到端对账
Reasonix 安装插件后会同时获得这两个 SKILL。Claude Code、Codex 等 Agent 可把 skills/ 挂载到各自的技能目录。
最重要的语义边界：
reason="idle"只表示字节流静默，不表示命令已完成；有提示符或结束标记时使用uart_expectuart_exchange会返回调用前已有的历史缓冲，但只有观察到本次写入后的新上行数据，才允许按 idle 或字节上限收尾uart_read/uart_exchange的new_data_observed表示调用后是否观察到新上行数据；pending表示返回快照中仍有未读缓冲。pending=false不证明设备之后不会继续输出，也不代表命令完成uart_read/uart_exchange只有reason="timeout"才可能返回bytes=0；并发清缓冲不会再产生空的 idle/max_bytes 结果matched=true只证明 pattern 按所选的原始字节/忽略 ANSI 语义在匹配范围内命中，不代表设备事务成功；终端用提示符/输出标记，AT 或无回显 MCU 用状态码/事务标识，二进制协议用帧字段与校验uart_expect.match_scope="buffer"（默认）允许历史未读数据参与匹配；只等待调用后的新数据时用"new"。对开启输入回显的终端，关闭回显或使用完整 pattern 不连续出现在命令文本中的输出锚点- pattern 默认按原始字节匹配；彩色终端中可显式设置
ignore_ansi=true，让匹配跳过常见 CSI、OSC 等 ANSI 控制序列。该选项不修改原始缓冲或返回数据，二进制协议不要启用 uart_expect_send.newline作用于reply；终端回复可传reply_mode="text"和newline="crlf"，不需要把行尾嵌入 reply 文本uart_expect默认只消费到 pattern 结尾；返回的pending=true（等价于buffered_bytes > 0）时补一次uart_read。pending=false仍只是瞬时快照；确实需要 pattern 后的未来输出时继续按协议等待- 带参数工具的未知字段会报错，不再静默忽略；
buffer_size只能在uart_open时设置，需调整时先关闭再重新打开端口 overflow_delta > 0表示环形缓冲已有数据被覆盖，当前读取结果存在缺口uart_send_file的 overflow 是返回时快照；返回后用uart_available/uart_read再确认最新overflow_total，0 不代表最终无溢出uart_send_file默认同步阻塞至结束；可选max_duration_ms只在显式设置时自动止损并返回reason="duration_limit"，通常仍应根据估算等待完成uart_send_file的reason="completed"只表示服务器已完成写入；端到端完整性必须用对端长度和解码后哈希确认
验证与开发
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo doc --no-deps
真实硬件 TX-RX 回环测试：
cargo run --release --example loopback -- --list
cargo run --release --example loopback -- COM3 115200
Linux 无权打开 /dev/ttyUSB0 时，以 root 运行 scripts/linux-serial-permissions.sh，然后注销并重新登录。Windows 枚举不到端口时，检查 CH340、CP210x 等 USB 转串口驱动。
安全
ser2mcp 会把串口读写和本地文件发送能力交给 AI 客户端。uart_send_file 可以读取 ser2mcp 进程有权访问的任意普通文件并经串口发出，服务端不限制目录。请使用权限受限的账户运行，只连接可信设备，并在发送文件前确认路径与目标设备均在用户授权范围内。完整说明见 SECURITY.md。
License
MIT OR Apache-2.0（见 LICENSE-MIT 与 LICENSE-APACHE）
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…