MCP – Befehlsfehler und Exitcodes¶
Status: produktiv seit 08.09.2026. Die frühere run()-Logik, die Prozessfehler als gewöhnlichen Text zurückgeben konnte, wurde durch strukturierte Prozessauswertung ersetzt.
Produktives Verhalten¶
| Fall | Verhalten |
|---|---|
| Exitcode 0 | normale Tool-Antwort mit strukturierten Prozessmetadaten |
| unerwarteter Exitcode ungleich 0 | echter MCP-Toolfehler mit beobachtetem Exitcode |
| Zeitlimit | eigener Fehlerstatus |
| Ausgabelimit | eigener Fehlerstatus |
| Signal / Startfehler | eigener Fehlerstatus |
| SSH-Fehler / Exitcode 255 | gesonderte, bewusst mehrdeutige Kategorie |
| fehlgeschlagenes Remote-Dateischreiben | keine nachträgliche Erfolgsmeldung |
| gesperrte Shell-Freigabe | echter Toolfehler |
Die Prozessdaten liegen strukturiert unter structuredContent.execution, unter anderem mit:
execution_status
exit_code
signal
timed_out
output_truncated
process_duration_ms
completion
commands_total
commands_failed
Audit¶
Das Audit übernimmt nur intern nachgewiesene Prozessmetadaten. Vollständige Befehle, stdout/stderr und freie Fehlertexte werden nicht in Audit-v2 übernommen.
Typische feste Kategorien:
COMMAND_EXIT_NONZERO
COMMAND_TIMEOUT
COMMAND_OUTPUT_LIMIT
COMMAND_SIGNALED
COMMAND_LAUNCH_FAILED
SSH_OR_REMOTE_EXIT_255
Die spätere Audit-Integrität hat zusätzlich den früher offenen direkten Schreibzugriff des MCP-Benutzers auf das Audit beseitigt. Der aktuelle Zustand verwendet root-eigene Tagesdateien und mcp-audit-writer.
Diagnose ist nicht dasselbe wie Erfolg¶
get_service_status darf bestimmte negative systemd-Zustände als verwertbaren Diagnosebefund zurückgeben. Ein inaktiver Dienst gilt dadurch nicht als gesund; lediglich die Statusabfrage konnte den Zustand erfolgreich ermitteln.
check_reachability kann einen fehlenden Ping-Reply als Diagnose melden. Das beweist weder, dass das Gerät ausgeschaltet ist, noch dass andere Protokolle nicht erreichbar sind.
Grenzen¶
Das Standard-Zeitlimit beträgt 60 Sekunden; stdout und stderr sind jeweils auf 1 MiB begrenzt.
Ein lokaler Exitcode 0 beweist nur den Erfolg des gestarteten Gesamtprozesses. Ein Shell-Wrapper oder eine Pipeline kann interne Fehler selbst verschlucken. Der MCP erfindet deshalb keine Teilbefehlsstatus.
SSH-Exitcode 255 bleibt ohne Zusatzinformation mehrdeutig: Er kann einen SSH-Verbindungsfehler oder einen entfernten Exitcode 255 darstellen.
Bei einem nicht eindeutig bestätigten Prozessende steht completion: unconfirmed. Vor einer Wiederholung muss der Zielzustand geprüft werden; automatische Wiederholungen sind nicht vorgesehen.
Installierte Dateien¶
/opt/mcp-shell/lib/command-runner.js
/opt/mcp-shell/lib/core.js
/opt/mcp-shell/lib/audit-safe.js
/opt/mcp-shell/tools/infrastructure.js
/opt/mcp-shell/tools/proxmox.js
/opt/mcp-shell/tools/system.js
/opt/mcp-shell/tools/files.js
/opt/mcp-shell/tools/mikrotik.js
Produktiver Nachweis¶
Nach dem Deployment wurde unter anderem ein harmloser shell_execute-Probeaufruf mit Exitcode 7 ausgeführt. Der Tool-Aufruf wurde korrekt als Fehler mit execution_status: nonzero_exit und exit_code: 7 zurückgegeben. Der zugehörige Audit-v2-Eintrag enthielt diese Prozessmetadaten, aber nicht den ausgeführten Befehl oder Roh-Ausgabe.
Historische Installationsunterlagen¶
/root/mcp-command-errors-20260908.tar.gz
/root/mcp-command-backup-20260908T071939Z.kQyiC2/rollback.sh
/root/mcp-command-errors-20260908.SxcmBc
/tmp/mcp-command-install-test.RywO2V
Für einen Neuaufbau ist die aktuelle MCP-Installationsseite maßgeblich.