Serial Web Terminal MCP

Ein Model Context Protocol-Server, der KI-Programmierassistenten (Claude Code, Cursor, Windsurf usw.) die Interaktion mit seriellen Schnittstellengeräten ermöglicht.

KI-Agenten können eine Verbindung zu seriellen Geräten herstellen, Befehle senden und Ausgaben erfassen – während Benutzer den gesamten Prozess in Echtzeit über ein browserbasiertes Terminal verfolgen.

✨ Funktionen

• 🔌 Serielle Verbindung — Verbindung zu COM-Ports, /dev/ttyUSB*, /dev/ttyS* usw. mit automatischem Login

• 🖥️ Web-Terminal — xterm.js-Browser-Terminal mit Echtzeit-Serien-E/A (wie Xshell)

• 🤖 MCP-Server — Native Tool-Integration; KI-Agenten rufen direkt über das MCP-Protokoll auf

• 📝 Zeitgestempelte Protokolle — Jede Zeile wird mit Zeitstempel protokolliert, tägliche Rotation, entspricht exakt der Terminalanzeige

• ⌨️ Bidirektional — KI sendet Befehle + Benutzer kann manuell im Browser-Terminal tippen

• 🌐 Mehrsprachiger Login — Erkennt Login-/Passwort-Aufforderungen in Englisch, Chinesisch und Japanisch

• ⏱️ Warten-und-Senden — Warte auf bestimmte Ausgabe und sende dann sofort Daten (z. B. uboot-Passwortfenster)

• 🛡️ Timeout-Wiederherstellung — Automatisches Strg+C bei Timeout, keine hängenden Sitzungen

📦 Installation

pip install mcp pyserial aiohttp

Oder aus den Anforderungen:

pip install -r requirements.txt

🚀 Schnellstart

1. Konfigurieren Sie Ihren KI-Client

Claude Code (.mcp.json im Projektstamm oder ~/.claude/claude_config.json):

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

Cursor (Einstellungen → MCP → Server hinzufügen):

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

Siehe examples/ für gebrauchsfertige Konfigurationsdateien.

2. Sprechen Sie mit Ihrem KI-Assistenten

> 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

Öffnen Sie http://localhost:8080 in Ihrem Browser, um die seriellen Operationen der KI in Echtzeit zu verfolgen.

🔧 MCP-Tools

serial_connect

Mit einem seriellen Gerät mit optionalem automatischem Login verbinden.

serial_send

Einen Shell-Befehl senden und die Ausgabe erfassen.

serial_wait_send

Auf eine bestimmte Zeichenfolge in der seriellen Ausgabe warten, dann sofort Daten senden. Ideal für:

• Eingabe von uboot während des Neustarts (3-Sekunden-Passwortfenster)

• Reaktion auf Login-Aufforderungen

• Jede „Warte auf X, dann sende Y“-Automatisierung

🖥️ Eigenständige Nutzung (ohne MCP)

serial_web.py kann unabhängig über die HTTP-API ausgeführt werden:

# 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"

CLI-Argumente

📝 Protokollformat

Protokolle werden in logs/serial_YYYYMMDD.log gespeichert (tägliche Rotation):

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  >>> 自动登录流程完成

• Terminalausgabe: Zeitstempel Inhalt (aus dem xterm.js-Puffer extrahiert – entspricht exakt der Browseranzeige)

• Systemereignisse: Zeitstempel >>> Nachricht (Login, Start usw.)

Zeilenwiedergabetreue:

• Keine Umbruchaufteilung — Zeilen, die vom Terminal umbrochen wurden (80-Spalten-Umbruch), werden wieder zu einer einzigen logischen Zeile zusammengeführt

• Fortschrittsbalken-erkennend — \r-Überschreibungssequenzen (10%\r20%\r30%) werden auf den endgültigen sichtbaren Zustand (30%) reduziert

• Rücktasten-erkennend — Manuelle Bearbeitungen mit Rücktaste werden als die endgültig bearbeitete Zeile aufgezeichnet

• Jede Zeile trägt immer einen Zeitstempel-Präfix

🏗️ Architektur

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)

📁 Projektstruktur

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

🧪 Testen

Führen Sie die Regressionstestsuite aus (kein physisches serielles Gerät erforderlich):

python tests/test_regression.py -v

Tests umfassen:

• Ausgabebereinigung (ANSI-Entfernung, Echo-Entfernung, Eingabeaufforderungsentfernung)

• Erkennung von Eingabeaufforderungen (Shell-Eingabeaufforderungen, bekannte Eingabeaufforderungen)

• Protokollzeilenpufferung (Rücktastenbehandlung, Teilzeilen, ANSI-Bereinigung)

• Erkennung von Schlüsselwörtern für automatischen Login (Englisch, Chinesisch, Japanisch)

• Befehl senden/empfangen (seriell simulieren, Timeout, Strg+C-Wiederherstellung)

• Warten-und-Senden (sofortige Übereinstimmung, dynamische Übereinstimmung, Timeout, Auslöser)

• HTML-Seitenstruktur (keine doppelten IDs, erforderliche Elemente)

• MCP-Server-Tool-Registrierung

• HTTP-API-Endpunkte (Status, Senden, Rohdaten, Protokoll – Fehlerbehandlung)

• Sicherheit (keine fest codierten Anmeldeinformationen, .gitignore-Abdeckung)

🌐 Automatischer Login

Der automatische Login-Ablauf unterstützt mehrsprachige Eingabeaufforderungen:

Login-Ablauf:

1. Eingabetaste senden, um das Terminal zu aktivieren

2. login:-Eingabeaufforderung erkennen → Benutzername senden

3. Password:-Eingabeaufforderung erkennen → Passwort senden

4. Auf Shell-Eingabeaufforderung warten

5. stty cols 200 ausführen (breites Terminal, verhindert 80-Spalten-Umbruch)

6. --init-cmd ausführen (Standard: unset TMOUT)

Wenn bereits angemeldet (keine Login-Eingabeaufforderung erkannt), wird zu Schritt 5 gesprungen.

📄 Lizenz

MIT