podkop-mcp

podkop-mcp

言語： English · Русский

SSH 経由で OpenWrt 上の Podkop および Forkop を管理する MCP サーバーです。

UCI を手作業で編集したり、uci add_list の落とし穴を覚えておいたり、base64 でラップしたスクリプトを PowerShell に渡したりする必要はありません。MCP クライアントにドメインの追加、セクションの一覧表示、ライブ接続の確認、サービスの再読み込み、問題のある変更のロールバックを依頼できます。ドライラン、バックアップ、秘匿情報のマスキングも組み込まれています。

ステータス：アルファ版です。Forkop 1.0.5 および Forkop 2.0.0（OpenWrt 25.12.6）に対するライブ環境での読み取り専用テストを実施済みです。書き込み／適用パスは、実際の Forkop 2.0.0 および Podkop 0.7.24 を使用した使い捨ての OpenWrt Docker コンテナーで検証済みです。バックエンドのスキーマは PODKOP_MCP_PROFILE_TTL 秒ごとに再検証されます（既定値は 30 です）。

理由

Podkop／Forkop を手作業で管理するのはエラーが発生しやすいためです。

• Forkop 1.x はドメインをスペース区切りの文字列 1 つ（section.domain）に保存します。 uci add_list を 1 回実行すると、完全一致の domain リストになり、サブドメインがルーティングされなくなっても気づきにくくなります。
• Forkop 2.x は、# コメントを含む複数行の section.destinations テキストを使用します。
• Podkop は本物の UCI リスト（section.user_domains）を使用します。
• Forkop の再読み込みは非同期で行われます。再読み込みの失敗を検出し、ロールバックする必要があります。
• サブスクリプション URL とプロキシ文字列は秘密情報であり、ログに残ってしまいます。

ルーター自体で実行する MCP サーバーとは異なり、podkop-mcp は管理者のマシン上で動作し、SSH 経由で OpenWrt と通信して、Podkop／Forkop の仕様（ドライラン、バックアップ、ロールバック、秘密情報のマスキング）に対応します。これらはすべて、型付き MCP ツールの背後に隠されています。

機能

• MCP パラメーターから指定する鍵を使った SSH トランスポート：鍵ファイル、インラインの base64／PEM、または ~/.ssh/config のエイリアスに対応します。ホスト鍵の検証、キープアライブ、タイムアウトにも対応します。
• バックエンドの検出：Forkop 1.x、Forkop 2.x、Podkop に対応し、インストール済み CLI から機能を判定します。
• ubus call uci get の JSON と、書き込み用の uci を使った UCI への完全なアクセス：任意のオプションを読み取りまたは変更できます。対象パッケージは forkop／podkop に限定されます。
• バックエンドの形式を保持する ドメイン操作：追加／削除／置換、網羅状況の検索、ライブ接続から未登録ホストを提案、FakeIP の確認に対応します。
• セクション：一覧表示、確認、作成、更新、有効化／無効化、子のサブスクリプション／URLTest 項目を連鎖的に削除します。
• サブスクリプションとプロキシグループ：一覧表示、追加、削除、更新、遅延のテスト、プロキシの選択（Forkop 2.x）に対応します。
• 監視：サービス／システムのステータス、ヘルスチェック、ログ、ライブ接続、トラフィックレート、プロキシ遅延に対応します。
• 安全性：変更を伴うツールは既定でドライランです。apply=true を指定すると、ルーター側のバックアップを作成し、UCI をコミットして再読み込みを行い、検証します。失敗時はバックアップが自動的に復元されます。PODKOP_MCP_READ_ONLY=1 を設定すると、すべての書き込みがブロックされます。
• 秘密情報は既定でマスキングされます：サブスクリプション URL、proxy_string、鍵、トークンが対象です。生データのエクスポートには reveal_secrets=true が必要です。
• バイリンガルのドキュメント（英語／ロシア語）と CI に対応します。

サポート対象

機能	Forkop 1.x	Forkop 2.x	Podkop
UCI パッケージ	forkop	forkop	podkop
ドメインオプション	domain（文字列）	destinations（複数行）	user_domains（リスト）
コミュニティリスト	はい	はい	はい
ルールセット	いいえ	はい	はい
Clash API	アクション CLI	HTTP CLI	アクション CLI
プロキシランタイムの選択	—	はい	—
読み取り専用モニタリング	はい	はい	はい

インストール

要件：

• Python 3.10 以降（CI テスト対象は 3.10～3.14）
• Forkop または Podkop がインストールされた OpenWrt ルーター
• ルーターへの SSH キーアクセス

PyPI からインストール：

pip install podkop-mcp
# or run without installing
uvx podkop-mcp

