Serial Web Terminal MCP

Сервер Model Context Protocol, предоставляющий AI-ассистентам (Claude Code, Cursor, Windsurf и др.) возможность взаимодействовать с устройствами через последовательный порт.

AI-агенты могут подключаться к последовательным устройствам, отправлять команды и захватывать вывод — при этом пользователь наблюдает за всем процессом в реальном времени через браузерный терминал.

✨ Возможности

• 🔌 Подключение по RS-232 — Подключайтесь к COM-портам, /dev/ttyUSB*, /dev/ttyS* и др. с автоматическим входом

• 🖥️ Веб-терминал — Браузерный терминал xterm.js, показывающий последовательный ввод/вывод в реальном времени (как Xshell)

• 🤖 MCP-сервер — Нативная интеграция инструментов; AI-агенты вызывают напрямую через протокол MCP

• 📝 Логи с метками времени — Каждая строка логируется с меткой времени, ежедневная ротация, полное соответствие отображению в терминале

• ⌨️ Двунаправленность — AI отправляет команды + пользователь может печатать вручную в браузерном терминале

• 🌐 Многоязычный вход — Автоматически определяет приглашения входа/пароля на английском, китайском и японском

• ⏱️ Ожидание и отправка — Ожидание конкретного вывода, затем немедленная отправка данных (например, окно пароля uboot)

• 🛡️ Восстановление по тайм-ауту — Автоматический Ctrl+C при тайм-ауте, без зависших сессий

Related MCP server: UART MCP Server

📦 Установка

pip install mcp pyserial aiohttp

Или из зависимостей:

pip install -r requirements.txt

🚀 Быстрый старт

1. Настройте ваш AI-клиент

Claude Code (.mcp.json в корне проекта или ~/.claude/claude_config.json):

{
  "mcpServers": {
    "serial-terminal": {
      "command": "python",
      "args": ["/path/to/serial_mcp_server.py"]
    }
  }
}

Cursor (Настройки → MCP → Добавить сервер):

{
  "mcpServers": {
    "serial-terminal": {
      "command": "python",
      "args": ["/path/to/serial_mcp_server.py"]
    }
  }
}

См. examples/ для готовых файлов конфигурации.

2. Общайтесь с вашим AI-ассистентом

> List available serial ports
AI: [calls serial_list_ports] → Found COM3, COM4...

> Connect to COM3, username admin, password ****
AI: [calls serial_connect(port="COM3", login_user="admin", login_pass="****")]
    → Serial connected, Web terminal: http://localhost:8080

> Run uname -a
AI: [calls serial_send(command="uname -a")]
    → Linux device 4.19.246 aarch64 GNU/Linux

Откройте http://localhost:8080 в вашем браузере, чтобы наблюдать за операциями AI через последовательный порт в реальном времени.

🔧 Инструменты MCP

serial_connect

Подключиться к последовательному устройству с опциональным автоматическим входом.

serial_send

Отправить команду оболочки и захватить вывод.

serial_wait_send

Ожидать конкретную строку в выводе последовательного порта, затем немедленно отправить данные. Идеально подходит для:

• Входа в uboot во время перезагрузки (3-секундное окно пароля)

• Ответа на приглашения входа

• Любой автоматизации «ожидать X, затем отправить Y»

🖥️ Автономное использование (без MCP)

serial_web.py может работать независимо через HTTP API:

# Start with auto-login
python serial_web.py --port COM3 --baud 115200 \
  --login-user admin --login-pass secret \
  --init-cmd "unset TMOUT"

# List available ports
python serial_web.py --list

HTTP API

# Send a command
curl -s -X POST http://localhost:8080/api/send \
     -H "Content-Type: application/json" \
     -d '{"command":"ls /","timeout":5}'

# Send raw data (Ctrl+C)
curl -s -X POST http://localhost:8080/api/raw \
     -H "Content-Type: application/json" \
     -d '{"data":"\x03"}'

