Serial Bridge

Serial Bridge ist ein Hub, der zwei serielle Konsolen zwischen einem lokalen Operator und MCP-Agents teilt. Es ist nicht betriebssystemspezifisch: Installieren Sie die Python-Pakete in requirements.txt und führen Sie es auf einem beliebigen Host mit Python 3.10+ aus. Der Hub befindet sich im Paket serial_bridge/; starten Sie ihn mit python -m serial_bridge oder dem Wrapper app.py im Stammverzeichnis.

Installation und Start

Python 3.10 oder neuer wird empfohlen.

python -m pip install -r requirements.txt
python -m serial_bridge

Die folgenden Shell-Ausschnitte verwenden PowerShell ($env:NAME = "..."). Unter bash oder zsh setzen Sie dieselben Namen mit export NAME=....

Der Hub öffnet Ihren Browser mit der Konsole unter http://127.0.0.1:8765/, sobald er lauscht. Der Wrapper app.py im Stammverzeichnis ist gleichwertig. Um ohne Öffnen eines Browser-Tabs zu starten:

$env:SERIAL_BRIDGE_OPEN_UI = "off"
python -m serial_bridge

Oder übergeben Sie --no-open-ui. Verwenden Sie --open-ui, um das Öffnen zu erzwingen, wenn die Umgebung es deaktiviert. Wenn SERIAL_BRIDGE_OPEN_UI nicht gesetzt ist, wird standardmäßig geöffnet; nur 0, false, no und off (ohne Beachtung der Groß-/Kleinschreibung) deaktivieren es.

Beim ersten Start generiert der Hub automatisch ein Access-Token in serial_bridge.token neben der Konfigurationsdatei für die Port-Bindung (überschreiben Sie den Pfad mit SERIAL_BRIDGE_TOKEN_FILE). Committen Sie die Secrets-Datei nicht.

