61 lines
1.9 KiB
Markdown
61 lines
1.9 KiB
Markdown
# 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`
|