# Wait-and-send
curl -s -X POST http://localhost:8080/api/wait-send \
     -H "Content-Type: application/json" \
     -d '{"wait_for":"login:","send_data":"admin","timeout":30}'

# Check status
curl -s http://localhost:8080/api/status

# Get logs
curl -s "http://localhost:8080/api/log?lines=50"

Аргументы командной строки

📝 Формат лога

Логи сохраняются в logs/serial_YYYYMMDD.log (ежедневная ротация):

2026-08-06 15:32:22  device # uname -a
2026-08-06 15:32:22  Linux device 4.19.246 aarch64 GNU/Linux
2026-08-06 15:32:23  device # cat /proc/cpuinfo | head -5
2026-08-06 15:32:23  processor	: 0
2026-08-06 15:32:23  >>> 自动登录流程完成

• Вывод терминала: метка_времени содержимое (извлечено из буфера xterm.js — полностью соответствует отображению в браузере)

• Системные события: метка_времени >>> сообщение (вход, запуск и т.д.)

Точность строк лога:

• Нет разрывов переноса — строки, мягко перенесенные терминалом (80-колоночный перенос), объединяются обратно в одну логическую строку

• Поддержка индикаторов прогресса — последовательности перезаписи \r (10%\r20%\r30%) сворачиваются в конечное видимое состояние (30%)

• Поддержка Backspace — ручные правки с Backspace записываются как окончательная отредактированная строка

• Каждая строка всегда имеет префикс с меткой времени

🏗️ Архитектура

AI Agent (Claude Code / Cursor / ...)
  └─ MCP Protocol (stdio)
      └─ serial_mcp_server.py
          └─ HTTP API
              └─ serial_web.py (aiohttp)
                  ├─ Serial Port (pyserial)
                  ├─ Web Terminal (xterm.js + WebSocket)
                  └─ Log Recording

Browser
  └─ http://localhost:8080
      ├─ xterm.js terminal (real-time serial data)
      └─ Log panel (timestamped logs)

📁 Структура проекта

serial-web-terminal/
├── serial_web.py              # Core: Web terminal + HTTP API
├── serial_mcp_server.py       # MCP Server (wraps HTTP API)
├── tests/
│   └── test_regression.py     # Regression test suite (68 tests)
├── examples/
│   ├── claude-code.json       # Claude Code MCP config
│   └── cursor.json            # Cursor MCP config
├── requirements.txt
├── LICENSE
└── README.md

🧪 Тестирование

Запустите набор регрессионных тестов (не требует физического последовательного устройства):

python tests/test_regression.py -v

Тесты охватывают:

• Очистка вывода (удаление ANSI-кодов, удаление эха, удаление приглашений)

• Обнаружение приглашений (приглашения оболочки, известные приглашения)

• Буферизация строк логов (обработка Backspace, неполных строк, очистка ANSI)

• Обнаружение ключевых слов автоматического входа (английский, китайский, японский)

• Отправка/получение команд (мок-последовательный порт, тайм-аут, восстановление через Ctrl+C)

• Ожидание и отправка (немедленное совпадение, динамическое совпадение, тайм-аут, триггер)

• Структура HTML-страницы (без дублирующихся ID, обязательные элементы)

• Регистрация инструментов MCP-сервера

• Конечные точки HTTP API (статус, отправка, сырые данные, логи — обработка ошибок)

• Безопасность (нет жестко закодированных учетных данных, покрытие .gitignore)

🌐 Автоматический вход

Процесс автоматического входа поддерживает многоязычные приглашения:

Процесс входа:

1. Отправить Enter для пробуждения терминала

2. Обнаружить приглашение login: → отправить имя пользователя

3. Обнаружить приглашение Password: → отправить пароль

4. Ожидать приглашение оболочки

5. Выполнить stty cols 200 (широкий терминал, предотвращает 80-колоночный перенос)

6. Выполнить --init-cmd (по умолчанию: unset TMOUT)

Если уже выполнен вход (приглашение входа не обнаружено), пропустить шаги со 2 по 4.

📄 Лицензия

MIT