MCP Kubernetes Ro

🚀 Kubernetes read-only MCP server

mcp-kubernetes-roは、AIアシスタントにKubernetesクラスタへの読み取り専用アクセスを提供するModel Context Protocol (MCP)サーバーです。これにより、AIモデルはリソースのリスト表示、リソースの詳細取得、ポッドログの取得、APIリソースの探索、およびBase64エンコード/デコード操作を行うことができます。そして、読み取り専用アクセスによってセキュリティを維持します。

このサーバーは、ローカルのkubectl設定を利用し（kubectlのインストールは必須ではありません）、Kubernetesクラスタに対する安全な読み取り専用インターフェースを提供します。破壊的な操作を防ぎながら、クラスタの包括的な検査とトラブルシューティング機能を可能にします。

✨ 主な機能

• kubectlを必要としない：MCPサーバーは、ローカルのkubectl設定を使用してKubernetesクラスタに接続しますが、バイナリ自体は必要としません。したがって、kubectlがマシンにインストールされていない場合でも動作します。
• リソースのリスト表示：任意のKubernetesリソースをタイプ別にリスト表示でき、ラベル、フィールド、および名前空間でオプションのフィルタリングが可能です。
• リソースの詳細取得：特定のKubernetesリソースの完全な詳細を取得できます。
• ポッドログの取得：高度なフィルタリングオプション（grepパターン、時間フィルタリング、および前のログ）を使用してポッドログを取得できます。
• コンテナの探索：ポッド内のコンテナをリスト表示し、ターゲットのログにアクセスできます。
• APIの探索：利用可能なKubernetes APIリソースとその機能を探索できます。
• Base64ユーティリティ：Kubernetesのシークレットと設定のためにBase64データのエンコードとデコードが可能です。
• 複数のトランスポートモード：標準入出力（stdio）とServer-Sent Events (SSE)の両方の通信モードをサポートしています。
• 読み取り専用セキュリティ：破壊的な操作を完全に防止しながら、完全な検査機能を維持します。
• 名前空間のサポート：特定の名前空間またはクラスタ全体のリソースで作業できます。
• 高度なフィルタリング：ラベルセレクター、フィールドセレクター、およびページネーションをサポートしています。
• コマンドごとのコンテキスト：個々のコマンドに異なるKubernetesコンテキストを指定できます。
• 環境変数のサポート：KUBECONFIG環境変数の自動検出機能があります。
• 起動時の接続性チェック：起動時にクラスタの接続性と基本的なアクセス許可を自動的に検証します。

📦 インストール

リリースページから事前にビルドされたバイナリをダウンロードすることができます。

また、macOSまたはLinuxではHomebrewを使用してインストールすることもできます。

brew install patrickdappollonio/tap/mcp-kubernetes-ro

NPMパッケージとして使用することもできます。ただし、AIエージェントに設定を提供する必要があります。

npx -y @patrickdappollonio/mcp-kubernetes-ro

最後に、DockerユーザーはGitHub Container Registryから事前にビルドされたイメージを使用することができます。

docker pull ghcr.io/patrickdappollonio/mcp-kubernetes-ro:latest

エディタの設定

mcp-kubernetes-roを使用するために、エディタの設定に以下の構成を追加してください。

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "mcp-kubernetes-ro",
      "args": [
        // 必要に応じてコメントを外して修正してください:
        // "--kubeconfig=/path/to/kubeconfig",
        // "--namespace=default",
        // "--transport=stdio",
        // "--port=8080",
        // "--disabled-tools=get_logs,decode_base64"
      ],
      "env": {
        // 必要に応じてKUBECONFIG環境変数を設定してください:
        // "KUBECONFIG": "/path/to/kubeconfig",
        // 必要に応じてMCP_KUBERNETES_RO_DISABLED_TOOLS環境変数を設定してください:
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // または汎用のDISABLED_TOOLS環境変数を使用してください:
        // "DISABLED_TOOLS": "get_logs,decode_base64"
      }
    }
  }
}

上記のように$PATHから直接mcp-kubernetes-roを使用することもできますし、バイナリへの完全なパス（例：/path/to/mcp-kubernetes-ro）を指定することもできます。

