sully-termux-mcp

sully-termux-mcp は、Termux で MCP ツールを実行するための Node.js 20+ TypeScript ESM ゲートウェイです。本番環境のデフォルトは意図的に小さく、ループバックアドレスのみで待ち受け、32バイトの Bearer トークンを要求し、別の認証付き管理 API を公開します。

クイックスタート

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

生成される設定は ~/.config/sully-mcp/config.json で、モードは 0600 です。データ、ジョブ出力、および編集された監査ログは ~/.local/share/sully-mcp にあり、モードは 0700 です。ペアリング JSON をログや issue に貼り付けないでください。

電話の制御には、Termux:API コマンドパッケージ（pkg install termux-api）をインストールし、同じ署名元から Termux:API コンパニオン Android アプリをインストールしてください（たとえば、両方とも F-Droid から、または両方とも GitHub から）。2つのパッケージが異なる署名元から来た場合、Android は API 呼び出しを配信しません。Termux:API をインストールまたは更新した後、ゲートウェイを再起動して、コマンドインベントリを再構築してください。

MCP エンドポイントは http://127.0.0.1:8765/mcp です。このリリースは、initialize、notifications/initialized、tools/list、tools/call を使用する安定した 2025-11-25 および 2025-06-18 セッションベースのプロトコルをサポートしています。2026-07-28 トランスポートは、必要なルーティングヘッダーとレスポンスエンベロープが実装されるまで意図的に宣伝されません。DELETE /mcp は 2025 セッションを閉じます。

Related MCP server: Python MCP Toolkit Server

管理

POST /admin/v1 は admin Bearer トークンを使用し、{ "action": "status", "params": {} } を受け入れます。アクションには、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、pair.revoke が含まれます。すべてのレスポンスは {ok:true,result} または {ok:false,error} です。シークレットは、明示的な tokens.rotate レスポンスまたは明示的な pair CLI コマンドでのみ返されます。

permissions と doctor には、デバイス、通信、メディア、操作、自動化でグループ化された一元化された Termux:API チェックリストが含まれています。コマンドの可用性は起動時に検出されます。Android のランタイム権限状態は unknown として報告され、Termux:API の同じ署名元要件は明示的です。

ツールと制限

組み込みには、制限付きの echo_safe、fs_read、fs_write、fs_list、fs_metadata、fs_find、fs_copy、fs_move、コマンドプロファイル、シェルジョブ、ジョブのステータス/出力/キャンセル/クリーンアップ、および検出された Termux:API コマンド（型付きの位置情報、カメラ、通知、トースト、クリップボード、SMS、TTS、音量、トーチ入力など）が含まれます。あまり一般的でない API コマンドは、使用法/ヘルプのヒント付きで制限付きの生の args を公開します。正確なオプションについては、インストールされているコマンドの --help を参照してください。shell_exec は常に shell:false で bash -lc を起動します。コマンドプロファイルと stdio アップストリームは、shell:false の実行可能ファイルと引数配列を使用します。ジョブは再起動後も interrupted として存続し、最大 8 MiB をキャプチャし、出力要求ごとに最大 64 KiB を返します。リクエストは 1 MiB、レスポンスは 4 MiB に制限され、ツールの同時実行数はデフォルトで 4 です。

HTTP アップストリームは HTTPS を使用するか、正確なリテラルのループバックホスト 127.0.0.1/::1 上の HTTP を使用する必要があります（DNS エイリアスや空白は不可）。プライベート、リンクローカル、またはメタデータ範囲に解決される HTTPS 宛先は拒否されます。リダイレクト、URL 資格情報、フラグメント、および許可リストにないツールは拒否されます。HTTP および stdio アップストリームツールにはプレフィックス（id__tool）が付けられ、allowedTools、readOnly、prefix で制限できます。

Termux ライフサイクル

通常の sully-mcp start/restart ライフサイクルは、利用可能な場合に termux-wake-lock を取得し、stop で解放します。termux-boot/sully-termux-mcp を ~/.termux/boot/sully-termux-mcp としてインストールし、実行可能にして再起動後に起動します。Android のバッテリー最適化によって Termux が停止される可能性があります。アプリケーションは、利用できないゲートウェイを回復可能として扱う必要があります。

サポートされている CLI コマンド: setup、start、stop、restart、status、logs、doctor、permissions、pair、update、uninstall --yes。

リリースの整合性

npm run release -- --version 0.2.0 は MCP_RELEASE_ED25519_PRIVATE_KEY を必要とし、sully-termux-mcp-0.2.0.tar.gz、その SHA-256、マニフェスト、および Ed25519 署名を書き込む前にビルドを実行します。scripts/install-command.txt の App コマンドは、固定された GitHub Release アーカイブ、ハッシュ、マニフェスト、署名を一時ディレクトリにダウンロードし、アーカイブを固定された期待ハッシュと比較し、インラインの公開鍵で Ed25519 署名を検証し、その後にのみ検証済みアーカイブの scripts/install-local.sh を実行します。ローカルインストーラーは Node 20+ をチェックし、npm ci --omit=dev とビルドを実行し、失敗時に以前の current ターゲットを保持しながら、アトミックな versions/<version>/current シンボリックリンクを交換します。また、Termux の $PREFIX/bin（または ~/.local/bin）に実際の sully-mcp ラッパーを作成し、検証されていない curl | sh パイプラインを使用することはありません。プライベート署名鍵は、リリースオペレーターによって MCP_RELEASE_ED25519_PRIVATE_KEY を通じて一時的に供給され、コミットされることはありません。

セキュリティモデル

ローカルリスナーにはループバックホストのみが受け入れられます。MCP と管理の資格情報は独立した 64 桁の 16 進数のランダム値であり、定数時間比較で比較されます。設定は制限的な権限で UTF-8 として書き込まれます。サーバーは /health、ツールリスト、通常のエラー、監査レコード、またはジョブメタデータからトークンを返しません。監査エントリは編集され、制限されています。副作用のあるツールは自動的に再試行されることはありません。破壊的なアップストリームツールは、呼び出し元によって明示的に許可リストに登録される必要があります。

このリポジトリは、SULLYTEST2 から引き継がれた PolyForm Noncommercial License 1.0.0 の下でライセンスされています。