HTTP-MCP-Server mit persistenten PTY-Sessions und Hintergrund-Jobs. Agenten können interaktive Programme (htop, vim, …) steuern und deren Bildschirminhalt lesen.

Starten

docker compose up
# Erster Start: apt + pip (ca. 60 s), danach dank pip-cache schnell
# Server läuft auf http://localhost:8000

Claude Code / Desktop einbinden

mcp-config.json in die Claude-Einstellungen kopieren oder manuell eintragen:

{
  "mcpServers": {
    "bash": { "type": "http", "url": "http://localhost:8000/mcp" }
  }
}

Tools

Tool	Beschreibung
`exec`	Einmaliger Shell-Befehl, synchron (Timeout konfigurierbar)
`pty_create`	Neues persistentes Terminal öffnen → `session_id`
`pty_send`	Text/Tasten senden (`\n` = Enter, `\x03` = Ctrl-C, `\x04` = Ctrl-D)
`pty_read`	Aktuellen Bildschirminhalt als Zeilen-Array lesen
`pty_kill`	Session beenden
`pty_list`	Alle offenen Sessions
`job_run`	Hintergrund-Job starten → `job_id` (kehrt sofort zurück)
`job_output`	Output-Zeilen lesen, inkrementell per `offset`
`job_status`	Status (`running`/`done`/`failed`), Exit-Code, Zeilenzahl
`job_kill`	Job per SIGTERM beenden
`job_list`	Alle bekannten Jobs

Typischer PTY-Flow

pty_create → session_id
pty_send   { session_id, text: "htop\n" }
pty_read   { session_id, wait_ms: 500 }   ← gerendertes Grid, kein ANSI-Müll
pty_send   { session_id, text: "\x03" }   ← Ctrl-C
pty_kill   { session_id }

Workspace

./workspace wird als /workspace in den Container gemountet — Dateien dort sind direkt in jeder PTY-Session sichtbar.

Erweiterungspunkte

Auth: API-Key-Header in main.py → FastAPI Depends
Session-Cleanup: TTL-Hintergrundtask der tote PTY-Sessions aufräumt
Streaming: SSE-Endpoint für Live-Output ohne Polling
Ressourcenlimits: ulimit im Dockerfile oder mem_limit in docker-compose.yml