また、npxパッケージとして使用することで、インストールプロセスを簡略化することもできます。

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "npx",
      "args": [
        "-y",
        "@patrickdappollonio/mcp-kubernetes-ro"
        // 必要に応じてコメントを外して修正してください:
        // "--kubeconfig=/path/to/kubeconfig",
        // "--namespace=default",
        // "--transport=stdio",
        // "--port=8080",
        // "--disabled-tools=get_logs,decode_base64"
      ],
      "env": {
        // 必要に応じてKUBECONFIG環境変数を設定してください:
        // "KUBECONFIG": "/path/to/kubeconfig",
        // 必要に応じてMCP_KUBERNETES_RO_DISABLED_TOOLS環境変数を設定してください:
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // または汎用のDISABLED_TOOLS環境変数を使用してください:
        // "DISABLED_TOOLS": "get_logs,decode_base64"
      }
    }
  }
}

そして、代わりにDockerイメージを利用する方法は以下の通りです。

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "KUBECONFIG=/root/.kube/config",
        "-v", "/path/to/kubeconfig:/root/.kube/config",
        "ghcr.io/patrickdappollonio/mcp-kubernetes-ro"
        // 追加のフラグをここに配置してください。例：--disabled-tools=get_logs,decode_base64
      ],
      "env": {
        // 必要に応じてKUBECONFIG環境変数を設定してください:
        // "KUBECONFIG": "/path/to/kubeconfig",
        // 必要に応じてMCP_KUBERNETES_RO_DISABLED_TOOLS環境変数を設定してください:
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // または汎用のDISABLED_TOOLS環境変数を使用してください:
        // "DISABLED_TOOLS": "get_logs,decode_base64"
      }
    },
  }
}

コンテナにkubeconfigファイルをマウントする必要があり、KUBECONFIG環境変数をマウントされたファイルのパスに設定するか、--kubeconfigフラグを使用して設定する必要があることに注意してください。

前提条件

• 有効なKubernetes設定ファイル（通常は~/.kube/config）
• 有効な資格情報とクラスタへのアクセス権（kubectlバイナリは必要ありません）
• 読み取り操作に適切なRBACアクセス許可
• Metrics Server（メトリクスツールに必要）：メトリクス機能（get_node_metrics、get_pod_metrics）を使用するには、Metrics Serverがクラスタにインストールされている必要があります。利用できない場合、これらのツールはエラーメッセージを返します。

💻 使用例

基本的な使用法

# デフォルトのkubeconfigとコンテキストで起動
mcp-kubernetes-ro

# 特定のkubeconfigで起動
mcp-kubernetes-ro --kubeconfig ~/.kube/config

# KUBECONFIG環境変数で起動
export KUBECONFIG=~/.kube/config
mcp-kubernetes-ro

# 特定の名前空間で起動
mcp-kubernetes-ro --namespace kube-system

# SSEモードで起動
mcp-kubernetes-ro --transport=sse --port=3000

高度な構成例

# 特定のkubeconfigを使用する本番クラスタ
mcp-kubernetes-ro \
  --kubeconfig ~/.kube/prod-config \
  --namespace monitoring

# 環境変数を使用したSSEモードの開発設定
export KUBECONFIG=~/.kube/dev-config
mcp-kubernetes-ro \
  --transport=sse \
  --port=8080

# コマンドごとのコンテキストを使用する（ツール呼び出しでコンテキストを指定）
# コンテキストは現在、ツールレベルで指定され、グローバルではありません。

# セキュリティまたはパフォーマンスの理由で特定のツールを無効にする
mcp-kubernetes-ro --disabled-tools=get_logs,decode_base64

# メトリクスサーバーが利用できない場合にメトリクスツールを無効にする
mcp-kubernetes-ro --disabled-tools=get_node_metrics,get_pod_metrics

# 本番環境で複数のツールを無効にする
mcp-kubernetes-ro \
  --kubeconfig ~/.kube/prod-config \
  --disabled-tools=encode_base64,decode_base64,get_logs

# 無効にするツールにアプリ固有の環境変数を使用する
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs,decode_base64
mcp-kubernetes-ro

