MCP SFTP Orchestrator

🚀 MCP Orchestrator — SSH/SFTP オーケストレーションサーバー

v11.8.0 Security Refresh — 82 個のツールが MCP 標準アノテーションを公開するようになりました。infra_overview は引数なしでは軽量なままですが、infra_overview { alias: "..." } を実行すると、ライブ検出を行い、Nginx／ドメイン、ポート、Docker／Compose、サービスを関連付けます。CHANGELOG.md をご覧ください。

バージョン：11.8.0
ツール：82
ライセンス：MIT
Node：>= 18.0.0
変更履歴：CHANGELOG.md

AI エージェントにサーバー群をオーケストレーションする機能を提供する、MCP（Model Context Protocol、stdio トランスポート）サーバーです。SSH、SFTP、ローカル／リモートのファイル編集（ハッシュセーフ）、サーバー間差分、シェル PTY、インフラスナップショット、プロトコルメモ、プロジェクト、作業セッション、インベントリ、SSH トラスト（pubkey）、エイリアスグループ、サーバー群の監査に対応します。

---

✨ 主な機能（v11.6）

分野	機能
実行	task_exec のマルチサーバー対応／group:oci／破壊的操作のドライラン／強制実行
ファイル	file_read／file_edit（精密編集）／file_write + ハッシュ + dryRun + バックアップ
サーバー群	メモ、infra_audit、fleet_status、server_inventory
プロジェクト	ローカル↔リモートのレジストリ + project_diff
作業	work_start → 編集 → work_end（作業メモを自動作成）
トラスト	ssh_authorize_key（pubkey のみ、デフォルトで dry_run）
セキュリティ	シークレットのマスキング、グローバル RO + エイリアスごとの RO、ブロックリスト、堅牢な SSH プール

---

📦 インストール

git clone https://github.com/fkom13/mcp-sftp-orchestrator.git
cd sftp-mcp   # ou tools/sftp-mcp
npm install
cp .env.example .env
# Éditer MCP_DATA_DIR et chemins de clés

前提条件：Node.js >= 18

---

⚙️ 設定（.env）

すべての変数は任意です。

変数	デフォルト	説明
MCP_DATA_DIR	~/.config/mcp-orchestrator	データフォルダー（JSON、スナップショット、プロジェクトなど）
MCP_SYNC_TIMEOUT_S	120	タスクがバックグラウンドに移行するまでの時間（秒）
MCP_DEFAULT_CMD_TIMEOUT_S	600	SSH コマンドのタイムアウト（秒）。0 = 無制限
MCP_INTERACTIVE_CMD_TIMEOUT_S	300	インタラクティブコマンドのタイムアウト（秒）。0 = 無制限
MCP_MAX_WAIT_TIMEOUT_S	600	task_wait の最大タイムアウト（秒）
MAX_CONNECTIONS_PER_SERVER	5	サーバーごとの SSH プール最大数
MIN_CONNECTIONS_PER_SERVER	1	サーバーごとの SSH プール最小数
IDLE_TIMEOUT	300000	アイドル状態の接続を閉じるまでの時間（ミリ秒）
KEEP_ALIVE_INTERVAL	30000	SSH キープアライブ間隔（ミリ秒）
MAX_QUEUE_SIZE	1000	ジョブキューの最大サイズ
SAVE_INTERVAL	5000	キューの自動保存間隔（ミリ秒）
MCP_ALLOWED_ROOTS	(空)	ローカルパスで許可されるルート（CSV）
MCP_READONLY	false	1 = 書き込み／変更を伴う実行を拒否（グローバル）
MCP_COMPACT	false	1 = 応答を切り詰める（エージェントのトークン用）
MCP_DEBUG	false	stderr に詳細ログを出力

MCP_DATA_DIR 内のファイル

ファイル	内容
servers.json	SSH エイリアス（host、user、keyPath／password、port?、readonly?）
apis.json	API カタログ（ツールで読み取る際にシークレットをマスキング）
queue.json / queue.backup.json	ジョブ
history.json	タスク履歴
server_notes.json	サーバーごとのプロトコル／メモ
server_groups.json	エイリアスグループ
projects.json	プロジェクトレジストリ
work_sessions.json	作業セッション
policies.json	コマンドのブロックリスト
tunnels.json / tunnel_allowlist.json	SSH トンネル
infra_snapshots/	コンテンツアドレス方式のスナップショット

---

🔌 MCP クライアント接続

Grok / config.toml

