Metadata-Version: 2.5
Name: serio-mcp
Version: 0.1.0
Summary: High-performance Model Context Protocol (MCP) server for serial/UART communication with real-time Expect state-machine support.
Project-URL: Homepage, https://github.com/weyou/serio-mcp
Project-URL: Repository, https://github.com/weyou/serio-mcp
Project-URL: Issues, https://github.com/weyou/serio-mcp/issues
Author-email: weyou <weyou.dev@gmail.com>
License: MIT
License-File: LICENSE
Keywords: antigravity,claude,cursor,embedded,expect,hardware,iot,mcp,model-context-protocol,serial,uart
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Embedded Systems
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyserial>=3.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# serio-mcp

[![PyPI version](https://img.shields.io/pypi/v/serio-mcp.svg?color=blue)](https://pypi.org/project/serio-mcp/)
[![Python Version](https://img.shields.io/pypi/pyversions/serio-mcp.svg)](https://pypi.org/project/serio-mcp/)
[![CI](https://github.com/weyou/serio-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/weyou/serio-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

**`serio-mcp`** is a high-performance **Model Context Protocol (MCP)** server that equips AI assistants (Claude Desktop, Cursor, Antigravity, VS Code) with reliable, zero-loss **Serial / UART** communication capabilities.

Engineered specifically for **embedded Linux development, hardware debugging, router recovery (U-Boot / Bootloader), and IoT automation**, featuring a dedicated **Expect State-Machine Engine** and a continuous background ingestion daemon to eliminate race conditions and dropped bytes.

---

## ✨ Features

- ⚡ **Zero-Loss Background Daemon**: A dedicated reader thread continuously ingests serial streams in the background—ensuring no characters or early bootlogs are dropped between tool calls.
- 🎯 **Atomic Expect Engine (`serial_expect`)**: Match multiple regular expressions or substring prompts (e.g. `['~ #', 'login:', 'Password:', 'IPQ807x#']`) in real-time.
- 🚀 **Prompt-Aware Execution (`serial_exec_expect`)**: Send shell/bootloader commands and automatically wait for the prompt to return, returning clean, isolated output.
- 🔌 **Dynamic Port Discovery & Switching**: Enumerate all attached hardware devices with VID/PID and switch ports or baud rates on the fly without restarting the server.
- ⌨️ **Raw Control Sequence Support**: Send `Ctrl+C` (`\x03`), `Enter` (`\r\n`), break signals, and custom byte sequences.
- 🛡️ **Cross-Platform**: Supports Linux, macOS, and Windows.

---

## 📦 Installation

### Quick Start with `uvx` (Recommended)

No manual installation required! Run directly with `uvx`:

```bash
uvx serio-mcp
```

### Installation with `pip` / `pipx`

```bash
pipx install serio-mcp
# or
pip install serio-mcp
```

---

## ⚙️ Configuration

### 1. Claude Desktop

Add this to your `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "serio": {
      "command": "uvx",
      "args": ["serio-mcp"]
    }
  }
}
```

### 2. Cursor IDE

Add to `.cursor/mcp.json` or Global Cursor Settings:

```json
{
  "mcpServers": {
    "serio": {
      "command": "uvx",
      "args": ["serio-mcp"]
    }
  }
}
```

### 3. Antigravity / Google AI Assistant

Add to `~/.gemini/config/mcp_config.json`:

```json
{
  "mcpServers": {
    "serio": {
      "command": "uvx",
      "args": ["serio-mcp"]
    }
  }
}
```

---

## 🛠️ Available MCP Tools

| Tool | Description |
| :--- | :--- |
| **`serial_list_ports`** | Enumerate all connected physical and virtual serial ports (with Device path, Description, VID, PID). |
| **`serial_configure`** | Dynamically connect to or switch serial port (`port='/dev/ttyUSB0'`, `baudrate=115200`). |
| **`serial_expect`** | Atomically send an optional command and wait for prompt patterns (`patterns=['# ', 'login:']`). |
| **`serial_exec_expect`** | Execute a command and automatically wait for the prompt to return, extracting clean output. |
| **`serial_send`** | Send raw strings, keys, or escape sequences (e.g. `\x03` for Ctrl+C, spaces for U-Boot intercept). |
| **`serial_read_buffer`** | Non-blocking read of newly accumulated incoming stream from the background buffer. |
| **`serial_get_history`** | Fetch recent line history captured by the background daemon. |
| **`serial_status`** | Query connection health, baud rate, buffer usage, and background worker status. |

---

## 💡 Practical Examples

### 1. Intercepting U-Boot Bootloader
```json
// Tool call: serial_expect
{
  "patterns": ["IPQ807x#", "Hit any key to stop autoboot:"],
  "command": " ",
  "timeout": 15.0
}
```

### 2. Handling Login Prompts
```json
// Step 1: Send username on login prompt
{
  "patterns": ["Password:", "# "],
  "command": "root",
  "timeout": 5.0
}

// Step 2: Send password on Password prompt
{
  "patterns": ["~ #", "# "],
  "command": "admin",
  "timeout": 5.0
}
```

### 3. Executing Shell Command
```json
// Tool call: serial_exec_expect
{
  "command": "uname -a; ifconfig br0",
  "timeout": 5.0
}
```

---

## 🧪 Development & Testing

```bash
# Clone the repository
git clone https://github.com/weyou/serio-mcp.git
cd serio-mcp

# Set up virtual environment with uv
uv venv
source .venv/bin/activate

# Install in editable mode with development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest -v

# Run linting
ruff check .
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).