# 無効にするツールに汎用の環境変数を使用する
export DISABLED_TOOLS=get_logs,decode_base64
mcp-kubernetes-ro

# コマンドラインフラグは両方の環境変数よりも優先されます
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs,decode_base64
export DISABLED_TOOLS=get_pod_metrics
mcp-kubernetes-ro --disabled-tools=get_node_metrics,get_pod_metrics

📚 ドキュメント

利用可能なMCPツール

利用可能な10個のツールがあります。

• list_resources：任意のKubernetesリソースをタイプ別にリスト表示し、オプションのフィルタリングが可能で、最新のものから順に並べられます。
• get_resource：特定のリソースの詳細を取得します。
• get_logs：高度なフィルタリングオプション（grepパターン、時間フィルタリング、および前のログ）を使用してポッドログを取得します。
• get_pod_containers：ポッド内のコンテナをリスト表示し、ログにアクセスします。
• list_api_resources：利用可能なKubernetes APIリソースとその詳細をリスト表示します（kubectl api-resourcesと同様）。
• list_contexts：kubeconfigファイルから利用可能なKubernetesコンテキストをリスト表示します。これは、他のツールでcontextパラメーターを使用するために利用可能なコンテキストを発見するのに役立ちます。
• get_node_metrics：メトリクスサーバーからノードのメトリクス（CPUとメモリ使用率）を取得します。結果はタイムスタンプでソートされ（最新のものから順）、一貫した順序とページネーションが可能です。組み込みのメトリクスサーバーエンドポイントはニードルベースのページネーションをサポートしていないためです。
• get_pod_metrics：メトリクスサーバーからポッドのメトリクス（CPUとメモリ使用率）を取得します。結果はタイムスタンプでソートされ（最新のものから順）、一貫した順序とページネーションが可能です。組み込みのメトリクスサーバーエンドポイントはニードルベースのページネーションをサポートしていないためです。
• encode_base64：テキストデータをBase64形式にエンコードします。
• decode_base64：Base64データをテキスト形式にデコードします。

ツールの管理

ツールの無効化

--disabled-toolsコマンドラインフラグまたは環境変数を使用して、ツール名のカンマ区切りリストで特定のツールを無効にすることができます。異なるユースケースに対応するために、2つの環境変数がサポートされています。

• MCP_KUBERNETES_RO_DISABLED_TOOLS：他のツールと衝突しないアプリ固有の変数です。
• DISABLED_TOOLS：環境内の複数のツールで共有できる汎用の変数です。

優先順位：

1. コマンドラインフラグ：--disabled-tools=NAMES（最も高い優先順位）
2. アプリ固有の環境変数：MCP_KUBERNETES_RO_DISABLED_TOOLS
3. 汎用の環境変数：DISABLED_TOOLS

これは以下の目的に役立ちます。

• セキュリティ：機密情報を公開する可能性のあるツール（例：get_logs、decode_base64）を無効にします。
• パフォーマンス：必要ない場合にリソースを大量に消費するツール（例：get_node_metrics、get_pod_metrics）を無効にします。
• 環境固有：クラスタで利用できないツール（例：メトリクスサーバーがインストールされていない場合のメトリクスツール）を無効にします。
• コンプライアンス：組織のポリシーを満たすために機能を制限します。

無効にできるツール名：

• list_resources
• get_resource
• get_logs
• get_pod_containers
• list_api_resources
• list_contexts
• get_node_metrics
• get_pod_metrics
• encode_base64
• decode_base64

ツールが無効になると、MCPサーバーに登録されず、利用可能なツールのリストに表示されません。無効にされたツールがスキップされたことを示すメッセージがstderrに記録されます。

例：

# コマンドラインフラグを使用する（最も高い優先順位）
mcp-kubernetes-ro --disabled-tools=encode_base64,decode_base64,get_logs

# アプリ固有の環境変数を使用する
export MCP_KUBERNETES_RO_DISABLED_TOOLS=encode_base64,decode_base64,get_logs
mcp-kubernetes-ro

# 汎用の環境変数を使用する
export DISABLED_TOOLS=encode_base64,decode_base64,get_logs
mcp-kubernetes-ro

