tfbash-mcp

Eine grundlegende MCP-Toolsammlung für Agent-Systeme. Das Projekt möchte verschiedenen Agents eine Reihe stabiler, komponierbarer und kognitiv leichter allgemeiner Fähigkeiten bieten, z. B. Befehlsausführung, Datei-Lesen/-Schreiben und Suche; für konkrete Fähigkeiten werden bevorzugt ausgereifte Implementierungen wiederverwendet, und nur wenn bestehende Lösungen die Kernanforderungen nicht erfüllen, werden Anpassung oder Eigenentwicklung in Betracht gezogen.

Aktueller Status: Python-Projektskelett und Anforderungs-/Architektur-RFC. Das Repository kann einen leeren stdio-MCP-Server starten, bietet aber noch keine der im RFC definierten Shell-Tools.

Warum dieses Projekt?

Agents müssen häufig über reine Textlogik hinausgehen, echte Arbeitsbereiche manipulieren oder lokale Programme aufrufen. Programmierer nutzen die Shell als primäre Arbeitsoberfläche; auch allgemeine Rollen wie Produkt, Betrieb und Forschung rufen über die Shell Skripte auf, konvertieren Dateien, verarbeiten Daten in Stapeln oder diagnostizieren Umgebungen.

Bestehende MCP-Tools unterscheiden sich stark in Fähigkeitsumfang und Ausführungsmodell: Manche unterstützen nur Einmal-Befehle, manche hängen von PTY oder residenten Daemons ab, manche haben integrierte Genehmigungen und Sandboxen, manchen fehlen zuverlässige lange Befehle, inkrementelle Ausgaben und verwaltete Prozessbereinigung. tfbash-mcp definiert zuerst reale Szenarien und überprüfbare Fähigkeitsverträge und entscheidet dann, ob direkt übernommen, angepasst oder selbst entwickelt wird.

Related MCP server: MCP Terminal Tool Server

Designprinzipien

• Erst Szenario, dann Auswahl: Anforderungen werden nicht rückwärts aus der Vertrautheit mit einer Sprache, einem Framework oder einem bestehenden Projekt abgeleitet.

• Wiederverwendung bevorzugen: Die Auswahlreihenfolge ist Adopt → Wrap → Build; Wiederverwendung setzt voraus, dass das Kernverhalten erfüllt wird.

• Klein und orthogonal: Basistools behalten klare Grenzen; Agent-Orchestrierung, Geschäftsworkflows oder UI werden nicht in die Tool-Schicht gepackt.

• Expliziter Zustand: Lange Aufgaben, persistente Shells, Ausgabecursor, Exit-Status und Ressourcenlebenszyklen müssen beobachtbar sein; Shells, die cwd/env beibehalten müssen, werden explizit erstellt und adressiert.

• Protokoll und Implementierungssprache unabhängig: Der Tool-Vertrag legt keine internen Konzepte von Python, pexpect, Computer oder Client offen; V1 verwendet Python + pexpect und stdio-Transport.

• Vertrauen in die Bereitstellungsumgebung: In der ersten Phase gibt es keine integrierte Genehmigung, Sandbox, Befehlsrichtlinie oder Verzeichnisgrenzen.

• Kontrollierbare Ressourcen: Speicher, Festplatte, Sitzungen, Prozesse und temporäre Dateien müssen klare Obergrenzen, Eigentümerschaft und Bereinigungsregeln haben.

Erste Phase: Bash-Tools

Die erste Phase konzentriert sich auf einen eigenständigen, allgemeinen Bash-MCP-Server in Unix-Umgebungen (Linux, macOS). Die Ziele umfassen gleichzeitig:

• Build, Tests, Codesuche, Dienststart und Logbeobachtung für Programmierer;

• Dateiverarbeitung, Datenkonvertierung und Umgebungsdiagnose für allgemeine Rollen über installierte CLIs oder Skripte;

• Mehrere adressierbare persistente Command Shells, die jeweils cwd, Umgebung und Aktivierungsstatus beibehalten und für jeden Befehl einen genauen Exit-Status zurückgeben;

• stdout/stderr des pexpect-PTY wird als kombinierte Ausgabe zurückgegeben, und für jede Ausführung wird eine begrenzte inkrementelle Ausgabe gepflegt;

• Kurze Befehle werden von shell_exec in einem Schritt zurückgegeben; lange Befehle geben nach Überschreiten von yield_ms running zurück und werden in derselben Shell weiter ausgeführt;

• Lange Befehle lesen Ausgaben inkrementell über shell_read, schreiben über shell_write in stdin und werden über shell_signal unterbrochen oder beendet;