[mcp_servers.orchestrator]
command = "node"
args = ["/chemin/absolu/sftp-mcp/server.js"]
# optionnel:
# env = { MCP_DATA_DIR = "/chemin/absolu/sftp-mcp/data" }

OpenCode / Claude Desktop（JSON）

{
  "mcpServers": {
    "orchestrator": {
      "command": "node",
      "args": ["/chemin/absolu/sftp-mcp/server.js"],
      "env": {
        "MCP_DATA_DIR": "/chemin/absolu/sftp-mcp/data"
      }
    }
  }
}

コードを変更した後は、MCP サーバーを再読み込みしてください（/mcps → r またはセッションを再起動）。system_diagnostics → version: "11.8.0" を確認してください。

---

🧰 ツールリファレンス（82）

診断と監査

ツール	説明
help	ツールガイド + .env + ヒント
guide	AI マニュアル（ワークフロー、チートシート、落とし穴、監査、セキュリティ）
system_diagnostics	キュー、プール、サーバー/API 非表示、バージョン、readOnly
infra_audit	サーバー群 + プロジェクト + メモ + クラッシュの概要
infra_overview	サーバー + メモ（簡易ビュー）
fleet_status	SSH 並列 ping（レイテンシ、負荷、ディスク）
server_inventory	簡易インベントリ（pm2/docker/disk/home、キャッシュ 10 分）

サーバーとグループ

ツール	説明
server_add	エイリアスの CRUD（keyPath または password、port、readonly）
server_list	一覧（パスワードは非表示）
server_remove	エイリアスを削除
server_group_list/set/remove	グループ（oci、contabo など）。使用方法：group:oci またはグループ名

プロジェクト（v11.6）

ツール	説明
project_list / project_get / project_set / project_remove	レジストリ
project_resolve	→ { local, remote, ignore, runtime }
project_diff	プロジェクトのローカル↔リモート差分

project_set の例：

{
  "name": "p-image",
  "local": { "path": "/home/.../dev-serveur/p-image" },
  "servers": {
    "prod": {
      "alias": "fkomprodmini2_prod",
      "path": "/home/ubuntu/p-image",
      "runtime": { "pm2": "p-image", "port": 5002 },
      "url": "https://pruna.esprit-artificiel.com"
    }
  },
  "ignore": ["node_modules", ".git", "data"]
}

作業セッション（v11.6）

ツール	説明
work_start	ログを開始します（alias、project、tag、任意のスナップショット）
work_log	イベント（file_edit、task_exec など）
work_list	アクティブなセッション（+ 履歴）
work_end	セッションを終了し、server_note に last_intervention を記録

SSH 信頼（v11.6）

ツール	説明
ssh_authorize_key	リモートの authorized_keys に公開鍵を追加します。デフォルトは dry_run。ソース：string | local_path | alias

{
  "target_alias": "fkomprodmini1_prod",
  "source": { "type": "alias", "alias": "vps_contabo" },
  "comment": "fleet-from-contabo",
  "dry_run": true
}

ポリシー

ツール	説明
policy_blocklist_list/add/remove	コマンドのブロックリスト（shell + sequences にも適用）

API カタログ

ツール	説明
api_add / api_list / api_remove / api_check	モニタリング（一覧ではキーを非表示）

タスク実行

ツール	説明
task_exec	SSH；alias | 配列 | all | group:x；破壊的操作には dry_run/force
task_exec_interactive	yes/no のプロンプト、メニュー
task_exec_sequence	1 台のサーバーでシーケンスを実行（各ステップでポリシーを適用）
task_transfer	SFTP による upload/download/server_to_server
task_transfer_multi	複数転送 + glob

ファイル / 差分 / Shell / スナップショット

分類	ツール
ファイル	file_read, file_write, file_edit
差分	diff_files, diff_folders, compare_all_sources
Shell	shell_create, shell_exec（+ skip_policy）, shell_list, shell_close
スナップショット	snapshot_create/list/diff/restore/delete

安全な編集：file_read → hash → file_edit + expectedHash（+ dryRun / backup）。

サーバーメモ

ツール	説明
server_note_set/get/list/remove	手順（説明、サービス、警告、介入）

モニタリングとログ

ツール	説明
get_system_resources	CPU / RAM / ディスク
get_services_status	systemd / Docker / PM2
get_fail2ban_status	Fail2Ban
check_api_health	SSH+curl 経由の HTTP
get_pm2_logs / get_docker_logs / tail_file	ログ

キュー