# 優先順位のデモンストレーション：コマンドラインフラグは環境変数を上書きする
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs
export DISABLED_TOOLS=get_pod_metrics
mcp-kubernetes-ro --disabled-tools=encode_base64,decode_base64

# 優先順位のデモンストレーション：アプリ固有の環境変数は汎用の環境変数を上書きする
export MCP_KUBERNETES_RO_DISABLED_TOOLS=encode_base64,decode_base64
export DISABLED_TOOLS=get_logs,get_pod_metrics
mcp-kubernetes-ro

# 出力：Skipping disabled tool: "encode_base64"
# 出力：Skipping disabled tool: "decode_base64"

実行モード

標準（stdio）モード

デフォルトでは、mcp-kubernetes-roはstdioモードで実行されます。これは、標準入出力を介して通信するエディタや他のツールとの統合に適しています。

mcp-kubernetes-ro

Server-Sent Events (SSE) モード

あるいは、mcp-kubernetes-roをSSEサポート付きのHTTPサーバーとして実行することもできます。これはウェブベースの統合に適しています。

mcp-kubernetes-ro --transport=sse --port=8080

SSEモードでは、サーバーは指定されたポート（デフォルト：8080）でリッスンし、Server-Sent Eventsを使用してHTTP経由で同じMCPツールを提供します。これは、stdio通信が実用的でないウェブアプリケーションや環境で役立ちます。

構成オプション

MCPサーバーを構成するために、以下のコマンドラインフラグが利用可能です。

Kubernetes構成

• --kubeconfig=PATH：kubeconfigファイルのパス（デフォルトはKUBECONFIG環境変数、次に~/.kube/config）
• --namespace=NAME：操作のデフォルトの名前空間（デフォルトは現在の名前空間）

トランスポートオプション

• --transport=TYPE：トランスポートタイプ：stdioまたはsse（デフォルト：stdio）
• --port=PORT：SSEサーバーのポート（デフォルト：8080、--transport=sseでのみ使用）

ツール管理

• --disabled-tools=NAMES：無効にするツール名のカンマ区切りリスト（オプション）
• MCP_KUBERNETES_RO_DISABLED_TOOLS：無効にするツールのアプリ固有の環境変数（コマンドラインフラグが優先されます）
• DISABLED_TOOLS：無効にするツールの汎用の環境変数（MCP_KUBERNETES_RO_DISABLED_TOOLSよりも優先順位が低い）

コンテキスト構成

サーバーはコマンドごとのコンテキストをサポートしています。これにより、同じ$KUBECONFIGファイル内の複数のKubernetesクラスタまたはコンテキストで作業する際により柔軟性が高まります。

構成の優先順位：

1. コマンドレベルのコンテキスト：個々のツール呼び出しでcontextパラメーターを使用する
2. Kubeconfigのデフォルト：kubeconfigファイルで指定された現在のコンテキストを使用する

Kubeconfigの解決優先順位：

1. コマンドラインフラグ：--kubeconfigパラメーター
2. 環境変数：KUBECONFIG環境変数
3. デフォルトのパス：~/.kube/config
4. クラスタ内の構成：Kubernetesポッド内で実行されている場合の自動検出

例：

{
  "resource_type": "pods",
  "namespace": "default",
  "context": "production-cluster"
}

このアプローチにより、以下のことが可能になります。

• 同じセッション内の異なる操作に異なるコンテキストを使用する
• サーバーを再起動することなくコマンドごとにコンテキストを切り替える
• 既存のkubeconfig設定との互換性を維持する

ツールの使用ドキュメント

リソースのリスト表示

任意のKubernetesリソースをタイプ別にリスト表示し、オプションのフィルタリングが可能で、最新のものから順に並べられます。

引数：