• Persistente Command Shells unterstützen Erstellung, Ausführung, inkrementelles Lesen, Schreiben, Signale, Auflistung und Schließen; separate Hintergrund-Job- und Terminal-Toolgruppen werden nicht mehr bereitgestellt;

• Shells und Executions gehören zum MCP-Serviceprozess und bleiben über Tool-Aufrufe hinweg erhalten, aber eine Wiederherstellung über Service-Neustarts hinweg wird nicht zugesagt;

• Ein tfrobot-client Computer entspricht einem vom SDK verwalteten MCP-Prozess; der Client behält nur den Aktivierungsschalter und den Laufzeitstatus.

Die persistente Shell der ersten Phase verwendet PTY, bietet aber nur eine befehlsorientierte Textausgabe, kein Vollbild-TUI-Bildschirmmodell, keine rohe Terminal-Sitzung und kein resize. Sollten später klare Integrationspartner für xterm.js, REPL oder Vollbild-TUI auftauchen, wird im selben Shell-Ressourcenmodell ein Terminal-Modus hinzugefügt. Ebenfalls nicht enthalten sind Befehlsgenehmigung, Prozess-Sandbox, Wiederherstellung über Service-Neustarts und eine starke Bindung an MCP Tasks.

Verwandte Dokumentation:

• Anforderungen und Architektur des allgemeinen Bash-MCP-Servers: definiert die unabhängige MCP-Grenze, den Tool-Vertrag, den ide4ai-Wiederverwendungsumfang, die SDK-/Client-Verantwortlichkeiten und die Abnahmekriterien.

Geplante Basisfähigkeiten

Die aktuelle Roadmap drückt nur die Erkundungsreihenfolge aus, nicht eine Entscheidung für Eigenentwicklung:

1. Persistente Shell und Ausführung langer Befehle;

2. Datei-Lesen, -Schreiben und patchartige Änderungen;

3. Dateierkennung und Textsuche;

4. Weitere kleine Basistools, die auf Basis realer Agent-Workflows ergänzt werden.

Jede Fähigkeit sollte zuerst eigenständige Anforderungen und Kandidatenrecherchen bilden und die Entscheidungsgrundlage für Adopt, Wrap oder Build dokumentieren. Verschiedene Fähigkeiten können aus verschiedenen Quellen stammen, solange das Fehlermodell, der Lebenszyklus und die Ergebnisstruktur, die dem Agent ausgesetzt werden, konsistent bleiben.

Repository-Struktur

.
├── .github/workflows/tests.yml  # Python 3.10–3.12 CI
├── pyproject.toml               # 包元数据、依赖与工具配置
├── src/tfbash_mcp/              # MCP Server 包与入口
├── tests/                       # 自动化测试
├── README.md
├── docs/
│   └── bash-tool-requirements.md
└── reference/
    ├── ide4ai/                   # pexpect 持久 Shell 基线
    ├── codex/                    # 进程生命周期参考
    ├── pi/                       # Agent Shell 参考
    └── deepseek-harness/         # Agent Runtime 参考

reference/ ist ein lokales Recherche-Checkout-Verzeichnis, das relativ groß ist und mehrere Git-Repositories von Drittanbietern enthält; es wird daher nicht in die Versionskontrolle oder das Verteilpaket von tfbash-mcp aufgenommen.

Lokale Entwicklung

Das Projekt unterstützt Python 3.10–3.12 und verwendet uv zur Umgebungsverwaltung:

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest --cov

Starten des aktuellen stdio-Server-Skeletts:

uv run tfbash-mcp

Dieser Prozess registriert derzeit keine Shell-Tools; er dient nur zur Verifizierung des Pakets, des Einstiegspunkts und des MCP-stdio-Lebenszyklus.

Entscheidungsbeteiligung

Das Anforderungsdokument hat bereits das V1-Modell mit mehreren Shells + Execution-Tools und die Python/pexpect-Implementierungsbasis festgelegt, ist aber noch ein zu implementierender, zu akzeptierender RFC. Vor Beginn der Entwicklung sind mindestens folgende Punkte erforderlich:

1. Abgleich der harten Schwellenwerte und offenen Punkte im Dokument;

2. Durchführung eines minimalen Machbarkeitsexperiments mit der gewählten pexpect-Basis;

3. Bestätigung der Lizenzbeibehaltung, Anpassungskosten, langfristigen Wartungsfläche und Ausstiegsstrategie für die ide4ai-Codeextraktion;

4. Rückschreiben der Experimentergebnisse und endgültigen Implementierungsabweichungen in den RFC, bevor Codierung und Abnahme beginnen.