# MCP 串口工具：核心命令参数与返回值规范
**版本**：0.1
**适用**：开发串口 AT/数据通信的 MCP 工具
**特性**：同步写入 + 异步主动上报 + 串口状态查询 + 日志查询
## 1. serial.open（必须）
### 功能
打开串口端口并配置所有参数。
### 参数
| 名称 | 类型 | 必须 | 说明 |
|------|------|------|------|
| port | string | ✔ | 串口名称，如 "COM3"、"/dev/ttyUSB0" |
| baudrate | int | ✔ | 波特率，如 9600、115200 |
| data_bits | int | ✔ | 5 / 6 / 7 / 8 |
| parity | string | ✔ | "none" / "even" / "odd" |
| stop_bits | float/int | ✔ | 1 / 1.5 / 2 |
| flow_control | string | ✔ | "none" / "rts_cts" / "xon_xoff" |
### 成功返回
```json
{
"status": "ok",
"port": "COM3",
"config": {
"baudrate": 115200,
"data_bits": 8,
"parity": "none",
"stop_bits": 1,
"flow_control": "none"
}
}
```
### 失败返回
```json
{
"status": "error",
"error_code": "PORT_BUSY",
"message": "Port COM3 is already in use."
}
```
## 2. serial.list（必须）
### 功能
列举当前系统可用的串口端口。
### 参数
无参数
### 返回示例
```json
{
"status": "ok",
"ports": [
{
"name": "COM3",
"description": "USB Serial Port (COM3)",
"manufacturer": "FTDI",
"vid": "0403",
"pid": "6001",
"is_available": true
},
{
"name": "COM5",
"description": "Communications Port (COM5)",
"manufacturer": "Microsoft",
"vid": null,
"pid": null,
"is_available": true
}
]
}
```
## 3. serial.close（必须）
### 参数
| 名称 | 类型 | 必须 | 说明 |
|------|------|------|------|
| port | string | ✔ | 要关闭的端口 |
### 返回
#### 成功
```json
{ "status": "ok" }
```
#### 失败
```json
{
"status": "error",
"error_code": "NOT_OPEN",
"message": "Port COM3 is not open."
}
```
## 4. serial.write（超级简化版）⭐最终模型
### 核心原则
简单、可控、无协议假设。只做两件事：
1. 写入数据
2. 在 timeout 内收集所有收到的字节 → 单段返回
**唯一结束条件 = timeout 到达**
### 参数（最终精简版）
| 名称 | 类型 | 必须 | 说明 |
|------|------|------|------|
| port | string | ✔ | 串口端口 |
| data | string(hex) | ✔ | 写入字节数据 |
| timeout_ms | int | ✔ | 写入后的等待时间 |
> 注：没有 terminator / 没有 max_responses / 没有 min_gap
### 返回示例
#### 成功返回
```json
{
"status": "ok",
"timeout_ms": 2000,
"raw_hex": "2B435245470D0A4F4B0D0A",
"text": "+CREG: 0\r\nOK\r\n"
}
```
#### 超时但部分数据
```json
{
"status": "timeout",
"partial": true,
"raw_hex": "2B435245470D0A",
"text": "+CREG: 0\r\n"
}
```
#### 完全无数据
```json
{
"status": "timeout",
"partial": false,
"raw_hex": "",
"text": ""
}
```
### 内部工作逻辑
#### 阶段 1：写数据
- 将 hex 转为字节流
- 写入串口
- 立即 flush
#### 阶段 2：持续收集数据（直到 timeout）
- 启动计时器
- 期间无判断：
- ❌ 不找 terminator
- ❌ 不分段
- ❌ 不解析 AT
- ❌ 不判断 OK/ERROR
- 所有读到的数据不断 append 到 buffer
#### 阶段 3：timeout → 返回
- 停止读取
- 将 buffer 转 hex/text
- 若 buffer 有数据 → partial = true
- 若无数据 → partial = false
> 🎯 LLM 自行判断数据含义，工具完全不解释协议。
## 5. 主动上报系统（serial.subscribe / report / unsubscribe）
用于 URC、GNSS、网络事件、模块日志等异步数据。
### 4.1 serial.subscribe
订阅指定串口的主动上报事件。
#### 请求
```json
{
"method": "serial.subscribe",
"params": {
"port": "COM3",
"types": ["data", "error", "status"]
}
}
```
#### 响应
```json
{
"result": {
"subscribed": true
}
}
```
### 4.2 serial.unsubscribe
取消某个端口的订阅。
#### 请求
```json
{
"method": "serial.unsubscribe",
"params": {
"port": "COM3"
}
}
```
#### 响应
```json
{
"result": {
"unsubscribed": true
}
}
```
### 4.3 serial.unsubscribe_all
清除所有订阅。
#### 请求
```json
{
"method": "serial.unsubscribe_all",
"params": {}
}
```
#### 响应
```json
{
"result": {
"unsubscribed": true
}
}
```
## 6. MCP 主动上报事件（serial.report）
所有主动事件（URC、日志、错误、状态变化）通过 Notification 推送。
### 上报格式（notification）
```json
{
"method": "serial.report",
"params": {
"port": "COM3",
"timestamp": "2025-11-14T09:35:22.123Z",
"type": "data",
"data": "+CSQ: 23,99\r\n"
}
}
```
### 字段说明
| 字段 | 说明 |
|------|------|
| port | 来源串口 |
| timestamp | ISO8601 |
| type | data / error / status |
| data | UTF-8（或必要时 base64） |
## 7. serial.status（必须）
返回串口当前状态。
### 返回示例
```json
{
"status": "ok",
"port": "COM3",
"is_open": true,
"config": {
"baudrate": 115200,
"data_bits": 8,
"parity": "none",
"stop_bits": 1,
"flow_control": "none"
},
"signals": {
"CTS": 1,
"DSR": 0,
"DCD": 0,
"RI": 0
}
}
```
## 8. health.ping（必须）
用于健康检查。
### 返回示例
```json
{
"status": "ok",
"version": "0.1.3",
"uptime": 12832,
"last_error": null
}
```
## 9. trace.get_log（推荐）
获取串口日志（用于调试/AI 回溯）。
### 参数
| 名称 | 类型 | 必须 | 说明 |
|------|------|------|------|
| port | string | ✔ | 串口名称 |
| since | string | ✘ | ISO 时间（可选） |
| limit_kb | int | ✘ | 最大大小 |
| compress | bool | ✘ | gzip+base64 返回 |
### 返回示例
```json
{
"status": "ok",
"log_base64": "<...>",
"compressed": true
}
```