• resource_type（必須）：リスト表示するリソースのタイプ - 複数形を使用します（例：'pods'、 'deployments'、 'services'）
• api_version（オプション）：リソースのAPIバージョン（例：'v1'、'apps/v1'）
• namespace（オプション）：ターゲットの名前空間（クラスタスコープのリソースの場合は空にします）
• context（オプション）：使用するKubernetesコンテキスト（デフォルトはkubeconfigからの現在のコンテキスト）
• label_selector（オプション）：リソースをフィルタリングするためのラベルセレクター（例：'app=nginx,version=1.0'）
• field_selector（オプション）：リソースをフィルタリングするためのフィールドセレクター（例：'status.phase=Running'）
• limit（オプション）：返すリソースの最大数（デフォルトはすべて）
• continue（オプション）：ページネーションのための続きトークン（前のレスポンスから）

例：

{
  "resource_type": "pods",
  "namespace": "default",
  "context": "production",
  "label_selector": "app=nginx"
}

リソースの詳細取得

特定のリソースの詳細を完全な構成とともに取得します。

引数：

• resource_type（必須）：取得するリソースのタイプ
• name（必須）：リソースの名前
• api_version（オプション）：リソースのAPIバージョン（例：'v1'、 'apps/v1'）
• namespace（オプション）：ターゲットの名前空間（名前空間付きのリソースの場合は必須）
• context（オプション）：使用するKubernetesコンテキスト（デフォルトはkubeconfigからの現在のコンテキスト）

例：

{
  "resource_type": "deployment",
  "name": "nginx-deployment",
  "namespace": "default",
  "context": "production"
}

ポッドログの取得

高度なフィルタリングオプション（grepパターン、時間フィルタリング、および前のログ）を使用してポッドログを取得します。

引数：

• namespace（必須）：ポッドの名前空間
• name（必須）：ポッドの名前
• container（オプション）：コンテナの名前（マルチコンテナポッドの場合は必須）
• context（オプション）：使用するKubernetesコンテキスト（デフォルトはkubeconfigからの現在のコンテキスト）
• max_lines（オプション）：取得する最大行数
• grep_include（オプション）：これらのパターンに一致する行のみを含めます（カンマ区切り）。grepのように動作し、これらのパターンのいずれかを含む行を含めます。
• grep_exclude（オプション）：これらのパターンに一致する行を除外します（カンマ区切り）。grep -vのように動作し、これらのパターンのいずれかを含む行を除外します。
• use_regex（オプション）：grepパターンをリテラル文字列ではなく正規表現として扱うかどうか
• since（オプション）：この時間以降のログを返します。"5m"、 "1h"、 "2h30m"、 "1d"のような期間または"2023-01-01T10:00:00Z"のような絶対時間をサポートします。
• previous（オプション）：前に終了したコンテナインスタンスからのログを返します（kubectl logs --previousのように）

例：

{
  "namespace": "default",
  "name": "nginx-pod-12345",
  "container": "nginx",
  "context": "production",
  "max_lines": "100",
  "grep_include": "error,warning",
  "since": "5m"
}

ポッド内のコンテナのリスト表示

ポッド内のコンテナをリスト表示し、ログにアクセスします。

引数：

• namespace（必須）：ポッドの名前空間
• name（必須）：ポッドの名前
• context（オプション）：使用するKubernetesコンテキスト（デフォルトはkubeconfigからの現在のコンテキスト）

例：

{
  "namespace": "default",
  "name": "nginx-pod-12345",
  "context": "production"
}

APIリソースのリスト表示

利用可能なKubernetes APIリソースとその詳細をリスト表示します（kubectl api-resourcesと同様）。

引数：

• なし

例：

{}

コンテキストのリスト表示

kubeconfigファイルから利用可能なKubernetesコンテキストをリスト表示します。これは、他のツールでcontextパラメーターを使用するために利用可能なコンテキストを発見するのに役立ちます。

引数：

• なし

例：

{}

例のレスポンス：

{
  "contexts": [
    {
      "name": "production",
      "cluster": "prod-cluster",
      "user": "prod-user",
      "namespace": "default",
      "current": true
    },
    {
      "name": "staging",
      "cluster": "staging-cluster",
      "user": "staging-user",
      "namespace": "staging",
      "current": false
    }
  ],
  "count": 2
}

ノードメトリクスの取得

メトリクスサーバーからノードのメトリクス（CPUとメモリ使用率）を取得します。結果はタイムスタンプでソートされ（最新のものから順）、一貫した順序とページネーションが可能です。組み込みのメトリクスサーバーエンドポイントはニードルベースのページネーションをサポートしていないためです。

