# 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`