ソースからインストール：

git clone https://github.com/mikel38487/podkop-mcp.git
cd podkop-mcp
python -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .

MCP クライアントを設定します（Claude Desktop、Cursor、DSH など）：

{
  "mcpServers": {
    "podkop": {
      "command": "podkop-mcp",
      "env": {
        "PODKOP_MCP_SSH_HOST": "192.168.1.1",
        "PODKOP_MCP_SSH_USER": "root",
        "PODKOP_MCP_SSH_KEY_PATH": "C:/Users/<user>/.ssh/router_key",
        "PODKOP_MCP_KNOWN_HOSTS": "C:/Users/<user>/.ssh/known_hosts",
        "PODKOP_MCP_HOST_KEY_POLICY": "reject"
      }
    }
  }
}

既存の ~/.ssh/config のエイリアスを使用することもできます：

"env": {
  "PODKOP_MCP_SSH_CONFIG_HOST": "router-home",
  "PODKOP_MCP_SSH_KEY_PATH": "C:/Users/<user>/.ssh/router_key",
  "PODKOP_MCP_HOST_KEY_POLICY": "reject"
}

ホストキーのポリシーはデフォルトで reject です。まずルーターのキーを known_hosts に追加してください（通常の ssh ログインなどで行えます）。accept-new は 新しいルーターで一度だけ使用する TOFU の利便機能です。初回接続時の MITM 攻撃を防ぐものではありません。

モデルに依頼します：

• 「podkop_doctor を実行して、バックエンドのバージョンを表示してください。」
• 「example.com と cdn.example.com を main に追加してください。まず差分を見せてください。」
• 「ドメイン数とともにセクションを一覧表示してください。」
• 「ライブ接続にあるホストのうち、どのセクションにも含まれていないものはどれですか？」
• 「直近 2 秒間のトラフィックと上位のクライアントを表示してください。」
• 「youtube セクションを無効にして、再読み込みしてください。」

ドキュメント

• ツールリファレンス · Справочник инструментов
• アーキテクチャ · Архитектура
• 互換性 · Совместимость
• トラブルシューティング · Диагностика
• OpenWrt Docker でのテスト · Тестирование в Docker
• セキュリティ · Безопасность
• セキュリティポリシー、コントリビューション

書き込み操作の仕組み

dry-run (default)
  → read config, compute normalized diff, show uci commands

apply=true
  → cp /etc/config/<pkg> /etc/podkop-mcp/backups/<ts>-<reason>.uci
  → uci set/add_list/delete (package restricted to forkop/podkop)
  → uci commit
  → /etc/init.d/<pkg> reload
  → poll get_status up to ~35 s
  → on failure: restore backup, commit, reload
  → return diff, backup id, health summary

ユーザー入力から組み立てたシェル文字列を使ってコマンドを実行することはありません。値は shlex でシェル用にエスケープされ、スクリプトは標準入力経由で sh に送信されます。パスは 検証されます。ルーターに base64 アプレットは必要ありません。

ツール概要

グループ	ツール
システム	podkop_doctor、podkop_status、podkop_system_info、podkop_health、podkop_logs、podkop_cli、podkop_core_features、podkop_import_check、podkop_installer_status、podkop_installer_log
設定	podkop_config_get、podkop_config_export、podkop_option_get/set/delete、podkop_backup_create/list/restore
セクション	podkop_sections_list、podkop_section_get/create/update/delete/enable、podkop_tunnel_create、podkop_child_create
ドメイン	podkop_domains_list/add/remove/replace/find/suggest、podkop_domain_check
リスト	podkop_community_lists_get/update
接続	podkop_connections_config、podkop_subscription_add/delete/update、podkop_proxies_list、podkop_proxy_select/test
モニタリング	podkop_monitor_snapshot、podkop_connections_live、podkop_traffic
サービス	podkop_service_action、podkop_lists_update

詳細なリファレンス：docs/tools.md。

設定リファレンス

