Janus

二つの顔。一つのクラスター。キーの露出なし。

janus-mcp.ns47.com · PyPI · 変更履歴

---

Janus とは？

Janus は、AI アシスタントが Kubernetes クラスターを安全かつ制御された形で利用できるようにする MCP（Model Context Protocol） サーバーです。ローカルで動作し、KUBECONFIG を厳重に保持しながら、適切にスコープを限定したツールを通じて LLM が操作できるようにします。これにより、トークン、証明書、API サーバーの URL をサードパーティのモデルに渡すことなく、AI コパイロットの力を活用できます。

ローマ神話の門の神（有名な二つの顔で同時に前後を見る）にちなんで名付けられた Janus は、LLM に対しては明確で宣言的なツール定義を提示し、クラスターに対しては完全な管理者アクセスを使用します。その一方で、両者が不適切に接触しないようにします。

課題

LLM は Kubernetes のデバッグ、運用、分析に非常に役立ちます。しかし、KUBECONFIG をチャット画面に貼り付けたり、外部 API に送信したりした瞬間、王国の鍵を渡してしまうことになります。ほとんどの組織にとって、それは受け入れられません。

モデルのセルフホストは有効ですが、最先端の LLM をローカルで実行できる、あるいは実行したいと考える人ばかりではありません。Janus は第三の道を提供します。認証情報はオンプレミス（またはノート PC）に保持し、リモートモデルにはサニタイズ済みの高レベルなクラスター情報だけを扱わせます。

仕組み

┌──────────────┐       ┌────────────────┐       ┌───────────────┐
│ LLM Client   │<─────>│ Janus (local)  │<─────>│ Kubernetes    │
│ (Claude,     │   MCP │ holds the      │   k8s │ API Server    │
│ VS Code,     │       │ KUBECONFIG     │   API │               │
│ custom)      │       │ redacts output │       │               │
└──────────────┘       └────────────────┘       └───────────────┘

1. テキストダンプではなくツール — Janus は、LLM が呼び出せる一連の MCP ツール（get_pods、describe_deployment、get_events など）を公開します。生のクラスター状態を渡すことはありません。
2. 自動的な情報の除去 — Kubernetes API からのすべての応答をサニタイズします。シークレット、トークン、環境変数の値、機密性の高いメタデータは、LLM に見える前に取り除かれます。
3. 書き込み操作には人間の承認が必要 — 読み取り専用の操作はすぐに実行されます。破壊的な操作（再起動、スケーリング、削除）には、MCP クライアント内で明示的な確認が必要です。LLM は操作を提案できますが、実行の決定は人間が行います。
4. スコープを限定したアクセス — Janus は、特定の名前空間、クラスターのセット、またはリソースの一部にアクセスを限定できます。これにより、KUBECONFIG が許可する範囲に加えて、さらなる安全策を設けられます。

特徴

• 🔒 認証情報の露出ゼロ — Janus を実行しているプロセスから KUBECONFIG が外部に出ることはありません。
• 🔍 充実した読み取り専用の診断機能 — ポッド、ワークロード、サービス、イベント、ログ、エンドポイント、クォータ、要求値と比較した現在の CPU／メモリ使用量（kubectl top+）、サニタイズ済みテンプレート差分を含むロールアウト履歴（「最近何が変わったか？」）。
• ✍️ 保護された書き込み操作 — ロールアウトの再起動とロールバック、スケーリング、ポッドの削除（UID に紐付け）、CronJob の一時停止／再開／実行、ノードのコーディング。いずれもモデル外で人間の承認を必須とし、オペレーターが有効にしない限り登録されません。
• 🧹 プラグイン可能な情報除去エンジン — 適切なデフォルト設定を備え、独自のパターンにも簡単に拡張できます。
• 🧭 二通りのクラスター概要 — get_cluster_summary ツールに加え、ピン留め可能な cluster://summary MCP リソースを提供します。多数のツール呼び出しを行わずに、LLM にコンテキストを与えられます。
• 🩺 ガイド付きトリアージ — diagnose_namespace プロンプトテンプレートは、MCP プロンプトに対応する任意のクライアントで、モデルを構造化された調査（概要 → ポッド → 警告 → 対象を絞ったログ → 診断）へと導きます。
• 🧪 あらゆる MCP クライアントに対応 — Claude Code、Claude Desktop、VS Code、Codex、自作のエージェントループで動作します。

ロードマップ

• 配布 ✓ — PyPI janus-mcp-server · コンテナー ghcr.io/tonylchang/janus-mcp · Homebrew tonylchang/tap/janus-mcp
• ストリーム可能な HTTP サイドカーモード（ベアラートークン + Origin 検証）

クイックスタート

uv tool install janus-mcp-server   # or: pipx install janus-mcp-server
#     brew install tonylchang/tap/janus-mcp

mkdir -p ~/.config/janus-mcp
curl -fsSL https://raw.githubusercontent.com/tonylchang/janus-mcp/main/examples/config.yaml \
  -o ~/.config/janus-mcp/config.yaml
$EDITOR ~/.config/janus-mcp/config.yaml   # set your kubeconfig context + namespaces

# register with Claude Code:
claude mcp add kubernetes -- janus-mcp serve

Python ツールチェーンがありませんか？同じサーバーがコンテナイメージとしても提供されています。

claude mcp add kubernetes -- docker run -i --rm \
  -v ~/.kube/config:/home/janus/.kube/config:ro \
  -v ~/.config/janus-mcp:/home/janus/.config/janus-mcp:ro \
  ghcr.io/tonylchang/janus-mcp:latest

Claude Desktop、VS Code/Copilot、Codex CLI、Cursor の登録手順は、 クイックスタートガイド をご覧ください。

次のような質問を AI アシスタントにしてみましょう。 「prod 名前空間でポッドがクラッシュしているのはなぜですか？」

Janus は関連情報を取得してサニタイズし、LLM が何が起きているのかを安全に解説します。

ドキュメント

• 運用者向けランブック — インストール、最小権限の RBAC、承認、監査ログ、トラブルシューティング
• 脅威モデル — 5 つのセキュリティ不変条件と、CI による検証方法
• rbac/ — 最小権限のマニフェスト（含まれていないものにご注意ください。シークレットは一切含まれません）

Janus は現在、活発に開発中です。