ツール	説明
task_queue / task_status / task_history / task_wait / task_logs	追跡
task_retry / task_retry_all	再実行
task_purge	消去（デフォルトは dry_run）
queue_stats / pool_stats	統計

Tmux とトンネル

ツール	説明
tmux_create/exec/read/list/kill	リモート tmux セッション
tunnel_create/list/close	ローカル/リモート/socks の SSH トンネル
tunnel_allowlist_add/remove	トンネルで許可するポート

---

📖 推奨エージェントワークフロー

セッション開始時

infra_audit  (ou infra_overview)
fleet_status
project_list / project_resolve

プロジェクトでの作業

work_start { project: "p-image", alias: "fkomprodmini2_prod", tag: "fix-x", message: "…" }
file_read → file_edit (expectedHash, dryRun puis apply)
work_log { type: "file_edit", path: "…" }
work_end { summary: "…" }   → note serveur mise à jour
project_diff { name: "p-image" }

長時間実行コマンド

task_exec { timeout: 0, … }  → si > syncTimeout → task_wait { id }

複数サーバーのターゲット

task_exec { alias: "group:oci", cmd: "hostname" }
task_exec { alias: "all", cmd: "uptime" }

---

🏗️ アーキテクチャ

Client MCP (stdio)
    │
server.js ─── 82 tools
    │
    ├── queue.js          File d’attente persistante + purge/retry
    ├── ssh.js / sshPool  Exécution + pool (retry safe, port configurable)
    ├── sftp.js           Transferts (server_to_server via sourceAdapter/pool)
    ├── sourceAdapter.js  Local fs | remote SFTP pool
    ├── fileOps.js        Read/write/edit + hash + dryRun + backup
    ├── diffEngine.js / compareEngine.js / diffFormatter.js
    ├── shellSessions.js  PTY persistants + policy
    ├── snapshotManager.js
    ├── projects.js / workSession.js / inventory.js / groups.js / fleet.js
    ├── sshTrust.js       authorized_keys (pubkey only)
    ├── servers.js / apis.js / notes.js / policies.js / tunnels.js
    ├── history.js / guide.js / config.js / utils.js

ジョブのライフサイクル

pending → running → completed | failed | partial
                      ↓ (redémarrage MCP pendant running)
                    crashed → task_retry → pending

---

🔒 セキュリティ

メカニズム	詳細
シークレット	api_list / 診断ではマスクされます（*** + 末尾4文字）
シェルエスケープ	curl、ログ、パスに escapeShellArg を適用
ブロックリスト	policies.json；shell + sequence を含む；強制するには skip_policy を指定
全体の読み取り専用	MCP_READONLY=1
エイリアスの読み取り専用	servers.json で "readonly": true を指定
破壊的操作	危険なパターンが含まれ、force:true が指定されていない場合、task_exec はドライランを実行
信頼	公開鍵のみ；デフォルトで dry_run
キー	SSH には keyPath を推奨；API シークレットには Vaultwarden を使用

---

🧪 テスト

npm test:unit    # p0 + p1 + p16 (43 tests)
npm test         # unit + smoke MCP + features
node diagnose.js # diagnostic local optionnel

ファイル	カバレッジ
test_p0_unit.js	utils、policies、redact、time-outs、version
test_p1_unit.js	groups、purge、destructive、RO env
test_p16_unit.js	projects、work session、compact、sshTrust
test_mcp.js	SDK のスモークテスト
test_features.js	queue / pool / globs / prompts

---

🛣️ 最近のバージョン

バージョン	内容	gencodedoc スナップショット
11.6.1	マルチエージェントの強化：全体的な読み取り専用、サーバー間の dossiers/force、シンボリックリンク対策の許可ルート、shell/tmux の引用、queue + アトミックな JSON ストア	—
11.6.0	プロジェクト、作業セッション、インベントリ、ssh_authorize_key、エイリアスの読み取り専用、compact	#23（最終ドキュメント）
11.4.0	fleet、infra_audit、groups、retry_all、purge、pool の書き換え	#21
11.3.0	シークレットのマスク、shell/seq ポリシー、SSH ポート、一部完了の待機	#20
10.4–10.0	ファイル操作、diff、shell、スナップショット、メモ、ガイド	#17–19
9.x / 8.x	SFTP force、タイムアウト、インタラクティブ機能、基本的なセキュリティ	—

詳細：CHANGELOG.md · 過去の計画：ROADMAP.md、ROADMAP_EXTENDED.md。

---

📄 ライセンス

MIT — Copyright (c) 2025-2026 Franck (fkom13)