# uart-mcp

[中文](#中文) | [English](#english)

---

## 中文

用于 UART 和串口调试的本地 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务端。它通过基于换行符分隔的标准输入输出 (stdio) 提供 MCP 服务，适用于运行在能够直接访问串口转接器的本机环境中。

### 功能特性

- **持久捕获会话**：内置有界的内存环形缓冲区（Ring Buffer）和按天滚动的日志文件。
- **数据读取与监控**：支持读取新增捕获行、等待正则/事件匹配、查看近期输出以及检索历史日志。
- **端口与交互**：支持枚举可用串口，并支持单次 HEX 数据的发送/应答（query）交互。
- **协议解析**：支持根据 YAML 协议描述文件解析捕获的 HEX 数据。
- **Shell 自动化交互**：支持向类 Shell 交互的终端设备依次执行一系列串口命令。
- **跨平台支持**：基于 Python 和 pySerial 实现，具备跨平台兼容性。

### 环境要求

- Python 3.10 或更高版本。
- 串口转接器/适配器以及使用该硬件设备所需的操作系统级权限。
- `uv`（推荐）或 `pip`。

### 安装与运行

克隆代码仓库，并在隔离环境中安装运行：

```sh
uv sync
uv run uart-mcp
```

该服务端采用 MCP stdio 协议。MCP 客户端会将其作为子进程启动，并通过 stdin/stdout 交换 JSON-RPC 消息。诊断信息输出至 stderr，确保 stdout 专用于协议传输。

或者，使用 pip 安装并运行命令行：

```sh
python -m pip install .
uart-mcp
```

开发与测试：

```sh
uv sync --group dev
uv run pytest
```

自动化测试使用模拟串口设备（fake serial device），无需连接真实硬件。

### MCP 客户端配置

支持 `mcpServers` 配置的客户端示例（请将路径替换为实际克隆路径）：

```json
{
  "mcpServers": {
    "uart-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/uart-mcp", "run", "uart-mcp"],
      "env": {
        "UART_MCP_LOG_DIR": "/absolute/path/to/uart-mcp-data/logs"
      }
    }
  }
}
```

在 Windows 系统下，请使用绝对路径，例如 `C:\\Users\\you\\src\\uart-mcp`。`UART_MCP_LOG_DIR` 环境变量为可选配置；默认情况下日志将写入仓库目录下的 `logs/` 文件夹。日志中可能包含设备输出、认证凭据等敏感信息，请妥善选择并保护该目录。

### 工具列表

| 工具 | 用途说明 |
| --- | --- |
| `list_ports` | 列出当前主机可见的所有串口。 |
| `serial_open`, `serial_close`, `serial_status` | 管理和查看后台捕获会话。 |
| `serial_read`, `serial_get_recent`, `serial_wait_for` | 消费已捕获输出或等待指定的正则匹配/事件。 |
| `serial_search`, `serial_get_log`, `serial_clear_buffer` | 检索历史日志、按页浏览单日日志或清空内存缓冲区。 |
| `serial_write` | 向已打开的捕获会话写入文本或 HEX 数据。 |
| `serial_send`, `serial_query` | 执行单次 HEX 发送或“发-收”交互操作。 |
| `protocol_parse` | 无需打开串口，直接基于 YAML 协议定义解析 HEX 响应数据。 |
| `serial_shell` | 向类 Shell 串口控制台发送一组连续命令。 |

在使用捕获会话类工具前需先调用 `serial_open`，使用完毕后调用 `serial_close`。如果同时打开了多个会话，必须在操作中指定 `port` 参数。`serial_read` 工具会推进共享读取游标；如仅需查看而不消费游标，请使用 `serial_get_recent`。捕获工具接收的数据是以“行”为维度的，因此未以换行符结尾的提示符可能暂时不会出现在捕获队列中。

### 安全与限制说明

- `serial_write`、`serial_send`、`serial_query` 和 `serial_shell` 会直接向真实硬件发送数据。MCP 标注已将其标记为带有副作用（side-effecting），但此类标注仅供提示参考；使用前请务必确认目标端口与发送内容。
- `serial_shell` 会原样发送传入的命令。它不是沙箱，不会对命令安全性进行校验。
- 服务端专为本地 stdio 交互设计，未实现网络传输、身份鉴权或多用户访问控制。
- 捕获的日志为纯文本存储，除非操作人员手动清理，否则将长期保留。
- 串口权限、驱动安装、电平标准、波特率和流控要求均取决于主机系统和连接的硬件设备。
- DTR/RTS 保持 pySerial 的默认设置。部分转接板或开发板在打开端口时可能会触发复位或进入 bootloader。

### 项目结构

- `uart_mcp_server.py`: MCP stdio 服务端及捕获会话工具。
- `uart_cli.py`: CLI 工具以及被 MCP 工具复用的单次串口操作实现。
- `uart_agent.py`: 串口会话管理与底层设备 I/O 辅助模块。
- `test_uart_mcp_server.py`: 无硬件依赖的单元与回归测试。
- `docs/`: 硬件测试记录与实现备忘。

### 开源协议

MIT。详情参见 [LICENSE](LICENSE)。

---

## English

A local [Model Context Protocol](https://modelcontextprotocol.io/) server for UART and serial-port debugging. It exposes a newline-delimited stdio MCP endpoint and is intended to run on the same machine that has access to the serial adapter.

### Features

- Persistent capture sessions with a bounded in-memory ring buffer and daily log files.
- Read newly captured lines, wait for regex/event matches, inspect recent output, and search historical logs.
- Enumerate ports and perform one-shot HEX send/query operations.
- Parse captured HEX data against YAML protocol descriptions.
- Communicate with shell-like devices using a sequence of serial commands.
- Cross-platform Python implementation using pySerial.

### Requirements

- Python 3.10 or newer.
- A serial adapter and the appropriate OS-level device permissions for hardware use.
- `uv` (recommended) or `pip`.

### Install and run

Clone the repository, then install it in an isolated environment:

```sh
uv sync
uv run uart-mcp
```

The server uses MCP stdio. An MCP client launches it as a subprocess and exchanges JSON-RPC messages over stdin/stdout. Diagnostics are written to stderr so stdout remains reserved for the protocol.

Alternatively, install the project with pip and run the console command:

```sh
python -m pip install .
uart-mcp
```

For development and tests:

```sh
uv sync --group dev
uv run pytest
```

The automated tests use a fake serial device and do not require connected hardware.

### MCP client configuration

Example configuration for clients that support `mcpServers` (adjust the path to your checkout):

```json
{
  "mcpServers": {
    "uart-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/uart-mcp", "run", "uart-mcp"],
      "env": {
        "UART_MCP_LOG_DIR": "/absolute/path/to/uart-mcp-data/logs"
      }
    }
  }
}
```

On Windows, use absolute paths such as `C:\\Users\\you\\src\\uart-mcp`. The `UART_MCP_LOG_DIR` setting is optional; by default logs are written to the repository's `logs/` directory. Logs may contain device output, credentials, or other sensitive data, so choose and protect the directory accordingly.

### Tools

| Tool | Purpose |
| --- | --- |
| `list_ports` | Enumerate serial ports visible to the host. |
| `serial_open`, `serial_close`, `serial_status` | Manage and inspect background capture sessions. |
| `serial_read`, `serial_get_recent`, `serial_wait_for` | Consume captured output or wait for a regex/event. |
| `serial_search`, `serial_get_log`, `serial_clear_buffer` | Search persisted logs, page through a daily log, or clear the in-memory buffer. |
| `serial_write` | Write text or HEX to an open capture session. |
| `serial_send`, `serial_query` | Perform one-shot HEX transmission or write/read transactions. |
| `protocol_parse` | Parse a HEX response using a YAML protocol definition without opening a port. |
| `serial_shell` | Send a sequence of commands to a shell-like serial console. |

Use `serial_open` before the capture-session tools and `serial_close` when finished. If more than one session is open, specify `port` on operations that target a session. The `serial_read` tool advances a shared read cursor; use `serial_get_recent` for non-consuming inspection. Incoming data is line-oriented for capture tools, so prompts without a newline may not appear there.

### Safety and limitations

- `serial_write`, `serial_send`, `serial_query`, and `serial_shell` transmit data to real hardware. MCP annotations mark these as side-effecting, but annotations are advisory; review the payload and target port before use.
- `serial_shell` sends the supplied commands as-is. It is not a sandbox and does not validate commands for safety.
- The server is designed for local stdio use. It does not implement network transport, authentication, or multi-user access control.
- Capture logs are plain text and persist until removed by the operator.
- Serial permissions, driver installation, electrical levels, baud rate, and flow-control requirements depend on the host and attached device.
- DTR/RTS are left to pySerial defaults. Some adapters or boards may reset or enter a bootloader when a port is opened.

### Project layout

- `uart_mcp_server.py`: MCP stdio server and capture-session tools.
- `uart_cli.py`: CLI and one-shot serial operations reused by MCP tools.
- `uart_agent.py`: serial session and device I/O helpers.
- `test_uart_mcp_server.py`: hardware-free regression tests.
- `docs/`: hardware retest notes and implementation observations.

### License

MIT. See [LICENSE](LICENSE).