sully-termux-mcp

sully-termux-mcp ist ein Node.js 20+ TypeScript-ESM-Gateway zum Ausführen von MCP-Tools in Termux. Die Produktionsvorgabe ist bewusst klein: Es lauscht nur auf einer Loopback-Adresse, erfordert ein 32-Byte-Bearer-Token und stellt eine separate authentifizierte Admin-API bereit.

Schnellstart

npm ci
npm run build
node dist/cli.js setup
node dist/cli.js start
node dist/cli.js status
node dist/cli.js pair                 # explicit user action; prints both tokens

Die generierte Konfiguration ist ~/.config/sully-mcp/config.json mit Modus 0600; Daten, Job-Ausgaben und das geschwärzte Audit-Log befinden sich unter ~/.local/share/sully-mcp mit Modus 0700. Fügen Sie Pairing-JSON niemals in ein Log oder einen Issue ein.

Für Telefonsteuerungen installieren Sie das Termux:API-Befehls Paket (pkg install termux-api) und installieren Sie die Termux:API-Begleit-App für Android aus derselben Signaturquelle (z. B. beide von F-Droid oder beide von GitHub). Android liefert keine API-Aufrufe, wenn die beiden Pakete aus unterschiedlichen Signaturquellen stammen. Starten Sie das Gateway nach der Installation oder Aktualisierung von Termux:API neu, damit sein Befehlsinventar neu aufgebaut wird.

Der MCP-Endpunkt ist http://127.0.0.1:8765/mcp. Diese Version unterstützt die stabilen sitzungsbasierten Protokolle 2025-11-25 und 2025-06-18 mit initialize, notifications/initialized, tools/list und tools/call. Der Transport 2026-07-28 wird absichtlich nicht beworben, bis seine erforderlichen Routing-Header und das Antwort-Envelope implementiert sind. DELETE /mcp schließt eine 2025-Sitzung.

Related MCP server: Python MCP Toolkit Server

Verwaltung

POST /admin/v1 verwendet das Admin-Bearer-Token und akzeptiert { "action": "status", "params": {} }. Zu den Aktionen gehören status, doctor, permissions, capabilities, jobs.list, jobs.output, jobs.cancel, jobs.cleanup, profiles.list, profiles.upsert, profiles.remove, upstreams.list, upstreams.import, upstreams.update, upstreams.remove, gateway.stop, tokens.rotate und pair.revoke. Alle Antworten haben {ok:true,result} oder {ok:false,error}. Geheimnisse werden nur für eine explizite tokens.rotate-Antwort oder den expliziten pair-CLI-Befehl zurückgegeben.

permissions und doctor enthalten eine zentralisierte Termux:API-Checkliste, gruppiert nach Gerät, Kommunikation, Medien, Interaktion und Automatisierung. Die Verfügbarkeit von Befehlen wird beim Start erkannt; der Android-Laufzeitberechtigungsstatus wird als unknown gemeldet, und die Anforderung derselben Signaturquelle für Termux:API ist explizit.

Tools und Grenzen

Zu den integrierten Funktionen gehören begrenzte echo_safe, fs_read, fs_write, fs_list, fs_metadata, fs_find, fs_copy, fs_move, Befehlsprofile, Shell-Jobs, Job-Status/-Ausgabe/-Abbruch/-Bereinigung sowie erkannte Termux:API-Befehle (einschließlich typisierter Standort-, Kamera-, Benachrichtigungs-, Toast-, Zwischenablage-, SMS-, TTS-, Lautstärke- und Taschenlampen-Eingaben). Weniger gebräuchliche API-Befehle legen begrenzte rohe args mit einem Verwendungs-/Hilfehinweis offen; konsultieren Sie die --help-Option des installierten Befehls für genaue Optionen. shell_exec startet immer bash -lc mit shell:false; Befehlsprofile und Stdio-Upstreams verwenden eine ausführbare Datei plus Argumentarray mit shell:false. Jobs überleben Neustarts als interrupted, erfassen höchstens 8 MiB und geben höchstens 64 KiB pro Ausgabeanforderung zurück. Anforderungen sind auf 1 MiB und Antworten auf 4 MiB begrenzt; die Tool-Parallelität beträgt standardmäßig vier.

