Metadata-Version: 2.3
Name: spes-serial-mcp
Version: 0.1.5
Summary: 基于 MCP 协议的本地串口通信服务，内置实时 Web 监控面板
Author: monyang
Author-email: monyang <mengyang@cvte.com>
Requires-Dist: mcp[cli]>=2.0.0
Requires-Dist: pyserial>=3.5
Requires-Dist: websockets>=16.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# Serial MCP

基于 MCP 协议的本地串口通信服务，内置实时 Web 监控面板。通过自然语言让 AI 助手与单片机、嵌入式设备直接对话。

## 功能特性

- 🖥️ **MCP 支持** — 通过 Model Context Protocol 与 AI 客户端无缝集成
- 🔌 **串口控制** — 自动扫描、连接、读写串口设备
- 🌐 **Web 监控面板** — 内置 HTTP + WebSocket 双端口服务，浏览器实时旁路监控，支持手动干预

## 可用工具

| 工具 | 说明 |
|------|------|
| `list_ports` | 扫描本机所有可用串口 |
| `connect_port` | 连接指定串口（支持自定义波特率，默认 115200） |
| `close_port` | 显式断开当前串口连接 |
| `write_data` | 向串口写入数据（自动补全换行符） |
| `read_data` | 读取串口缓冲区数据（含用户干预历史） |
| `start_monitor_ui` | 启动 Web 监控面板（默认 HTTP 8080 / WebSocket 8081） |

## 安装运行

```bash
uv sync
uv run spes-serial-mcp
```

## 客户端配置

### 方式一：一键安装（推荐）

在终端执行（需已安装 [uv](https://docs.astral.sh/uv/)）：

```bash
claude mcp add --scope user spes-serial-mcp -- uvx --from spes-serial-mcp spes-serial-mcp
```

执行后重启 Claude Code 会话生效，可用 `claude mcp list` 验证连接状态。

### 方式二：让 AI 自动添加

把下面的提示词发给 AI，即可自动完成安装配置：

```
请安装并配置 MCP 串口工具 spes-serial-mcp：
1. 执行 claude mcp add --scope user spes-serial-mcp -- uvx --from spes-serial-mcp spes-serial-mcp
2. 执行 claude mcp list 确认该服务状态为 connected
3. 完成后告诉我：需要重启 Claude Code 会话才能生效
```

## 快速开始

```
请使用串口工具，连接到我的开发板并且测试通信
```

启动后，AI 会自动执行以下初始化检查：

```
1. start_monitor_ui    → 启动 Web 面板 http://localhost:8080
2. list_ports          → 发现 COM3 等串口
3. connect_port        → 连接设备（115200）
4. write_data("hello") → 测试通信
5. read_data()         → 读取串口输入
```

在浏览器中打开 `http://localhost:8080`，你可以：

- 🔘 手动控制串口连接/断开
- 💬 实时查看 LLM 与单片机的全部对话
- ✏️ 手动下发命令（旁路干预）

## Web 面板使用说明

**面板不会随 MCP 服务自动启动**。MCP 服务本身只通过 stdio 运行，不监听任何 HTTP 端口；只有显式调用 `start_monitor_ui` 工具后，才会监听 8080 端口（WebSocket 端口为 8081，页面自动连接）。

对 AI 说以下指令即可启动：

```
启动监控面板
```

也可以指定其他端口，例如：

```
启动监控面板，使用端口 9090
```

（此时 HTTP 端口为 9090，WebSocket 自动使用 9091）

启动成功后 AI 会返回链接，再用浏览器访问即可。常见问题：

- **浏览器提示「无法访问此页面」**：面板尚未启动，请先让 AI 执行 `start_monitor_ui`
- **8080 端口被占用**：换一个端口启动即可
- **面板何时关闭**：面板运行在 MCP 服务进程的后台线程中，AI 客户端（Claude Code 等）退出后随之关闭

## Web面板功能

面板由顶栏状态区、设备连接管理、串口监视器三个区域组成：

### 顶栏状态区

- **串口状态胶囊** — 实时显示连接状态（端口 · 波特率），点击即可连接/断开串口
- **主题切换** — 浅色/深色主题一键切换，选择记忆在浏览器中
- **WebSocket 状态** — 显示与 MCP 服务的连接状态，断线后每 3 秒自动重连，点击可手动重连

### 设备连接管理

- **端口下拉框** — 点击时实时扫描本机串口，显示设备描述
- **波特率选择** — 支持 9600 ~ 921600 常用波特率，默认 115200
- **连接/断开按钮** — 连接后自动锁定端口与波特率设置，断开后恢复可选

### 串口监视器

- **实时日志** — 每条记录包含「时间戳 | 方向 | 来源 | 内容」四列，自动滚屏跟随最新数据；向上翻阅时暂停滚动，点击右下角按钮回到底部
- **来源分类** — 通过彩色标签区分数据来源：

  | 标签 | 方向 | 说明 |
  |------|------|------|
  | AI 发出 | TX | LLM 通过 MCP 工具写入串口的数据 |
  | 手动发送 | TX | 在面板中手动下发的命令 |
  | 下位机返回 | RX | 单片机等设备上报的数据 |
  | 系统 | SYS | 连接/断开等系统消息 |

- **TX/RX 计数** — 实时统计累计收发次数
- **保存LOG** — 一键将当前日志导出为 txt 文件，文件名形如 `serial-log-20260825-153000.txt`
- **清空缓存** — 一键清空日志显示

### 手动发送（旁路干预）

- 输入框输入命令后按 **Enter** 或点击「立即发送」下发；**↑↓** 键可切换历史命令（保留最近 50 条）
- 手动发送的命令会同步记录到 LLM 的读取缓冲区：AI 调用 `read_data` 时会优先返回你的干预记录与下位机回应，实现人机协作调试