MCP 服务器

coserial

Enables humans and AI agents to collaboratively control serial ports via MCP tools or Web UI, with real-time data sharing across all participants.

README

coserial

简体中文 | English

Collaborative Serial Debug Bridge. Humans and AI Agents co-control serial ports via MCP tools or Web UI, sharing all IO data in real time. Humans, Agents, and hardware — all on the same page.

Architecture

Agent A ── MCP stdio ── coserial-client ──┐
Agent B ── MCP stdio ── coserial-client ──┤
Agent C ── MCP stdio ── coserial-client ──┤
...                                       │ HTTP (localhost)
Human A ── Web UI ────────────────────────┤
Human B ── Web UI ────────────────────────┤
...                                       ▼
                         coserial-server
                         ├── HTTP API (/mcp/…)     ← MCP tool calls
                         ├── WebSocket /ws         ← Web UI real-time data
                         ├── GET /                 ← Web UI (HTML/CSS/JS)
                         ├── SessionManager
                         │   ├── COM1
                         │   ├── COM2
                         │   └── ...
                         └── Web UI Monitor

Features

🤝 Human-Agent Collaboration — Humans and AI Agents share the same serial session, debugging in real time
🔌 MCP Tool Control — Agents read/write serial ports, wait for pattern matches, send commands, etc. via standard MCP protocol
🖥️ Web UI Monitor — Dark theme, real-time RX/TX data stream, HEX display, search highlighting, log export
🔄 Three-Party Data Sync — Agent I/O and Web UI I/O write to the same buffer — nobody misses anything
📡 Multi-Session Management — Connect to multiple serial ports simultaneously, switch via Web UI dropdown
🔧 Signal Line Control — DTR/RTS hardware reset support
📝 Log Persistence — Serial I/O automatically recorded to file
🎯 Zero-Build Frontend — Vanilla HTML/CSS/JS, no frontend toolchain required

Quick Start

Install

# Clone the repo
git clone https://github.com/FlipFlopszzz/coserial.git
cd coserial

# Install dependencies (requires uv)
uv sync

Launch

# Start server + open Web UI (manual debug mode)
uv run coserial

# Start and auto-connect to COM20
uv run coserial COM20

# List all active sessions
uv run coserial list

# Start server only (headless)
uv run coserial-server

MCP Tools

Tool	Description
`server()`	Discover/start server process, returns port
`open_session(port, baud)`	Create a serial session, returns session_id
`close_session(session_id)`	Close a specific session
`write(session_id, data)`	Send data to serial port
`read(session_id, timeout, size)`	Read buffer data
`wait_for(session_id, pattern, timeout)`	Wait for output matching a regex
`command(session_id, data, expect, timeout)`	Send command and wait for response
`set_params(session_id, baud, ...)`	Dynamically adjust serial parameters
`get_params(session_id)`	Get full session parameters
`set_signals(session_id, dtr, rts)`	Control DTR/RTS signal lines
`list_ports()`	List available serial ports
`list_sessions()`	List all active sessions
`web(port)`	Open Web UI in system browser
`preview(port)`	Return URL for Agent's embedded browser
`shutdown_server()`	Shut down server process

Web UI

Open http://127.0.0.1:37210/ directly in your system browser, or via any Agent tool's embedded browser.

Project Structure

coserial/
├── pyproject.toml
├── src/coserial/
│   ├── __main__.py       # Entry: uv run coserial
│   ├── client.py         # MCP stdio client → HTTP proxy to server
│   ├── server.py         # Server: HTTP API + WebSocket + Web UI
│   ├── session.py        # SessionBuffer + SerialSession + SessionManager
│   └── web_ui/
│       └── index.html    # Single-page HTML, inline CSS/JS