変数	デフォルト	意味
PODKOP_MCP_SSH_HOST	—	ルーターのアドレス
PODKOP_MCP_SSH_PORT	22	SSH ポート
PODKOP_MCP_SSH_USER	root	SSH ユーザー
PODKOP_MCP_SSH_KEY_PATH	—	秘密鍵のパス
PODKOP_MCP_SSH_KEY	—	インライン秘密鍵（PEM）
PODKOP_MCP_SSH_KEY_B64	—	インライン鍵、base64
PODKOP_MCP_SSH_KEY_PASSPHRASE	—	鍵のパスフレーズ
PODKOP_MCP_SSH_PASSWORD	—	鍵の代わりに使用するパスワード（シークレットです。環境経由で渡し、決してコミットしないでください）
PODKOP_MCP_SSH_CONFIG_HOST	—	~/.ssh/config のエイリアス
PODKOP_MCP_KNOWN_HOSTS	~/.ssh/known_hosts	ホスト鍵ファイル
PODKOP_MCP_HOST_KEY_POLICY	reject	reject、accept-new、ignore
PODKOP_MCP_CONNECT_TIMEOUT	8	SSH 接続タイムアウト（秒）
PODKOP_MCP_COMMAND_TIMEOUT	45	コマンドのタイムアウト（秒）
PODKOP_MCP_BACKEND	auto	auto、forkop、podkop。指定した CLI がインストールされている必要があります
PODKOP_MCP_READ_ONLY	0	すべての書き込みをブロック
PODKOP_MCP_BACKUP_DIR	/etc/podkop-mcp/backups	ルーター側のバックアップ
PODKOP_MCP_BACKUP_KEEP	30	保持するバックアップの数
PODKOP_MCP_MAX_OUTPUT_BYTES	200000	取得するコマンド出力の上限（バイト）
PODKOP_MCP_LOG_LEVEL	INFO	サーバーログのレベル（標準エラー出力）（DEBUG、INFO、WARNING、ERROR、CRITICAL）
PODKOP_MCP_PROFILE_TTL	30	バックエンドプロファイルをルーターに対して再検証するまでの秒数
PODKOP_MCP_TARGETS	—	複数のルーターを指定する JSON
PODKOP_MCP_CONFIG	—	複数のルーターを指定する JSON ファイルのパス。PODKOP_MCP_TARGETS および単一ルーター用の変数より優先されます
PODKOP_MCP_TARGET_NAME	router	PODKOP_MCP_SSH_HOST／PODKOP_MCP_SSH_CONFIG_HOST で定義された単一ルーターの名前。JSON のターゲットリストを使用する場合は無視されます

複数のルーターを管理するには、ルーターを JSON ファイルに記述し、 PODKOP_MCP_CONFIG にそのファイルを指定します。

{
  "targets": {
    "home": {"host": "192.0.2.10"},
    "office": {"host": "192.0.2.11", "port": 2222}
  },
  "default_target": "home"
}

"env": {
  "PODKOP_MCP_CONFIG": "~/.config/podkop-mcp/targets.json"
}

ツール呼び出しで target が指定されていない場合は、default_target のルーター（または省略時は最初のルーター）が使用されます。もう一方のルーターを使用するには、"target": "office" を渡します。PODKOP_MCP_TARGET_NAME は、このファイルからターゲットを選択するものではありません。PODKOP_MCP_SSH_HOST／PODKOP_MCP_SSH_CONFIG_HOST で定義された単一ルーターの名前を指定するだけです。

テスト

python -m pytest -q                 # unit + fake router + live/docker skipped
python scripts/smoke_mcp.py         # MCP stdio handshake
PODKOP_MCP_LIVE=1 python -m pytest -q -m live   # read-only, real router

実際の SSH／UCI／適用処理をテストするための OpenWrt Docker コンテナーがあります。 実際の openwrt/rootfs ユーザーランドと実際の ubus／rpcd／dropbear／uci を使用し、Forkop CLI／init はスタブを使用します（sing-box／nft は含みません）。

.\scripts\openwrt-docker.ps1
. .\.tmp\openwrt-env.ps1
.\.venv\Scripts\python.exe -m pytest -q -m docker_ssh
.\scripts\openwrt-docker.ps1 -Stop

これはコンテナーであり、VM ではありません。ホストカーネルを共有します。VM の詳しい手順と制限事項は docs/testing.md を参照してください。ライブテストで本番ルーターに書き込むことはありません。書き込み操作は Docker コンテナーとフェイクトランスポートでテストされます。

制限事項

• MCP トランスポートは stdio です。SSE／HTTP は対象外です。
• セクションの並べ替えにはまだ対応していません（UCI の順序はファイル順です）。必要に応じて、エクスポート／編集と podkop_config_export を使用してください。
• Podkop のサブスクリプション処理はベストエフォートです。アクティブなターゲットは Forkop です。
• Forkop 1.x はプロキシごとのアクティブなレイテンシテストに対応していません。URLTest の履歴を使用してください。
• Forkop／Podkop の自動アップグレードには対応していません。

ライセンス

MIT。Forkop と Podkop は、それぞれ独自のライセンスに基づく別個のプロジェクトです。

関連団体ではありません

これは独立した非公式プロジェクトです。Podkop、Forkop、OpenWrt の各プロジェクトとは提携しておらず、承認や保守も受けていません。