Serial MCP

🚀 Serial-MCP 串口服務器

Serial-MCP 是一款基於 asyncio 和 FastMCP 框架的串口通信協議轉換服務器。它具備豐富的功能模塊，可實現串口配置、消息收發、端口管理等操作，為串口通信提供了便捷高效的解決方案。

🚀 快速開始

啟動 Serial-MCP 串口服務器，只需執行以下命令：

python serial_MCP.py

✨ 主要特性

• 串口配置與管理：支持設置和修改串口參數（波特率、數據位、校驗位、停止位）。
• 消息通信：提供可靠的消息收發機制，支持大容量消息緩衝區。
• 多端口支持：能夠同時監聽和管理多個串口設備。
• 協議轉換：支持多種串口協議的自動識別與適配。

支持的串口參數

📦 安裝指南

本項目對系統環境有一定要求：

• 操作系統：Linux 或 macOS（推薦）。
• Python 版本：3.7 及以上版本。
• 依賴庫：
  • asyncio：異步編程支持。
  • websockets：WebSocket 協議實現。

所有配置均可以通過環境變量完成：

• SERIAL_PORT：指定默認使用的串口號（默認值為 /dev/tty.usb*）。
• SERIAL_BAUD_RATE：設置默認波特率（默認值為 9600）。
• SERIAL_BUFFER_LENGTH：配置消息緩衝區大小（默認值為 100）。

💻 使用示例

基礎用法

以下是一些常用操作的代碼示例：

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()                     # 關閉當前串口連接

📚 詳細文檔

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] 時間戳 - 模塊名：錯誤信息

🔧 技術細節

本項目的技術實現依賴於 asyncio 實現異步編程，websockets 實現 WebSocket 協議。系統要求操作系統為 Linux 或 macOS，Python 版本需 3.7 及以上。

📄 許可證

本項目採用 MIT 協議開源：

MIT License

貢獻指南

提交代碼

1. Fork 項目倉庫。
2. 創建新分支：git checkout -b feature/new-feature
3. 提交代碼：git commit -m "添加新功能"
4. 提交至 upstream：git push upstream feature/new-feature

提交問題

• 遇到問題請在 Issues 區提交，註明版本號和復現步驟。

聯繫方式

如有任何疑問，請聯繫：support@serial-mcp.com。