serial-mcp

🚀 Serial - MCP 串口服务器

Serial - MCP 是基于 asyncio 和 FastMCP 框架的串口通信协议转换服务器。它支持串口配置、消息收发、端口管理等多种功能模块，能有效解决串口通信中的协议转换问题，为串口设备的通信提供便捷、高效的解决方案。

🚀 快速开始

启动服务器

python serial_MCP.py

✨ 主要特性

核心功能

• 串口配置与管理：支持设置和修改串口参数（波特率、数据位、校验位、停止位）。
• 消息通信：提供可靠的消息收发机制，支持大容量消息缓冲区。
• 多端口支持：能够同时监听和管理多个串口设备。
• 协议转换：支持多种串口协议的自动识别与适配。

支持的串口参数

• 波特率：9600, 115200 等标准波特率。
• 数据位：8 位数据位默认支持，可扩展其他配置。
• 校验方式：支持无校验、奇校验、偶校验。
• 停止位：支持 1 位和 2 位停止位。

💻 使用示例

基础用法

1. 初始化串口连接

await init_serial({
    "port": "/dev/tty.usbmodem1101",     # 串口号
    "baudrate": 9600,                   # 波特率
    "buffer_length": 100                # 缓冲区长度
})

2. 发送消息

await send_message({
    "message": "Hello, device!"          # 待发送的消息内容
})

3. 接收消息

await read_message({
    "wait": False,                       # 是否等待消息，默认False
    "timeout": 1.0                      # 等待超时时间，单位秒
})

4. 列出可用串口

await list_serial_ports()                # 返回所有可用串口信息

5. 获取连接状态

await get_serial_status()                # 返回当前串口连接状态

6. 配置串口参数

await configure_serial({
    "port": "/dev/tty.usbmodem1101",     # 新的串口号，可选
    "baudrate": 9600,                   # 新的波特率，可选
    "list_ports": False                 # 是否仅列出端口，默认False
})

7. 关闭串口连接

await close_serial()                     # 关闭当前串口连接

📚 详细文档

配置说明

所有配置均可以通过环境变量完成：

• SERIAL_PORT：指定默认使用的串口号（默认值为 /dev/tty.usb*）。
• SERIAL_BAUD_RATE：设置默认波特率（默认值为 9600）。
• SERIAL_BUFFER_LENGTH：配置消息缓冲区大小（默认值为 100）。

API 端点说明

串口数据接收

• 功能：实时监听并接收来自串口设备的数据。
• 接口：/serial/receive
• 请求方式：WebSocket
• 参数：
  • port：必填，目标串口号。

消息发送控制

• 功能：向指定串口发送预处理的消息内容。
• 接口：/serial/send
• 请求方式：POST
• 参数：
  • message：必填，待发送的字符串消息。
  • port：可选，默认使用当前配置端口。

端口状态查询

• 功能：获取所有可用串口及其连接状态。
• 接口：/serial/status
• 请求方式：GET

消息格式

接收消息格式

{
    "port": "string",                   // 串口号
    "data": "string",                   // 接收到的原始数据
    "timestamp": number,                // 时间戳
    "status": boolean                   // 接收状态
}

发送消息格式

{
    "message": "string"                 // 待发送的消息内容
}

错误处理

常见错误码

• 400 Bad Request：请求参数格式错误。
• 503 Service Unavailable：指定串口未连接或不可用。

自定义错误消息

{
    "error": {
        "code": number,                 // 错误代码
        "message": string               // 错误描述
    }
}

日志记录

所有操作均支持日志输出，日志格式如下：

[INFO] 时间戳 - 模块名：操作描述
[ERROR] 时间戳 - 模块名：错误信息

🔧 技术细节

系统需求

• 操作系统：Linux 或 macOS（推荐）。
• Python 版本：3.7 及以上版本。
• 依赖库：
  • asyncio：异步编程支持。
  • websockets：WebSocket 协议实现。

🤝 贡献指南

提交代码

1. Fork 项目仓库。
2. 创建新分支：git checkout -b feature/new - feature
3. 提交代码：git commit -m "添加新功能"
4. 提交至 upstream：git push upstream feature/new - feature

提交问题

• 遇到问题请在 Issues 区提交，注明版本号和复现步骤。

📄 许可证

本项目采用 MIT 协议开源：

MIT License

📞 联系方式

如有任何疑问，请联系：support@serial - mcp.com。