director-shell-mcp

director-shell-mcp ist ein kleiner MCP-Server für Agenten im Director-Modus. Er nutzt den MCP-stdio-Transport, um eine kontrollierte Ausweichmöglichkeit zum Schreiben von Dateien, zum Ausführen von Python-Code zur Datenerkundung, zum Ausführen von Shell-Befehlen und zur Überwachung von im Hintergrund laufenden Jobs bereitzustellen. Befehle werden nur gestartet, wenn ein Agent explizit ein Tool aufruft; der Server führt selbst keine Shell aus.

Installation

Node.js 18 oder neuer ist erforderlich. Aus diesem Verzeichnis:

npm install

Führen Sie den Server direkt aus mit:

node C:/path/to/director-shell-mcp/index.js

Related MCP server: shell-0

OMP-Registrierung (primär)

Der primäre Client ist die Oh My Pi (OMP)-Umgebung. Fügen Sie diese exakte Konfiguration zur benutzerbezogenen ~/.omp/agent/mcp.json (oder zur projektspezifischen .omp/mcp.json) hinzu:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

Für stdio-Server kann type weggelassen werden. Nach dem Bearbeiten der Konfiguration führen Sie in OMP /mcp reload und dann /mcp test director-shell aus.

Registrierung generischer MCP-Clients

Andere MCP-Clients akzeptieren in der Regel eine äquivalente stdio-Registrierung:

{
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

Tool-Referenz

Alle Tools geben ein JSON-Objekt im MCP-Textinhalt zurück. Fehler werden als MCP-Toolfehler mit einem error-Feld in Satzform zurückgegeben.

shell_run

Führt einen Befehl bis zum Abschluss aus. Parameter:

• command (string, erforderlich): Befehlstext.

• cwd (string, optional): Arbeitsverzeichnis.

• timeout_ms (integer, optional): Standard 60.000; Maximum 600.000.

• shell (powershell, cmd oder bash, optional): Standard ist PowerShell unter Windows und Bash auf anderen Systemen.

Das Ergebnis enthält exit_code, duration_ms und stdout/stderr-Objekte. Jeder Stream enthält bis zu etwa 50 KiB Vorschautext. Wenn ein Stream diese Grenze überschreitet, enthält sein Objekt zusätzlich truncated: true und full_output_path, der auf eine temporäre Datei mit dem vollständigen Stream verweist. Ein Timeout gibt einen MCP-Toolfehler mit einer klaren Meldung und dem Teilergebnis zurück.

write_file

Schreibt UTF-8-Text in einen absoluten Dateipfad. Parameter:

• path (string, erforderlich): absoluter Dateipfad.

• content (string, erforderlich): zu schreibender Text.

• append (boolean, optional): anhängen statt ersetzen; Standard false.

• create_dirs (boolean, optional): fehlende übergeordnete Verzeichnisse erstellen; Standard true.

Das Ergebnis enthält path, bytes_written, created (ob die Datei vor dem Aufruf nicht existierte) und appended.

edit_file

Ersetzt Text in einer UTF-8-Datei an einem absoluten Pfad. Parameter:

• path (string, erforderlich): absoluter Dateipfad.

• old_text (string, erforderlich): nicht-leerer Text, der gefunden werden soll.

• new_text (string, erforderlich): Ersatztext.

• replace_all (boolean, optional): jedes Vorkommen ersetzen; Standard false.

Ohne replace_all muss old_text genau einmal vorkommen. Null oder mehrere Übereinstimmungen geben einen MCP-Toolfehler zurück und lassen die Datei unverändert. Das Ergebnis enthält path und replacements.

run_python

Führt Python-Quellcode bis zum Abschluss aus, mit begrenzter Ausgabe und einem Timeout. Unter Windows prüft der Server zuerst den py-Launcher und dann python; auf anderen Systemen prüft er zuerst python3 und dann python und speichert das erste verwendbare ausführbare Programm. Parameter:

• code (string, erforderlich): Python-Quellcode.

• cwd (string, optional): Arbeitsverzeichnis für den Python-Prozess.

• timeout_ms (integer, optional): Standard 60.000; Maximum 600.000.

• args (Array von Strings, optional): Werte, die als sys.argv[1:] übergeben werden.

Das Ergebnis enthält exit_code, duration_ms, stdout/stderr-Objekte und python_executable. Ausgabeströme sind begrenzt und werden wie bei shell_run in temporäre Dateien ausgelagert. Ein Timeout gibt einen MCP-Toolfehler mit einer klaren Meldung und dem Teilergebnis zurück.

job_start

Startet einen abgekoppelten Befehl, der nach der Rückkehr des Tool-Aufrufs weiterläuft. Parameter:

• command (string, erforderlich)

• cwd (string, optional)

• shell (powershell, cmd oder bash, optional)

• name (string, optional, menschenlesbare Bezeichnung)

Das Ergebnis enthält job_id, pid, log_paths (stdout, stderr und combined) und den exit_marker-Pfad. Metadaten werden als JSON unter %LOCALAPPDATA%/director-shell-mcp/jobs/<jobId>/ gespeichert, sodass Jobs nach einem Server-Neustart weiterhin auffindbar sind.

job_status

Liest den gespeicherten Zustand eines Jobs. Parameter:

• job_id (string, erforderlich): eine von job_start zurückgegebene ID.

• tail_lines (integer, optional): Standard 40; Maximum 1.000.

Das Ergebnis enthält running, exit_code (falls verfügbar), runtime_ms, started_at und output_tail aus dem kombinierten Log. Der abgekoppelte Wrapper schreibt exit_code.txt, wenn der Befehl endet, und bewahrt den Exit-Code über Server-Neustarts hinweg.

job_kill

Beendet einen von diesem Server gestarteten Job. Er akzeptiert job_id. Unter Windows wird taskkill /T /F verwendet, um den Prozessbaum des Wrappers zu beenden. Bereits abgeschlossene Jobs bleiben unverändert.

job_list

Listet alle gültigen gespeicherten Jobs mit ihrer job_id, optionalen name, pid, running-Status, Exit-Code und Startzeit auf.

grep_files

Durchsucht eine absolute Datei oder ein Verzeichnis rekursiv mit einem JavaScript-Regulärausdruck, ohne ripgrep zu benötigen. Die Suche überspringt node_modules, .git, bin, obj, dist und target, ignoriert Dateien größer als 5 MiB und Binärdateien und stoppt beim Ergebnislimit. Parameter:

• pattern (string, erforderlich): JavaScript-Regulärausdruck-Quelltext.

• path (string, erforderlich): absoluter Datei- oder Verzeichnispfad.

• glob (string, optional): einfacher Dateinamenfilter mit * und ?.

• case_sensitive (boolean, optional): Standard false.

• max_results (integer, optional): Standard 200; Maximum 1.000.

• context_lines (integer, optional): Zeilen vor und nach jeder Übereinstimmung; Standard 0; Maximum 5.

Das Ergebnis enthält matches mit file, line_number, line, before und after, sowie files_scanned und truncated. Ungültige reguläre Ausdrücke geben einen MCP-Toolfehler zurück.

job_wait

Wartet auf das Ende eines vorhandenen abgekoppelten Jobs und pollt alle 500 ms dessen gespeicherten Exit-Marker. Parameter:

• job_id (string, erforderlich): von job_start zurückgegebene ID.

• timeout_ms (integer, optional): Standard 60.000; Maximum 600.000.

• tail_lines (integer, optional): Standard 40; Maximum 1.000.

Das Ergebnis hat dieselben Felder wie job_status und fügt timed_out hinzu. Ein Ablauf der Frist, während der Job noch läuft, ist ein normales Ergebnis mit timed_out: true, kein MCP-Fehler.

lock_acquire und lock_release

Bieten einen benannten, agentenübergreifenden Mutex, der unter %LOCALAPPDATA%/director-shell-mcp/locks/ gespeichert wird. Namen enthalten nur Buchstaben, Ziffern, _, . und - und sind höchstens 64 Zeichen lang. lock_acquire akzeptiert name (erforderlich), wait_ms (optional, Standard 0, Maximum 600.000) und eine optionale note; es gibt name, ein UUID-token und acquired_at zurück. Die Erfassung verwendet ein atomares Verzeichnis-Erstellen und stellt Sperren wieder her, deren aufgezeichneter Besitzerprozess nicht mehr lebt. Ein Fehler bei gehaltener Sperre identifiziert dessen pid, note falls vorhanden und Dauer. lock_release akzeptiert name und das Besitzer-token; falsche Tokens und freie Sperren sind Fehler und ändern die Sperre nicht.

screenshot

Erfasst den gesamten virtuellen Bildschirm oder ein sichtbares oberstes Fenster als PNG unter Windows mit System.Drawing und den Windows-APIs. Parameter:

• target (screen oder window, optional): Standard screen.

• window_title (string, erforderlich für window): case-insensitive Teilstring des sichtbaren Fenstertitels.

• output_path (absoluter .png, optional): Standard ist eine mit Zeitstempel versehene Datei im temporären Ausgabeverzeichnis.

Das Ergebnis enthält path, width, height, target und den übereinstimmenden window_title für Fensteraufnahmen. Es gibt einen klaren Nicht-unterstützt-Fehler auf Nicht-Windows-Systemen und einen klaren Keine-Übereinstimmung-Fehler, wenn ein angefragtes Fenster nicht gefunden werden kann.

process_list

Gibt eine schreibgeschützte Prozessliste unter Windows zurück. Parameter:

• name_filter (string, optional): case-insensitive Teilstring eines Prozessnamens oder ausführbaren Pfads.

• max_results (integer, optional): Standard 100; Maximum 1.000.

Jeder Prozess enthält pid und name und enthält path, started_at und working_set_bytes, falls verfügbar. Das Ergebnis enthält auch truncated.

file_lockers

Meldet Prozesse, die eine vorhandene Datei unter Windows über die Restart-Manager-API offen halten. Es akzeptiert path (erforderlich), das ein absoluter Pfad zu einer vorhandenen Datei sein muss, und gibt { path, lockers } zurück. Jeder Locker enthält pid, app_name und app_type; eine nicht gesperrte Datei ist ein erfolgreiches Ergebnis mit einem leeren lockers-Array. Nicht-Windows-Systeme geben einen klaren Nicht-unterstützt-Fehler zurück.

Verifikation

Führen Sie den leichten End-to-End-Smoke-Test aus (er verwendet nur echo und PowerShell-Sleep):

npm run smoke

Der Smoke-Test startet einen frischen MCP-Server über stdio, führt die Initialisierung durch, listet alle fünfzehn Tools auf, übt das Schreiben von Dateien, exaktes Textbearbeiten, Python-Ausführung und Argumentübergabe, Befehlsabschluss und Ausgabeerfassung, verifiziert abgekoppelte Jobs während sie laufen und nachdem sie beendet sind, übt grep, wait, Sperren, Screenshots, Prozessliste und Restart-Manager-Dateisperr-Erkennung, prüft die Persistenz über job_list und verifiziert die Behandlung von Befehls-Timeouts.

Lizenz

MIT