Serial-MCP

Serial-MCP

允许 Agent 与连接到计算机串行端口的设备通信的 MCP 服务。目前仅在 MAC 上经过测试。

基于 FastMCP 框架构建的可靠串行通信服务，提供稳定的串行端口通信接口，具备消息缓冲、错误处理和连接管理等功能。

安装

1. 克隆仓库：

git clone https://github.com/PaDev1/Serial-MCP.git
cd Serial-MCP

2. 安装依赖项：

pip install -r requirements.txt

安装后，按照以下结构将服务添加到 Claude Desktop 或类似应用中

"serial_MCP": { "command": "uv", "args": [ "run", "--with", "fastmcp,pyserial", "fastmcp", "run", "/serial_MCP.py" ], "env": { "SERIAL_PORT": "", "SERIAL_BAUD_RATE": "9600", "SERIAL_BUFFER_LENGTH": "100" } }

功能

• 异步串行通信：基于 asyncio 构建，可高效执行 I/O 操作
• 消息缓冲：缓冲区大小可配置，并支持时间戳
• 连接管理：自动检测端口并管理连接
• 错误处理：全面检测并报告错误
• 环境配置：支持环境变量和运行时配置
• 日志记录：详细记录日志、时间戳和错误信息

可用工具

1. delay

等待指定秒数。

参数：

• delay（float）：等待秒数（必须为正数）

返回：

• 成功状态
• 请求的延迟时间
• 实际延迟时间（测量值）
• 状态消息

示例：

await delay({
    "delay": 2.5  # Wait for 2.5 seconds
})

2. init_serial

使用指定参数初始化串行连接。

参数：

• port（str）：串行端口设备路径（例如，'/dev/tty.usbmodem1101'）
• baudrate（int）：通信波特率（默认值：9600）
• buffer_length（int）：缓冲的最大消息数（默认值：100）

返回：

• 初始化状态
• 当前模式（real/disconnected）
• 端口和波特率信息

3. send_message

通过串行连接发送消息，并可选择等待响应。

参数：

• message（str）：要发送的消息
• wait_for_response（bool）：发送后是否等待响应（默认值：False）
• response_timeout（float）：等待响应的秒数（默认值：0.5）

返回：

• success（bool）：操作是否整体成功
• status（str）：操作状态（"success"、"error" 等）
• mode（str）：当前连接模式（"real"、"disconnected"）
• write_status（str）：写入操作状态：
  • "success"：消息已成功写入
  • "failed"：写入操作失败
  • "timeout"：写入操作超时
• connection_state（str）：当前连接状态：
  • "connected"：串行端口已连接且可用
  • "disconnected"：没有活动的串行连接
  • "error"：连接处于错误状态
• response_status（str）：响应状态：
  • "not_checked"：未请求检查响应
  • "received"：已收到响应
  • "no_response"：超时时间内未收到响应
  • "error"：检查响应时发生错误
• response_messages（list）：收到的消息列表（如果有）
• bytes_written（int）：成功写入的字节数
• error_type（str）：操作失败时的错误类型
• message（str）：易于理解的状态消息
• error_details（dict）：适用时提供的其他错误信息

不检查响应的发送示例：

await send_message({
    "message": "Hello",
    "wait_for_response": False
})
# Returns:
{
    "success": True,
    "status": "success",
    "mode": "real",
    "write_status": "success",
    "connection_state": "connected",
    "response_status": "not_checked",
    "response_messages": [],
    "bytes_written": 6,
    "message": "Message sent successfully in real mode"
}

检查响应的发送示例：

await send_message({
    "message": "Hello",
    "wait_for_response": True,
    "response_timeout": 1.0
})
# Returns:
{
    "success": True,
    "status": "success",
    "mode": "real",
    "write_status": "success",
    "connection_state": "connected",
    "response_status": "received",
    "response_messages": [
        {
            "timestamp": "2024-03-14T15:30:45.123456",
            "message": "Hello received"
        }
    ],
    "bytes_written": 6,
    "message": "Message sent successfully in real mode"
}

超时时间内未收到响应的示例：

await send_message({
    "message": "Hello",
    "wait_for_response": True,
    "response_timeout": 0.5
})
# Returns:
{
    "success": True,
    "status": "success",
    "mode": "real",
    "write_status": "success",
    "connection_state": "connected",
    "response_status": "no_response",
    "response_messages": [],
    "bytes_written": 6,
    "message": "Message sent successfully in real mode"
}

4. read_message

从缓冲区读取消息。

参数：

• wait（bool）：缓冲区为空时是否等待消息（默认值：False）
• timeout（float）：等待消息的秒数（默认值：1.0）

返回：

• 带时间戳的消息列表
• 当前模式
• 读取操作状态

5. list_serial_ports

列出系统上所有可用的串口。

参数： 无

返回：

• 可用端口列表及其详细信息
• 端口名称和描述
• 硬件 ID

6. get_serial_status

获取串口连接的当前状态。

参数： 无

返回：

• 当前模式
• 端口和波特率信息
• 缓冲区长度
• 可用端口
• 上一条错误消息
• 串口模块是否可用

7. configure_serial

初始化后配置串口连接。

参数：

• port（str，可选）：要使用的新端口
• baudrate（int，可选）：要使用的新波特率
• list_ports（bool）：是否仅列出端口（默认值：False）

返回：

• 更新后的配置
• 当前模式
• 可用端口（如果 list_ports 为 True）

8. close_serial

关闭当前串口连接。

参数： 无

返回：

• 关闭状态
• 当前模式

9. help

获取有关如何使用 Serial MCP 服务的详细说明。

参数： 无

返回：

• 详细的帮助信息，包括：
  • 工具描述和参数
  • 每个工具的使用示例
  • 常见响应格式
  • 连接状态
  • 响应状态
  • 重要使用说明

示例：

await help()
# Returns comprehensive help information about all available tools and their usage

配置

可使用环境变量配置服务：

• SERIAL_PORT：串口设备路径（默认值：'/dev/tty.usb*'）
• SERIAL_BAUD_RATE：通信速率（默认值：9600）
• SERIAL_BUFFER_LENGTH：缓冲的最大消息数（默认值：100）

用法

启动服务

python serial_MCP.py

API 端点

初始化串口连接

await init_serial({
    "port": "/dev/tty.usbmodem1101",
    "baudrate": 9600,
    "buffer_length": 100
})

发送消息

await send_message({
    "message": "Hello, device!"
})

读取消息

await read_message({
    "wait": False,  # Whether to wait for messages
    "timeout": 1.0  # Timeout in seconds
})

列出可用端口

await list_serial_ports()

获取连接状态

await get_serial_status()

配置连接

await configure_serial({
    "port": "/dev/tty.usbmodem1101",
    "baudrate": 9600,
    "list_ports": False
})

关闭连接

await close_serial()

消息格式

缓冲区中的消息会附带时间戳存储：

{
    "timestamp": "2024-03-14T15:30:45.123456",  # ISO format
    "message": "Actual message content"
}

错误处理

服务会针对各种情况提供详细的错误消息：

• 连接失败
• 参数无效
• 超时
• 缓冲区溢出
• 消息无效

日志记录

日志写入 logs/serial_MCP.log，格式如下：

[timestamp] - [level] - [message]

要求

• Python 3.7+
• pyserial>=3.5
• fastmcp>=0.1.0
• pydantic>=2.0.0
• asyncio>=3.4.3

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 FastMCP 框架提供服务基础设施
• 感谢 pyserial 提供串口通信功能