引数：

• node_name（オプション）：メトリクスを取得する特定のノード名。指定しない場合は、すべてのノードのメトリクスを返します。
• context（オプション）：使用するKubernetesコンテキスト（デフォルトはkubeconfigからの現在のコンテキスト）
• limit（オプション）：返すノードメトリクスの最大数。指定しない場合は、利用可能なすべてのメトリクスを返します。
• continue（オプション）：ページネーションのための続きトークン（前のレスポンスから）。

エラー処理：

• メトリクスサーバーが利用できない場合は、エラーメッセージを返します。
• 一般的なメトリクスサーバーのエラーを検出し、具体的なガイダンスを提供します。

例：

{
  "node_name": "worker-node-1",
  "context": "production",
  "limit": 5
}

例のレスポンス（単一ノード）：

{
  "kind": "NodeMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {
    "name": "worker-node-1",
    "creationTimestamp": "2023-01-01T12:00:00Z"
  },
  "timestamp": "2023-01-01T12:00:00Z",
  "window": "10.062s",
  "usage": {
    "cpu": "137m",
    "memory": "1368128Ki"
  }
}

例のレスポンス（ページネーション付きのリスト）：

{
  "kind": "NodeMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "count": 5,
  "items": [
    {
      "kind": "NodeMetrics",
      "metadata": { "name": "node-1" },
      "timestamp": "2023-01-01T12:00:00Z",
      "usage": { "cpu": "137m", "memory": "1368128Ki" }
    }
  ],
  "continue": "eyJvZmZzZXQiOjUsInR5cGUiOiJub2RlIiwibmFtZXNwYWNlIjoiIn0="
}

ポッドメトリクスの取得

メトリクスサーバーからポッドのメトリクス（CPUとメモリ使用率）を取得します。結果はタイムスタンプでソートされ（最新のものから順）、一貫した順序とページネーションが可能です。組み込みのメトリクスサーバーエンドポイントはニードルベースのページネーションをサポートしていないためです。

引数：

• namespace（オプション）：ポッドメトリクスを取得する名前空間。指定しない場合は、すべての名前空間のすべてのポッドのメトリクスを返します。
• pod_name（オプション）：メトリクスを取得する特定のポッド名。指定する場合はnamespaceが必要です。
• context（オプション）：使用するKubernetesコンテキスト（デフォルトはkubeconfigからの現在のコンテキスト）
• limit（オプション）：返すポッドメトリクスの最大数。指定しない場合は、利用可能なすべてのメトリクスを返します。
• continue（オプション）：ページネーションのための続きトークン（前のレスポンスから）。

エラー処理：

• メトリクスサーバーが利用できない場合は、エラーメッセージを返します。
• 一般的なメトリクスサーバーのエラーを検出し、具体的なガイダンスを提供します。
• pod_nameが指定された場合にnamespaceが提供されていることを検証します。

ページネーションの注意事項：

• 続きトークンはコンテキストを認識しており、名前空間のコンテキストが変更されるとリセットされます。
• 一貫した順序とフィルタリングのためにクライアント側のページネーションが実装されています。

例（特定のポッド）：

{
  "namespace": "kube-system",
  "pod_name": "metrics-server-557ff575fb-9dcl4",
  "context": "production"
}

例（ページネーション付き）：

{
  "namespace": "kube-system",
  "context": "production",
  "limit": 10,
  "continue": "eyJvZmZzZXQiOjEwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ=="
}

例のレスポンス（単一ポッド）：

{
  "kind": "PodMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {
    "name": "metrics-server-557ff575fb-9dcl4",
    "namespace": "kube-system",
    "creationTimestamp": "2023-01-01T12:00:00Z"
  },
  "timestamp": "2023-01-01T12:00:00Z",
  "window": "18.888s",
  "containers": [
    {
      "name": "metrics-server",
      "usage": {
        "cpu": "8020419n",
        "memory": "48164Ki"
      }
    }
  ]
}

例のレスポンス（ページネーション付きのリスト）：

