docs

2026-06-24 12:00:49 +02:00
parent 68c418400e
commit 5d6bd16d8d
3 changed files with 74 additions and 22 deletions
@@ -0,0 +1,60 @@
+# mcp-docker-bash
+
+HTTP-MCP-Server mit persistenten PTY-Sessions und Hintergrund-Jobs. Agenten können interaktive Programme (`htop`, `vim`, …) steuern und deren Bildschirminhalt lesen.
+
+## Starten
+
+```bash
+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:
+
+```json
+{
+  "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`