HTTP-Upstreams müssen HTTPS verwenden oder HTTP auf dem exakten literalen Loopback-Host 127.0.0.1/::1 (keine DNS-Aliase oder Leerzeichen). HTTPS-Ziele, die auf private, link-lokale oder Metadatenbereiche aufgelöst werden, werden abgelehnt. Weiterleitungen, URL-Anmeldeinformationen, Fragmente und nicht in der Whitelist enthaltene Tools werden abgelehnt. HTTP- und Stdio-Upstream-Tools werden mit Präfix versehen (id__tool) und können mit allowedTools, readOnly und prefix eingeschränkt werden.

Termux-Lebenszyklus

Der normale sully-mcp start/restart-Lebenszyklus erwirbt termux-wake-lock, wenn verfügbar, und stop gibt es wieder frei. Installieren Sie termux-boot/sully-termux-mcp als ~/.termux/boot/sully-termux-mcp und machen Sie es ausführbar, um nach einem Neustart zu starten. Die Android-Akkuoptimierung kann Termux trotzdem stoppen; die Anwendung sollte ein nicht verfügbares Gateway als wiederherstellbar behandeln.

Unterstützte CLI-Befehle: setup, start, stop, restart, status, logs, doctor, permissions, pair, update und uninstall --yes.

Release-Integrität

npm run release -- --version 0.2.0 erfordert MCP_RELEASE_ED25519_PRIVATE_KEY und führt einen Build aus, bevor sully-termux-mcp-0.2.0.tar.gz, seine SHA-256, das Manifest und die Ed25519-Signatur geschrieben werden. Der App-Befehl in scripts/install-command.txt lädt das feste GitHub-Release-Archiv, den Hash, das Manifest und die Signatur in ein temporäres Verzeichnis herunter, vergleicht das Archiv mit seinem festgelegten erwarteten Hash, verifiziert die Ed25519-Signatur mit seinem Inline-öffentlichen Schlüssel und führt erst dann das verifizierte scripts/install-local.sh des Archivs aus. Das lokale Installationsprogramm prüft Node 20+, führt npm ci --omit=dev und den Build aus und tauscht einen atomaren versions/<version>/current-Symlink aus, wobei das vorherige aktuelle Ziel bei einem Fehler erhalten bleibt. Es erstellt auch einen echten sully-mcp-Wrapper in Termux's $PREFIX/bin (oder ~/.local/bin) und verwendet niemals eine unverifizierte curl | sh-Pipeline. Der private Signaturschlüssel wird transient über MCP_RELEASE_ED25519_PRIVATE_KEY vom Release-Operator bereitgestellt und niemals committet.

Sicherheitsmodell

Für den lokalen Listener werden nur Loopback-Hosts akzeptiert. MCP- und Admin-Anmeldeinformationen sind unabhängige 64-Hex-Zufallswerte und werden mit einem Vergleich in konstanter Zeit verglichen. Die Konfiguration wird als UTF-8 mit restriktiven Berechtigungen geschrieben. Der Server gibt keine Token von /health, Tool-Listen, normalen Fehlern, Audit-Datensätzen oder Job-Metadaten zurück. Audit-Einträge werden geschwärzt und begrenzt. Tools mit Nebenwirkungen werden niemals automatisch erneut versucht. Destruktive Upstream-Tools müssen vom Aufrufer explizit in die Whitelist aufgenommen werden.

Dieses Repository ist unter der PolyForm Noncommercial License 1.0.0 lizenziert, die von SULLYTEST2 übernommen wurde.