{
  "kind": "PodMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "namespace": "kube-system",
  "count": 10,
  "items": [
    {
      "kind": "PodMetrics",
      "metadata": { "name": "pod-1", "namespace": "kube-system" },
      "timestamp": "2023-01-01T12:00:00Z",
      "containers": [
        {
          "name": "container-1",
          "usage": { "cpu": "8020419n", "memory": "48164Ki" }
        }
      ]
    }
  ],
  "continue": "eyJvZmZzZXQiOjIwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ=="
}

Base64エンコード

テキストデータをBase64形式にエンコードします。

引数：

• data（必須）：エンコードするテキストデータ

例：

{
  "data": "username:password"
}

Base64デコード

Base64データをテキスト形式にデコードします。

引数：

• data（必須）：デコードするBase64データ

例：

{
  "data": "dXNlcm5hbWU6cGFzc3dvcmQ="
}

ユースケース

クラスタのトラブルシューティング

• 名前空間全体で失敗しているポッドをリスト表示する
• 詳細なリソース構成を取得する
• デバッグのためにポッドログを取得する
• 利用可能なAPIリソースを探索する

リソースの探索

• タイプ別にクラスタのリソースを探索する
• 特定のラベルを持つリソースを見つける
• リソースの関係を理解する
• リソースの構成を特定する

セキュリティとコンプライアンス

• 読み取り専用アクセスにより、誤った変更を防止する
• 変更のリスクなしに構成を検査する
• リソースの状態と設定を監査する
• 本番クラスタを安全に探索する

AIによるオペレーション支援

• AIアシスタントにクラスタの問題を診断してもらう
• リソースの問題に対するインテリジェントな提案を得る
• 自動化されたログ分析とパターン認識
• Kubernetesリソースに対する自然言語クエリ

AIアシスタントに関する考慮事項

このMCPサーバーはKubernetesクラスタの検査に包括的なツールを提供しますが、一部のAIアシスタントは、技術的に利用可能であっても、特定のツールの組み合わせを使用できない場合があります。

潜在的な制限

• シークレットへのアクセス：一部のAIアシスタントは、資格情報の取り扱いに関するセキュリティポリシーのため、提供されたget_resourceおよびdecode_base64ツールを使用しても、Kubernetesのシークレットを取得、デコード、または表示しない場合があります。
• 機密データ：AIモデルは、ユーザーのアクセス許可やツールの可用性に関係なく、チャットインターフェースで機密情報を公開することを禁止する組み込みの制限を持っている場合があります。
• セキュリティパターン：特定のAIアシスタントは、技術的な機能よりもセキュリティのベストプラクティスを優先し、機密データを公開する可能性のある操作を拒否する場合があります。

回避策

AIアシスタントがセキュリティ上の理由で利用可能なツールを使用しない場合：

1. 直接のCLIアクセス：機密操作には直接kubectlを使用し、AIに実行するコマンドを提案してもらいます。例えば：

   kubectl get secret <secret-name> -n <namespace> -o yaml
   echo "<base64-data>" | base64 -d
   

2. 手動でのツール使用：MCPサーバーをプログラムで使用する場合は、AIアシスタントを介さずにツールを直接呼び出します。
3. ドキュメント：セキュリティ上の影響を考慮してください。AIの拒否は、誤った資格情報の公開を防ぐためのものかもしれません。

設計哲学

この動作は、セキュリティに対する異なるアプローチを反映しています。

• ツールベース：ツールとアクセス許可があれば、それを使用できるはずです。
• AIセーフティ：技術的な機能よりも誤った公開を防止することを優先します。

両方の視点は有効であり、機密データの取得を伴うワークフローを設計する際にはこの制限を考慮する必要があります。

起動時の接続性チェック

MCPサーバーは起動時に自動的に接続性チェックを実行し、Kubernetesクラスタに正常に接続できることを検証します。このチェックには以下が含まれます。

1. APIサーバーの到達可能性：Kubernetes APIサーバーにアクセス可能で応答していることを検証します。
2. 認証：資格情報が有効でクラスタに受け入れられることを確認します。
3. APIの探索：サーバーが利用可能なAPIリソースを探索できることをテストします。
4. 基本的なアクセス許可：少なくとも名前空間に対する読み取りアクセス権があることを検証します（基本的なRBACチェック）。

