Serial MCP

🚀 Serial-MCP Serial Server

Serial-MCP is a serial communication protocol conversion server based on the asyncio and FastMCP frameworks. It supports multiple functional modules, including serial port configuration, message sending and receiving, and port management.

🚀 Quick Start

Prerequisites

• Operating System: Linux or macOS (recommended).
• Python Version: 3.7 or higher.
• Dependencies:
  • asyncio: Support for asynchronous programming.
  • websockets: Implementation of the WebSocket protocol.

Starting the Server

python serial_MCP.py

✨ Features

Core Features

• Serial Port Configuration and Management: Supports setting and modifying serial port parameters (baud rate, data bits, parity bit, stop bits).
• Message Communication: Provides a reliable message sending and receiving mechanism, supporting a large-capacity message buffer.
• Multi-Port Support: Can simultaneously monitor and manage multiple serial port devices.
• Protocol Conversion: Supports automatic recognition and adaptation of multiple serial port protocols.

Supported Serial Port Parameters

• Baud Rate: Standard baud rates such as 9600, 115200.
• Data Bits: 8 data bits are supported by default, and other configurations can be extended.
• Parity Mode: Supports no parity, odd parity, and even parity.
• Stop Bits: Supports 1 and 2 stop bits.

📦 Installation

All configurations can be completed through environment variables:

• SERIAL_PORT: Specifies the default serial port number (default value is /dev/tty.usb*).
• SERIAL_BAUD_RATE: Sets the default baud rate (default value is 9600).
• SERIAL_BUFFER_LENGTH: Configures the message buffer size (default value is 100).

💻 Usage Examples

Basic Usage

1. Initializing the Serial Port Connection

await init_serial({
    "port": "/dev/tty.usbmodem1101",     # Serial port number
    "baudrate": 9600,                   # Baud rate
    "buffer_length": 100                # Buffer length
})

2. Sending a Message

await send_message({
    "message": "Hello, device!"          # Message content to be sent
})

3. Receiving a Message

await read_message({
    "wait": False,                       # Whether to wait for a message, default is False
    "timeout": 1.0                      # Waiting timeout in seconds
})

4. Listing Available Serial Ports

await list_serial_ports()                # Returns information about all available serial ports

5. Getting the Connection Status

await get_serial_status()                # Returns the current serial port connection status

6. Configuring Serial Port Parameters

await configure_serial({
    "port": "/dev/tty.usbmodem1101",     # New serial port number, optional
    "baudrate": 9600,                   # New baud rate, optional
    "list_ports": False                 # Whether to only list ports, default is False
})

7. Closing the Serial Port Connection

await close_serial()                     # Closes the current serial port connection

API Endpoint Explanation

Serial Data Reception

• Function: Monitors and receives data from serial port devices in real-time.
• Interface: /serial/receive
• Request Method: WebSocket
• Parameters:
  • port: Required, target serial port number.

Message Sending Control

• Function: Sends preprocessed message content to the specified serial port.
• Interface: /serial/send
• Request Method: POST
• Parameters:
  • message: Required, string message to be sent.
  • port: Optional, uses the currently configured port by default.

Port Status Query

• Function: Gets all available serial ports and their connection statuses.
• Interface: /serial/status
• Request Method: GET

📚 Documentation

Message Format

Received Message Format

{
    "port": "string",                   // Serial port number
    "data": "string",                   // Received raw data
    "timestamp": number,                // Timestamp
    "status": boolean                   // Reception status
}

Sent Message Format

{
    "message": "string"                 // Message content to be sent
}

Error Handling

Common Error Codes

• 400 Bad Request: Incorrect request parameter format.
• 503 Service Unavailable: Specified serial port is not connected or unavailable.

Custom Error Message

{
    "error": {
        "code": number,                 // Error code
        "message": string               // Error description
    }
}

Logging

All operations support log output. The log format is as follows:

[INFO] Timestamp - Module Name: Operation description
[ERROR] Timestamp - Module Name: Error information

🔧 Technical Details

System Requirements

• Operating System: Linux or macOS (recommended).
• Python Version: 3.7 or higher.
• Dependency Libraries:
  • asyncio: Support for asynchronous programming.
  • websockets: Implementation of the WebSocket protocol.

🤝 Contribution Guidelines

Submitting Code

1. Fork the project repository.
2. Create a new branch: git checkout -b feature/new-feature
3. Commit your code: git commit -m "Add new feature"
4. Push to upstream: git push upstream feature/new-feature

Submitting Issues

• If you encounter any issues, please submit them in the Issues section, indicating the version number and reproduction steps.

📄 License

This project is open-sourced under the MIT License:

MIT License

📞 Contact

If you have any questions, please contact: support@serial-mcp.com.