SSH

Das SSH-Plug-in verbindet mcp-toolbox mit einem entfernten Server. Damit kannst du:

• Befehle ausführen – einen einzelnen Befehl auf dem Server starten und Ausgabe samt Exit-Code erhalten
• Interaktive Sitzungen – ein Terminal auf dem Server öffnen und steuern, auch für Programme, die Eingaben erwarten
• Dateien übertragen (SFTP) – Dateien lesen, schreiben, auflisten und löschen

Typische Einsatzfälle: Server warten, Logs auswerten, Konfigurationsdateien ändern, Updates einspielen, Backups sichern.

Einrichtung

Erstelle eine Instanz im Plug-in-Manager und trage die Verbindungsdaten ein:

Feld	Bedeutung
Host	Adresse oder IP des Servers (Pflicht)
User	SSH-Benutzer (Pflicht)
Port	SSH-Port, Standard 22
Password	Passwort für die Anmeldung
Private SSH key	Alternativ ein privater Schlüssel (mehrzeilig)
Key passphrase	Passphrase des Schlüssels, falls gesetzt

Die Einstellungen (Timeout, Standard-Shell, Sitzungs-Limits) haben sinnvolle Voreinstellungen und müssen für den Normalfall nicht angepasst werden.

Tools

Verbindung und Befehle

Tool	Funktion
ssh_ping	Prüft die Verbindung und meldet Server-Daten (Banner). Der schnelle Erreichbarkeits-Check.
ssh_exec	Führt einen Befehl aus und liefert Ausgabe (stdout/stderr) und Exit-Code. Für alles, was einmal läuft und abschließt.

Beispiel: ssh_exec mit df -h zeigt den Speicherplatz, mit uptime die Serverlast, mit systemctl restart nginx startet der Befehl den Dienst neu.

Interaktive Sitzungen

Tool	Funktion
ssh_session_start	Startet eine Terminal-Sitzung (PTY) und liefert eine Session-ID.
ssh_session_send	Tippt Text in die Sitzung – mit einem abschließenden \n wird die Eingabe abgeschickt.
ssh_session_read	Liefert die Ausgabe seit dem letzten Lesen; kann kurz auf neue Ausgabe warten (Long-Poll).
ssh_session_exec	Führt einen Befehl in der Sitzung aus und wartet auf dessen Ende (inkl. Exit-Code).
ssh_session_list	Zeigt alle offenen Sitzungen mit Alter und gepufferten Daten.
ssh_session_close	Beendet die Sitzung und liefert den Rest der Ausgabe.

Eine Sitzung ist wie ein offenes Terminal: du startest sie, tippst Eingaben und liest die Antwort. Sie eignet sich für Programme, die Eingaben erwarten (z. B. python3, Datenbank-Shells, Konfigurationsassistenten) oder länger laufen. Nicht genutzte Sitzungen werden nach einigen Minuten automatisch geschlossen (einstellbar); mehrere Sitzungen gleichzeitig sind möglich.

Dateien (SFTP)

Tool	Funktion
ssh_sftp_list	Listet den Inhalt eines Verzeichnisses.
ssh_sftp_read	Liest eine Datei – als Text oder als Base64 (für binäre Inhalte).
ssh_sftp_write	Schreibt eine Datei; fehlende Zwischenverzeichnisse werden angelegt.
ssh_sftp_mkdir	Legt ein Verzeichnis an (rekursiv).
ssh_sftp_delete	Löscht eine Datei oder ein Verzeichnis samt Inhalt.
ssh_sftp_stat	Zeigt Metadaten einer Datei (Größe, Rechte, Änderungszeit).

Typische Arbeitsabläufe

Server-Status prüfen

1. ssh_ping – ist der Server erreichbar?
2. ssh_exec mit uptime – wie lange läuft er, wie hoch ist die Last?
3. ssh_exec mit free -h und df -h – Speicher und Plattenplatz im Blick.

Problem diagnostizieren

1. ssh_exec mit journalctl -u <Dienst> --no-pager -n 50 – die letzten Log-Zeilen eines Dienstes.
2. ssh_sftp_read der betroffenen Konfigurationsdatei, z. B. /etc/nginx/nginx.conf.
3. Bei Bedarf: ssh_sftp_write mit der korrigierten Datei, danach ssh_exec mit systemctl restart <Dienst>.
4. ssh_exec mit systemctl status <Dienst> – prüfen, ob der Dienst jetzt läuft.

Interaktives Programm steuern

1. ssh_session_start – Terminal öffnen, z. B. mit python3 als Shell.
2. ssh_session_send – die gewünschten Eingaben eintippen; jede Zeile mit \n abschließen.
3. ssh_session_read – die Ausgabe Schritt für Schritt abholen und darauf reagieren.
4. ssh_session_close – die Sitzung am Ende schließen.

Dateien sichern oder verteilen

1. ssh_sftp_read – eine Log- oder Konfigurationsdatei lesen (bei Binärdaten encoding: base64).
2. ssh_sftp_mkdir + ssh_sftp_write – die Datei an anderer Stelle ablegen.
3. ssh_sftp_delete – eine veraltete Datei entfernen (Achtung: löscht endgültig, auch Verzeichnisse mit Inhalt).

Hinweise für KI-Agenten

• Sitzungen im Wechsel bedienen: ssh_session_send tippt, ssh_session_read holt die Antwort; ssh_session_exec führt einen Befehl aus und wartet, bis er fertig ist – das Ergebnis enthält den Exit-Code. Nicht zwei ssh_session_exec gleichzeitig auf derselben Sitzung laufen lassen.
• Exit-Codes zuverlässig bekommen: ssh_session_exec nutzt im Standard-Modus ein internes Abschlusszeichen und meldet den echten Exit-Code. Der quiet-Modus wartet nur auf eine ruhige Phase – für Programme, die ihr Ende nicht anzeigen, aber eine Pause machen.
• Session-ID verloren? ssh_session_list zeigt alle offenen Sitzungen der Instanz – so lassen sich Sitzungen nach einem Kontextverlust wiederfinden.
• Lange oder interaktive Aufgaben: ssh_exec hat ein Timeout und passt nur für kurze Befehle; für alles Langlaufende eine Sitzung verwenden.
• Aufgabe, bis sie abschließt: ssh_session_read mit until wartet, bis ein bestimmtes Zeichen oder Wort in der Ausgabe erscheint – z. B. ein Prompt oder eine Fehlermeldung.