確認事項

起動に成功すると、以下のような出力が表示されます。

Testing connectivity to Kubernetes cluster...
✓ Successfully connected to Kubernetes cluster (version: v1.28.0, 4 namespaces accessible)

接続性問題のトラブルシューティング

接続性チェックが失敗した場合、詳細なエラーメッセージが表示されます。一般的な問題には以下が含まれます。

• 無効なkubeconfig：kubeconfigファイルが存在し、適切にフォーマットされていることを確認してください。
• クラスタに到達できない：クラスタのエンドポイントがネットワークからアクセス可能であることを確認してください。
• 認証に失敗した：資格情報が期限切れでなく、有効であることを確認してください。
• アクセス許可が不十分：少なくとも基本的なクラスタリソースに対する読み取りアクセス権があることを確認してください。

接続性チェックには30秒のタイムアウトが設定されており、応答しないクラスタでのハングを防止します。

セキュリティに関する考慮事項

• 読み取り専用アクセス：サーバーは読み取り操作（get、list、watch）のみをサポートしています。
• ローカル認証：既存のkubectl設定と資格情報を使用します。
• 破壊的な操作はない：リソースの作成、更新、または削除はできません。
• 名前空間の分離：kubeconfigのRBACアクセス許可を尊重します。
• セキュアな通信：標準入出力とHTTPSベースのSSE通信の両方をサポートしています。

🔧 技術詳細

メトリクスの実装詳細

エラー検出と処理

メトリクスツール（get_node_metricsとget_pod_metrics）には、メトリクスサーバーの可用性に関する高度なエラー検出機能が含まれています。

• 自動検出：メトリクスサーバーがインストールされていないか、応答していないことを検出します。
• 有益なエラーメッセージ：メトリクスサーバーが欠落している場合には、具体的なインストールコマンドを提供します。
• 一般的なエラーパターン：様々なメトリクスサーバーのエラーシナリオを認識します。
  • metrics-serverサービスが見つからない
  • metrics.k8s.ioAPIグループが利用できない
  • "server could not find the requested resource"エラー
  • "no metrics available"状態

ページネーションの実装

両方のメトリクスツールは、一貫した結果を得るためにクライアント側のページネーションを実装しています。組み込みのメトリクスサーバーエンドポイントはニードルベースのページネーションをサポートしていないため、AIツールが必要なデータのみを要求する安全な方法を提供します。特に小さなコンテキストウィンドウで役立ちます。

• ソート：すべての結果はページネーションの前にタイムスタンプでソートされます（最新のものから順）。
• 続きトークン：Base64エンコードされたJSONトークンには以下が含まれます。
  • offset：結果セット内の現在の位置
  • type：リソースのタイプ（"node"または"pod"）
  • namespace：コンテキストの名前空間（ポッドメトリクスの場合）
• コンテキスト認識：名前空間のコンテキストが変更されると、ページネーションの状態がリセットされます。
• トークン形式：eyJvZmZzZXQiOjEwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ==

リソースの取得戦略

• 取得後にフィルタリング：常にサーバーから利用可能なすべてのメトリクスを取得し、その後クライアント側でフィルタリングとページネーションを適用します。
• 一貫した順序：ページネーションされたリクエスト間で予測可能な結果を保証します。
• 名前空間のスコープ：指定された場合、ポッドメトリクスを特定の名前空間に自動的にスコープ指定します。

エラー処理

サーバーは一般的な問題に対する詳細なエラーメッセージを提供します。

• 無効なリソースタイプまたはAPIバージョン
• 必須パラメーターが欠落している
• RBACアクセス許可エラー
• ネットワーク接続性の問題
• 不正なkubeconfigファイル
• メトリクスサーバーが利用できない（インストールガイダンス付き）

制限事項

• ローカルのkubectl設定が必要です。
• 読み取り専用アクセスのみ（書き込み操作はできません）。
• kubeconfigの資格情報でアクセス可能なリソースに制限されます。
• ログのリアルタイムストリーミングはサポートされていません（静的な取得のみ）。
• APIリソースを超えたカスタムリソース定義の探索はサポートされていません。