Öffnen Sie Setup (http://127.0.0.1:8765/setup) auf dem Hub-Host, um die Hub-URL zu kopieren, das Access-Token anzuzeigen, es zu rotieren und einen Cursor-mcpServers-Ausschnitt einzufügen. Setup-Geheimnisse (Token-Klartext, Rotate und der geheimnistragende Ausschnitt) sind nur auf Loopback (127.0.0.1 / ::1) sichtbar.

Alternativ setzen Sie SERIAL_BRIDGE_TOKEN vor dem Start des Hubs und geben dasselbe Geheimnis an den MCP-Client. Die Umgebungsvariable überschreibt die Secrets-Datei für die Lebensdauer dieses Prozesses; Rotate schreibt die Datei weiterhin neu, warnt jedoch, bis die Umgebungsvariable entfernt oder der Hub ohne sie neu gestartet wird.

MCP-Authentifizierung ist auch von Loopback aus erforderlich. Legen Sie das Token nicht in die Versionskontrolle, in statische Frontend-Dateien, URLs oder Logs.

Der Hub lauscht auf 0.0.0.0:8765 und ist daher aus dem lokalen Netzwerk erreichbar. Verwenden Sie eine geeignete Host-Firewall und ein starkes Token. Remote-Agents können keine Modi oder Port-Bindungen ändern.

MCP

Verwenden Sie Setup (/setup) auf dem Hub-Host für eine Copy-Paste-Cursor-Konfiguration. Manuelle Verdrahtung:

Konfigurieren Sie die Streamable-HTTP-MCP-Verbindung des Agents mit:

URL: http://<hub-host>:8765/mcp
Authorization: Bearer <SERIAL_BRIDGE_TOKEN>

Verwenden Sie genau /mcp; die Web-UI befindet sich unter /. Der MCP-Server stellt bereit:

• serial_status: liest den aktuellen Modus sowie die Port-Bindung, den Öffnungsstatus und den Auslastungshinweis jedes Targets.

• serial_exec: sendet einen Textbefehl und erfasst die Ausgabe bis zu einer Leerlaufpause, einer optionalen Prompt-Übereinstimmung oder dem 60-Sekunden-Timeout.

• serial_send: sendet eine Textzeile oder eine Raw-Payload, ohne auf Ausgabe zu warten.

Um Status und Exec zu testen:

1. Öffnen Sie die Web-UI lokal und wechseln Sie in den Bridge-Modus.

2. Verbinden Sie den MCP-Client mit der obigen URL mit dem Bearer-Header.

3. Rufen Sie serial_status ohne Argumente auf und bestätigen Sie, dass mode bridge ist und das gewünschte Target geöffnet ist.

4. Rufen Sie serial_exec mit {"target":"linux","cmd":"uname -a"} oder {"target":"rtos","cmd":"help"} auf.

5. Wenn das Gerät einen stabilen Prompt hat, übergeben Sie optional prompt; setzen Sie prompt_is_regex nur dann auf true, wenn der Prompt-Wert ein regulärer Ausdruck ist.

Exec akzeptiert die Target-Namen linux und rtos, nicht die Namen serieller Geräte. Es gibt die erfasste output sowie die Flags timed_out, truncated und aborted zurück.

Die Exec-Ausgabe und die Transkripte live/*.log sind Klartext ohne ANSI-Escape-Sequenzen. Die Web-UI interpretiert die Escape-Sequenzen stattdessen und zeigt Gerätefarben.

Port-Bindung

Eine Port-Bindung weist einem Target einen seriellen Gerätepfad und eine Baudrate zu. Die integrierten Standardwerte sind Windows-Stil (linux auf COM3, rtos auf COM6, beide 115200); unter Linux oder macOS setzen Sie stattdessen Pfade wie /dev/ttyUSB0.

Überschreiben Sie die Standardwerte vor dem Start mit Umgebungsvariablen:

$env:SERIAL_BRIDGE_LINUX_PORT = "COM8"
$env:SERIAL_BRIDGE_LINUX_BAUD = "57600"
$env:SERIAL_BRIDGE_RTOS_PORT = "COM9"
$env:SERIAL_BRIDGE_RTOS_BAUD = "115200"
python -m serial_bridge

Entsprechende CLI-Flags sind --linux-port, --linux-baud, --rtos-port und --rtos-baud. SERIAL_BRIDGE_CONFIG oder --config wählt die persistierte JSON-Datei. Die Ladereihenfolge ist: integrierte Standardwerte, dann Umgebungs-/CLI-Werte, dann die persistierte Datei; gespeicherte Web-UI-Werte gewinnen.

Nur der Operator kann Port-Bindungen bearbeiten, und nur im CRT-Modus, während der Hub die Ports freigegeben hat. Die Web-UI listet die erkannten seriellen Ports in einem Dropdown pro Target auf; verwenden Sie Scan, um nach dem Anschließen eines Adapters neu aufzulisten. In der Web-UI vorgenommene Änderungen bleiben über einen Neustart hinweg erhalten.

Live-Verzeichnis

Das Live-Verzeichnis ist der Ort, an dem der Hub pro Target Bridge-Sitzungsprotokolle und bridge_status.json schreibt. Der Standardwert ist <app-dir>/live/ neben dem Projektstamm (dasselbe Verzeichnis wie serial_bridge.json und der Wrapper app.py im Stammverzeichnis).

Überschreiben Sie vor dem Start mit:

$env:SERIAL_BRIDGE_LIVE_DIR = "D:\logs\serial-bridge"
python -m serial_bridge

Oder übergeben Sie --live-dir. Die Ladereihenfolge entspricht der Port-Bindung: integrierter Standardwert, dann Umgebung/CLI, dann die persistierte Konfigurationsdatei; Web-UI-Speicherungen gewinnen.

Jedes Mal, wenn der Operator in den Bridge-Modus wechselt, erstellt der Hub neue Protokolldateien mit dem Namen <TargetName>-YYYY-MM-DD-HHMMSS.log (lokale Zeit, 24-Stunden-Uhr). Eine zweite Bridge-Sitzung erstellt neue Dateien; ältere Protokolle bleiben an ihrem Platz und werden nicht migriert, wenn Sie das Live-Verzeichnis ändern oder ein Target umbenennen.

Bearbeiten Sie das Live-Verzeichnis im Bindings-Panel der Web-UI nur im CRT-Modus (derselbe Nur-Loopback-Schreibpfad wie bei der Port-Bindung). Die Fußzeile zeigt das konfigurierte Verzeichnis und die aktuellen Sitzungsprotokolldateinamen, wenn zugewiesen.

Bridge-Modus und CRT-Modus

• Bridge-Modus: Der Hub besitzt die konfigurierten seriellen Ports. Der Operator und die Agents können Befehle senden und dieselben Live-Transkripte beobachten.

• CRT-Modus: Der Hub gibt die Ports für SecureCRT oder einen anderen exklusiven seriellen Client frei. MCP-Exec und -Send schlagen fehl, bis der Operator in den Bridge-Modus zurückkehrt.

Trennen Sie SecureCRT, bevor Sie in den Bridge-Modus wechseln. Der Wechsel in den CRT-Modus bricht eine laufende Exec ab und kann eine Teilausgabe zurückgeben.

Warnung zum Raw-Senden

serial_send mit raw_hex schreibt beliebige Bytes ohne Textzeilen-Rahmung oder automatisches Zeilenende. Das ist volle Konsolenleistung: Steuerbytes können den Bootvorgang unterbrechen, Prozesse beenden, den Gerätezustand verändern oder eine Sitzung nicht mehr reagieren lassen. Bevorzugen Sie serial_exec für Befehle und verwenden Sie Raw-Payloads nur, wenn die genaue Byte-Sequenz und die Auswirkung auf das Gerät verstanden sind.