Lumino

LUMINO MCP サーバー

Kubernetes、OpenShift、Tekton 環境全体にわたって、インテリジェントなオブザーバビリティ、予測分析、AI 駆動の自動化を SRE に提供するオープンソースの MCP（Model Context Protocol）サーバーです。

目次

• 概要
• 機能
• クイックスタート
• チーム向けオンボーディングガイド
• 前提条件
• インストール
• 使用例
• 設定
• ML モデルの永続化
• KubeArchive との統合
• Prometheus/Thanos との統合
• 利用可能なツール
• アーキテクチャ
• 仕組み
• MCP クライアントとの統合
• パフォーマンスに関する考慮事項
• トラブルシューティング
• 依存関係
• コントリビューション
• セキュリティ
• ライセンス
• 謝辞

チーム向けオンボーディングガイド

SPRE MCP 診断スタック（Lumino、PagerDuty、Slack、DevLake、ngit-memory、GitHub、GitLab、Konflux Portal、Sumo Logic、Jira）を初めて利用する方は、こちらから始めてください。

• docs/ONBOARDING_GUIDE.md — セットアップ、最初の診断、トラブルシューティング、3 つの詳細な実例、想定されるツール出力

概要

LUMINO MCP Server は、サイト信頼性エンジニア（SRE）や DevOps チームが Kubernetes クラスターと連携する方法を変革します。Model Context Protocol を通じて 39 個の専用ツールを提供することで、AI アシスタントは次のことを実行できます。

• 監視 — クラスターの健全性、リソース、パイプラインの状態をリアルタイムで監視します
• 分析 — 統計手法や ML 手法を用いて、ログ、イベント、異常を分析します
• トラブルシューティング — 自動化された根本原因分析で、失敗したパイプラインの問題を調査します
• 予測 — リソースのボトルネックや潜在的な問題が発生する前に予測します
• シミュレーション — デプロイ前に設定変更による影響を評価します

機能

Kubernetes と OpenShift の運用

• Namespace と Pod の管理
• 柔軟な出力形式でのリソース検索
• クラスター全体でのラベルベースのリソース検索
• OpenShift Operator と MachineConfigPool の状態確認
• etcd ログ分析

Tekton パイプラインインテリジェンス

• Namespace 全体にわたる Pipeline と TaskRun の監視
• オプションのクリーニング機能を備えた詳細なログ取得
• 失敗したパイプラインの根本原因分析
• クラスターをまたいだパイプラインのトレース
• CI/CD パフォーマンスのベースライン設定

高度なログ分析

• 詳細度を設定できるスマートなログ要約
• 大量のログに対するストリーミング分析
• 複数の戦略を組み合わせたハイブリッド分析
• NLP 手法を用いたセマンティック検索
• 重大度分類を伴う異常検出

予測型・プロアクティブな監視

• z スコア分析による統計的な異常検出
• 早期警告のための予測ログ分析
• リソースボトルネックの予測
• 有効期限アラートを備えた証明書の健全性監視
• TLS 証明書の問題調査

イベントインテリジェンス

• 複数の戦略を用いたスマートなイベント取得
• 概要から詳細調査へと進む段階的なイベント分析
• ML によるパターン検出を用いた高度な分析
• ログとイベントの相関分析

シミュレーションと What-If 分析

• 設定変更に対するモンテカルロシミュレーション
• デプロイ前の影響分析
• 許容範囲を設定できるリスク評価
• 影響を受けるコンポーネントの特定

クイックスタート

2 分以内に LUMINO を使い始めましょう。

Claude Code CLI ユーザー向け（最も簡単）

次のプロンプトを貼り付けて、Lumino MCP サーバーのセットアップを Claude Code に依頼するだけです。

Provision the Lumino MCP server as a project-local MCP integration:

1. Clone the repository:
   git clone https://github.com/spre-sre/lumino-mcp-server.git

2. Install Python dependencies using uv:
   cd lumino-mcp-server && uv sync

3. Create .mcp.json in the current project root (NOT inside lumino-mcp-server) with this configuration.
   IMPORTANT: Replace <ABSOLUTE_PATH_TO_LUMINO> with the actual absolute path to the cloned lumino-mcp-server directory:

   {
     "mcpServers": {
       "lumino": {
         "type": "stdio",
         "command": "<ABSOLUTE_PATH_TO_LUMINO>/.venv/bin/python",
         "args": ["<ABSOLUTE_PATH_TO_LUMINO>/main.py"],
         "env": {
           "PYTHONUNBUFFERED": "1"
         }
       }
     }
   }

4. After creating .mcp.json, inform the user to:
   - Exit Claude Code completely
   - Connect to their Kubernetes or OpenShift cluster (kubectl/oc login)
   - Restart Claude Code in this project directory
   - They will see a prompt to approve the Lumino MCP server
   - Once approved, Lumino tools will be available (check with /mcp command)

その他の MCP クライアント向け

お好みのインストール方法を選択してください。

• MCPM（推奨）：mcpm install @spre-sre/lumino-mcp-server
• 手動セットアップ：詳細は MCP クライアントの統合 手順をご覧ください。

インストールの確認

インストールが完了したら、簡単なクエリでテストしてください。

"List all namespaces in my Kubernetes cluster"

前提条件

必須

• Python 3.10 以上 - コアランタイム
• MCP クライアント - 以下のいずれか：
  • Claude Desktop
  • Claude Code CLI
  • Gemini CLI
  • Cursor IDE

Kubernetes 機能を使用する場合

• Kubernetes/OpenShift へのアクセス - 読み取り権限を持つ有効な kubeconfig
• RBAC 権限 - ポッド、名前空間、その他のリソースを一覧表示する権限

任意（推奨）

• uv - pip よりも高速な依存関係管理
• MCPM - 最も簡単なインストール方法
• Prometheus - 高度なメトリクスおよび予測機能用

インストール

uv を使用する場合（推奨）

# Clone the repository
git clone https://github.com/spre-sre/lumino-mcp-server.git
cd lumino-mcp-server

# Install dependencies
uv sync

# Run the server
uv run python main.py

pip を使用する場合

# Clone the repository
git clone https://github.com/spre-sre/lumino-mcp-server.git
cd lumino-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Run the server
python main.py

使用方法

ローカルモード（stdio トランスポート）

デフォルトでは、サーバーは stdio トランスポートを使用するローカルモードで実行され、MCP クライアントとの直接統合に適しています。

python main.py

Kubernetes モード（HTTP ストリーミングトランスポート）

Kubernetes 内で実行する場合は、HTTP ストリーミングを有効にするために名前空間の環境変数を設定してください。

export KUBERNETES_NAMESPACE=my-namespace
python main.py

サーバーは環境を自動的に検出し、トランスポートモードを切り替えます。

使用例

🔍 インテリジェントな根本原因分析

自動分析を使用して、複雑な障害を調査、診断します。

"Generate a comprehensive RCA report for the failed pipeline run 'build-api-pr-456' in namespace ci-cd"

"Analyze what caused pod crashes in namespace production over the last 6 hours and correlate with resource events"

"Investigate the TLS certificate issues affecting services in namespace ingress-nginx"

🎯 予測インテリジェンスと予測

問題がシステムに影響を及ぼす前に予測します。

"Predict resource bottlenecks across all production namespaces for the next 48 hours"

"Analyze historical pipeline performance and detect anomalies in build times for the last 30 days"

"Check cluster certificate health and alert me about any certificates expiring in the next 60 days"

"Use predictive log analysis to identify potential failures in namespace monitoring before they occur"

🧪 シミュレーションと仮定分析

本番環境に変更を適用する前に、安全にテストします。

"Simulate the impact of increasing memory limits to 4Gi for all pods in namespace backend-services"

"Run a what-if scenario for scaling deployments to 10 replicas and analyze resource consumption"

"Simulate configuration changes for nginx ingress controller and assess risk to existing traffic"

🗺️ トポロジーと依存関係のマッピング

システムアーキテクチャとコンポーネント間の関係を把握します。

"Generate a live topology map of all services, deployments, and their dependencies in namespace microservices"

"Map the complete dependency graph for the payment-service including all connected resources"

"Show me the topology of components affected by the cert-manager service"

🔬 高度な調査とフォレンジック

多角的な分析で複雑な問題を深く調査します。

"Perform an adaptive namespace investigation for production - analyze logs, events, and resource patterns"

"Create a detailed investigation report for resource constraints and bottlenecks in namespace data-processing"

"Trace pipeline execution for commit SHA abc123def from source to deployment across all namespaces"

"Search logs semantically for 'authentication failures related to expired tokens' across the last 24 hours"

📊 CI/CD パイプラインインテリジェンス

継続的デリバリーパイプラインを最適化し、トラブルシューティングします。

"Establish performance baselines for all Tekton pipelines and flag runs deviating by more than 2 standard deviations"

"Trace the complete pipeline flow for image 'api:v2.5.3' from build to production deployment"

"Analyze failed pipeline runs in namespace tekton-pipelines and identify common failure patterns"

"Compare current pipeline run times against 30-day baseline and highlight performance degradation"

🎨 段階的なイベント分析

概要から詳細調査まで、複数のレベルでイベントを調査します。

"Start with an overview of events in namespace kube-system, then drill down into critical issues"

"Perform advanced event analytics with ML pattern detection for namespace monitoring over the last 12 hours"

"Correlate events with pod logs to identify the root cause of CrashLoopBackOff in namespace applications"

🚀 リアルタイム監視とアラート

クラスターの健全性とパイプラインのステータスを把握します。

"Show me the status of all Tekton pipeline runs cluster-wide and highlight long-running pipelines"

"List all failed TaskRuns in the last hour with error details and recommended actions"

"Monitor OpenShift cluster operators and alert on any degraded components"

"Check MachineConfigPool status and show which nodes are being updated"

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

クラスターのセキュリティと証明書管理を確保します。

"Scan all namespaces for expiring certificates and generate a renewal schedule"

"Investigate TLS certificate issues causing handshake failures in namespace istio-system"

"Audit all secrets and configmaps for sensitive data exposure patterns"

📈 高度な分析と ML によるインサイト

機械学習を活用してパターンを検出します。

"Use streaming log analysis to process large log volumes from namespace data-pipeline with error pattern detection"

"Detect anomalies in log patterns using ML analysis with medium severity threshold for namespace api-gateway"

"Analyze resource utilization trends using Prometheus metrics and forecast capacity needs"

設定

Kubernetes 認証

サーバーは Kubernetes の設定を自動的に検出します。

1. クラスター内設定 - Kubernetes ポッド内で実行する場合
2. ローカル kubeconfig - ローカルで実行する場合（~/.kube/config を使用）

環境変数

変数	説明	デフォルト	使用する場面
KUBERNETES_NAMESPACE	K8s モードの名前空間	-	Kubernetes ポッド内でサーバーを実行する場合
K8S_NAMESPACE	代替の名前空間変数	-	KUBERNETES_NAMESPACE の代わりに使用
PROMETHEUS_URL	メトリクス用の Prometheus サーバー URL	自動検出	カスタム Prometheus エンドポイント、または標準以外のポートを使用する場合
KUBECONFIG	kubeconfig ファイルのパス	~/.kube/config	複数のクラスターを使用する場合、またはカスタムの kubeconfig の場所を指定する場合
LOG_LEVEL	ログの詳細度（DEBUG、INFO、WARNING、ERROR）	INFO	問題のデバッグ、またはログのノイズを減らす場合
MCP_SERVER_LOG_LEVEL	MCP フレームワークのログレベル	INFO	MCP プロトコルの問題をトラブルシューティングする場合
PYTHONUNBUFFERED	Python の出力バッファリングを無効化	-	MCP クライアントでログをリアルタイムに確認するために推奨
KUBEARCHIVE_HOST	明示的に指定する KubeArchive API エンドポイント URL	自動検出	カスタム KubeArchive エンドポイント、または標準以外のデプロイを使用する場合
KUBEARCHIVE_ENABLED	KubeArchive 連携の有効／無効を設定	true	KubeArchive のクエリを完全に無効にするには false に設定
THANOS_URL	Thanos Query エンドポイント URL（メトリクスでは最優先）	自動検出	カスタム Thanos Query エンドポイントを使用する場合。PROMETHEUS_URL より優先されます
PROMETHEUS_TOKEN	Prometheus／Thanos 認証用のベアラートークン	自動検出	自動検出に失敗した場合に明示的な認証トークンを指定
OPENSHIFT_TOKEN	Prometheus／Thanos 用の OpenShift ベアラートークン	自動検出	OpenShift クラスターで PROMETHEUS_TOKEN の代わりに使用
OC_TOKEN	OpenShift CLI トークンのフォールバック	自動検出	Prometheus／Thanos 認証用の最終手段となるトークンのフォールバック

ML モデルの永続化

predictive_log_analyzer ツールは、学習済みの ML モデルと学習データをローカルの ~/.lumino/ に永続化します。これにより、サーバーの再起動後もモデルを再利用でき、過去の障害パターンから段階的に学習できます。

ディレクトリ構成

~/.lumino/
├── models/                     # Trained ML models
│   ├── {model_id}.joblib       # Serialized model (e.g. IsolationForest via joblib)
│   ├── {model_id}.meta.json    # Model metadata (created, last used, performance metrics)
│   └── model_index.json        # Index tracking all models and the current active model
└── training_data/              # Training data store
    └── training_data.db        # SQLite database

モデル ID は predictive_log_v1_YYYYMMDD_HHMMSS の形式です。

学習データベース

SQLite データベース（training_data.db）には、次の 4 つのテーブルがあります。

テーブル	用途
log_samples	特徴量、名前空間、ポッド名、エラー指標、メッセージのエントロピーを抽出した、前処理済みのログサンプル
failure_labels	Kubernetes イベント、失敗した PipelineRuns、異常なポッドのステータスから収集した障害イベント。障害の種類には、oom、crash、image、scheduling、storage、config、health、network、timeout、pipeline_failure、permission、resource_limits、general、pod_failure があります
log_failure_correlations	ログサンプルと障害イベントの時間的近接性に基づく相関関係（30 分の時間枠内での時間差に応じて 0.5～1.0 のスコアを付与）
training_runs	model_id、使用したサンプル数、使用したラベル数、パフォーマンス指標、完了ステータスを記録する学習実行履歴

4 つすべてのテーブルに、マルチクラスター対応のための cluster_id 列が定義されています。現在、書き込み時に値が設定されるのは log_samples と failure_labels のみで、log_failure_correlations と training_runs では NULL のままです。クラスター ID は、アクティブな kubeconfig コンテキスト名（例：api-stone-prod-p02-hjvn-p1-openshiftapps-com:6443）から取得されます。ポッド内で実行されている場合は、in-cluster-{KUBERNETES_SERVICE_HOST} が代わりに使用されます。

古いデータのクリーンアップ

manage_prediction_training_data ツール（アクション cleanup）を使用したプログラムによるクリーンアップ：

• cleanup_old_models(max_age_days=30, keep_min=3) -- 30 日より古いモデルを削除します。ただし、最新の 3 件は常に保持します
• cleanup_old_data(max_age_days=90) -- 90 日より古いログサンプル、障害ラベル、相関データを削除します

手動でのクリーンアップ：

rm -rf ~/.lumino/              # Clear everything (models + training data)
rm -rf ~/.lumino/models/       # Clear just models
rm -rf ~/.lumino/training_data/ # Clear just training data (SQLite DB)

ディスク使用量に関する注意：モデルは時間の経過とともに蓄積されます。デフォルトのクリーンアップでは、作成から 30 日以内のモデルを対象とし、最低 3 件を保持します。トレーニングデータは 90 日間保持されます。ディスク容量を確保するため、manage_prediction_training_data ツールをアクション cleanup で定期的に実行してください。

KubeArchive との統合

KubeArchive は Kubernetes リソースをクラスター外に保存し、過去のリソース状態やログを取得するための REST API を提供します。LUMINO は、ポッド、PipelineRun、TaskRun がライブクラスターからガベージコレクションされた場合のフォールバックとして KubeArchive を使用します。query_kubearchive ツールは、このアーカイブを透過的に照会します。

エンドポイントの自動検出

エンドポイントは 5 段階のチェーンで自動的に検出されます（最初に一致したものを使用）：

1. KUBEARCHIVE_HOST 環境変数（最優先）
2. OpenShift Route：名前が kubearchive-api-server のものを、次の名前空間で検索します：kubearchive、product-kubearchive、default
3. Kubernetes Ingress：同じ名前空間で、名前が kubearchive-api-server のものを検索します
4. Kubernetes Service：名前が kubearchive-api-server のものを検索します（クラスター内 DNS：https://kubearchive-api-server.<namespace>.svc.cluster.local:<port>）
5. kubeconfig に基づく Route の推定 -- API サーバーのドメインから候補 URL を構築し（パターン：https://kubearchive-api-server-{namespace}.apps.{cluster-domain}）、/livez をプローブします

検出結果は起動時にキャッシュされます。接続に失敗するとキャッシュがクリアされ、次のリクエスト時に再度プローブされます。

ローカル開発（ポートフォワーディング）

クラスター外で実行し、クラスター内の Service エンドポイントが検出された場合（手順 4）、LUMINO は自動的に kubectl port-forward を設定します：

kubectl port-forward -n {namespace} svc/kubearchive-api-server {local_port}:{remote_port}

• ポート 8081--8090 を試し、その後システム割り当てポートにフォールバックします
• ポートフォワードプロセスは自動的に開始され、サーバーの終了時に自動的にクリーンアップされます
• kubectl が利用できない場合、LUMINO はユーザー向けに手動で実行する代替コマンドをログに出力します

認証

KubeArchive の認証には、次の優先順位が適用されます：

1. 提供されたトークン（コンストラクターまたは前のセッションから）
2. クラスター内のサービスアカウントトークン（/var/run/secrets/kubernetes.io/serviceaccount/token）
3. 既存の Kubernetes クライアントトークン（サーバー起動時に初期化された API クライアントから抽出）
4. OpenShift oc whoami -t トークン（OpenShift クラスターの場合）
5. 自動作成される短期間有効なサービスアカウントトークン（kubectl create token、有効期間 1 時間、Kubernetes のみ）

リソース管理とクリーンアップ

KubeArchiveEndpointDiscovery クラスは、kubectl port-forward プロセスのサブプロセスを確実にクリーンアップし、リソースリークを防ぎます。

推奨される使用方法：コンテキストマネージャー

確実にクリーンアップするには、with 文を使用します：

from src.helpers.kubearchive_integration import KubeArchiveEndpointDiscovery

with KubeArchiveEndpointDiscovery(k8s_core_api, k8s_custom_api) as discovery:
    endpoint = await discovery.discover_endpoint()
    # Use the endpoint...
    # Port-forward subprocess automatically cleaned up on exit

自動クリーンアップの仕組み

明示的なコンテキスト管理なしで使用した場合、このクラスは 3 つのフォールバッククリーンアップ機構を提供します：

1. atexit ハンドラー — インタープリターの正常終了時にポートフォワードをクリーンアップします
2. シグナルハンドラー（SIGTERM/SIGINT） — 元のハンドラーを呼び出しつつ、終了時に正常にクリーンアップします
3. __del__ ファイナライザー — 最終手段のフォールバックです（実行タイミングは保証されません）

リソースを確実にクリーンアップするには、コンテキストマネージャーを使用する方法が推奨されます。

KubeArchive の設定

KUBEARCHIVE_HOST および KUBEARCHIVE_ENABLED 環境変数については、上記の設定セクションを参照してください。

Prometheus/Thanos の統合

LUMINO は prometheus_query、resource_bottleneck_forecaster、ci_cd_performance_baselining_tool ツール向けに、Prometheus または Thanos Query エンドポイントを自動検出します。Thanos Query は Prometheus HTTP API を実装しており、レプリカ間で統合された重複のないビューを提供するため、利用可能な場合は優先されます。

エンドポイントの検出優先順位

優先度	ソース	エンドポイントの種類
0	THANOS_URL 環境変数	thanos
1	PROMETHEUS_URL 環境変数	prometheus
2	定義済みのクラスターエンドポイント（コード内）	varies
3	5 分間の TTL キャッシュ	cached
4	自動検出チェーン（以下を参照）	detected
5	定義済みのフォールバックエンドポイント	varies

自動検出の順序は、実行環境によって異なります。

• クラスター内：Thanos サービス --> Prometheus サービス --> Prometheus Operator CRD --> OpenShift Routes
• ローカル／クラスター外：OpenShift Routes --> Thanos サービス --> Prometheus Operator CRD --> Prometheus サービス

自動検出の詳細

OpenShift Routes：openshift-monitoring 名前空間を検索します。prometheus-k8s よりも thanos-querier ルートを優先します。名前に prometheus が含まれる任意のルートをフォールバックとして使用します。TLS 終端設定からプロトコルを検出します。

Thanos サービス：openshift-monitoring、monitoring、thanos、observability、kube-prometheus 名前空間を検索します。優先するサービス名は thanos-query-frontend、thanos-querier、thanos-query です。ラベルセレクター app.kubernetes.io/name=thanos-query、app.kubernetes.io/component=query,app.kubernetes.io/name=thanos、app=thanos-query、app=thanos-querier を使った検索も行います。

Prometheus サービス：openshift-monitoring、monitoring、prometheus、kube-prometheus、observability 名前空間を検索します。優先するサービス名は prometheus-server、prometheus-k8s、prometheus です。ラベルセレクター app=prometheus、app.kubernetes.io/name=prometheus、app.kubernetes.io/component=prometheus を使った検索も行います。

Prometheus Operator CRD：monitoring.coreos.com/v1 の Prometheus カスタムリソースと、関連するサービス（同じ名前空間内の prometheus-{name} というパターン）から検出します。

Prometheus/Thanos の認証

Prometheus/Thanos の認証では、次の 5 つの方法を優先順位順に使用します。

1. oc whoami -t -- 新しい OpenShift トークン（OpenShift で最も信頼性が高い方法）
2. kubeconfig ファイルを再読み込みして現在のトークンを取得
3. メモリー内の Kubernetes クライアント設定トークン
4. ServiceAccount トークンファイル（/var/run/secrets/kubernetes.io/serviceaccount/token）
5. 環境変数：PROMETHEUS_TOKEN、OPENSHIFT_TOKEN、OC_TOKEN（記載順に確認）

設定例

{
  "env": {
    "THANOS_URL": "https://thanos-querier.example.com",
    "PROMETHEUS_TOKEN": "your-bearer-token"
  }
}

注：エンドポイントキャッシュの TTL は 5 分です。実行時に THANOS_URL または PROMETHEUS_URL を変更した場合、新しい値は次回のクエリから適用されます。

利用可能なツール

Kubernetes コア（5 個のツール）

ツール	説明
list_namespaces	クラスター内のすべての名前空間を一覧表示します
list_pods_in_namespace	ステータスと配置情報を含めて Pod を一覧表示します
get_kubernetes_resource	柔軟な出力形式で任意の Kubernetes リソースを取得します
search_resources_by_labels	ラベルを指定して、複数の名前空間にまたがるリソースを検索します
query_kubearchive	必要に応じてログを取得しながら、KubeArchive からアーカイブ済みの Kubernetes リソースを検索します

Tekton パイプライン（6 個のツール）

ツール	説明
list_pipelineruns	ステータスと所要時間を含めて PipelineRun を一覧表示します
list_taskruns	TaskRun を一覧表示します。パイプラインによる絞り込みも可能です
get_pipelinerun_logs	必要に応じてクリーンアップしながら、パイプラインログを取得します
list_recent_pipeline_runs	すべての名前空間を対象に、最近のパイプライン実行を一覧表示します
find_pipeline	パターンマッチングでパイプラインを検索します
get_tekton_pipeline_runs_status	クラスター全体のパイプラインステータスの概要を表示します

ログ分析（8 ツール）

ツール	説明
analyze_logs	ログテキストからエラーパターンを抽出
smart_summarize_pod_logs	インテリジェントなログ要約
stream_analyze_pod_logs	大規模なログのストリーミング分析
analyze_pod_logs_hybrid	分析戦略を組み合わせた分析
detect_log_anomalies	重大度レベルに基づく異常検知
semantic_log_search	NLP ベースのセマンティックログ検索
templatize_pod_logs	Drain3 を使用してログを固有の構造テンプレートにクラスタリング（オプションの logan 依存関係が必要）
deep_analyze_pod_logs	ゼロショット ML を使用してログテンプレートをゴールデンシグナルと障害カテゴリに分類（オプションの logan 依存関係が必要）

イベント分析（3 ツール）

ツール	説明
smart_get_namespace_events	戦略に基づくスマートなイベント取得
progressive_event_analysis	マルチレベルのイベント分析
advanced_event_analytics	ML を活用したイベントパターン検知

障害分析と RCA（2 ツール）

ツール	説明
analyze_failed_pipeline	失敗したパイプラインの根本原因分析
automated_triage_rca_report_generator	インシデントレポートの自動生成

リソース監視（4 ツール）

ツール	説明
check_resource_constraints	名前空間内のリソース問題を検知
detect_anomalies	統計的異常検知
prometheus_query	PromQL クエリを実行
resource_bottleneck_forecaster	リソース枯渇を予測

名前空間の調査（2 ツール）

ツール	説明
conservative_namespace_overview	焦点を絞った名前空間の健全性チェック
adaptive_namespace_investigation	クエリに基づく動的な調査

証明書とセキュリティ（2 ツール）

ツール	説明
investigate_tls_certificate_issues	TLS 関連の問題を検出
check_cluster_certificate_health	証明書の有効期限を監視

OpenShift 固有（3 ツール）

ツール	説明
get_machine_config_pool_status	MachineConfigPool のステータスと更新
get_openshift_cluster_operator_status	クラスターオペレーターの健全性
get_etcd_logs	etcd ログの取得と分析

CI/CD パフォーマンス（2 ツール）

ツール	説明
ci_cd_performance_baselining_tool	パイプラインのパフォーマンス基準
pipeline_tracer	コミット、PR、またはイメージごとにパイプラインを追跡

トポロジーと予測（3 ツール）

ツール	説明
live_system_topology_mapper	システムトポロジーをリアルタイムでマッピング
predictive_log_analyzer	ログパターンから問題を予測
manage_prediction_training_data	予測ログアナライザーのトレーニングデータを管理

シミュレーション（1 ツール）

ツール	説明
what_if_scenario_simulator	設定変更をシミュレーション

アーキテクチャ

lumino-mcp-server/
├── main.py                 # Entry point with transport detection
├── src/
│   ├── server-mcp.py       # MCP server with all 39 tools
│   └── helpers/
│       ├── constants.py              # Shared constants
│       ├── event_analysis.py         # Event processing logic
│       ├── failure_analysis.py       # RCA algorithms
│       ├── kubearchive_integration.py # KubeArchive API client & discovery
│       ├── log_analysis.py           # Log processing
│       ├── ml_persistence.py         # ML model & training data storage
│       ├── resource_topology.py      # Topology mapping
│       ├── semantic_search.py        # NLP search
│       └── utils.py                  # Utility functions
└── pyproject.toml          # Project configuration

動作の仕組み

LUMINO は、Model Context Protocol を通じて AI アシスタントと Kubernetes インフラストラクチャの橋渡しをします。

┌─────────────────────────────────────────────────────────────────┐
│                        AI Assistant Layer                        │
│          (Claude Desktop, Claude Code CLI, Gemini CLI)          │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Natural Language Queries
                             │ "Analyze failed pipelines"
                             │ "Predict resource bottlenecks"
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Model Context Protocol                       │
│                      (MCP Communication)                         │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Tool Invocations & Results
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                       LUMINO MCP Server                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │ Log Analysis │  │ Event Intel  │  │  Predictive  │         │
│  │   (6 tools)  │  │  (3 tools)   │  │  (2 tools)   │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │   Pipeline   │  │  Simulation  │  │   Topology   │         │
│  │  (6 tools)   │  │  (1 tool)    │  │  (2 tools)   │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Kubernetes API Calls
                             │ Prometheus Queries
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Kubernetes/OpenShift Cluster                  │
│                                                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │   Pods   │  │ Services │  │ Tekton   │  │etcd/Logs │       │
│  └──────────┘  └──────────┘  │Pipelines │  └──────────┘       │
│  ┌──────────┐  ┌──────────┐  └──────────┘  ┌──────────┐       │
│  │  Events  │  │ Configs  │  ┌──────────┐  │Prometheus│       │
│  └──────────┘  └──────────┘  │OpenShift │  └──────────┘       │
│                               │Operators │                       │
│                               └──────────┘                       │
└─────────────────────────────────────────────────────────────────┘

ワークフロー

1. ユーザークエリ → AI アシスタントが自然言語のリクエストを受け取ります
2. MCP による変換 → アシスタントがクエリを適切なツール呼び出しに変換します
3. LUMINO による処理 → サーバーが Kubernetes／Prometheus の操作を実行します
4. データ分析 → ML／統計アルゴリズムが生データを処理します
5. AI による統合 → アシスタントが結果を人間に読みやすい情報に整えます

主な機能

• ローカル状態を最小限に - クラスターにリアルタイムでクエリを実行します。予測分析用の ML モデルの永続化は ~/.lumino/ で任意に設定できます（ML モデルの永続化を参照）
• トランスポートの自動検出 - stdio（ローカル）モードと HTTP（K8s）モードを切り替えます
• トークン予算の管理 - 大量のログに対応する適応型の戦略を使用します
• インテリジェントなキャッシュ - 頻繁にアクセスされるデータをスマートにキャッシュします
• セキュリティを最優先 - 既存の kubeconfig RBAC 権限を使用し、個別の認証は不要です

MCP クライアントとの連携

方法 1：MCPM を使用する（Claude Code CLI／Gemini CLI に推奨）

Claude Code CLI または Gemini CLI に LUMINO MCP サーバーをインストールする最も簡単な方法は、MCP サーバーのパッケージマネージャーである MCPM を使用することです。

MCPM をインストールする

# Clone and build MCPM
git clone https://github.com/spre-sre/mcpm.git
cd mcpm
go build -o mcpm .

# Optional: Add to PATH
sudo mv mcpm /usr/local/bin/

要件：Go 1.23 以降、Git、Python 3.10 以降、uv（または pip）

LUMINO MCP サーバーをインストールする

# Install from GitHub repository (short syntax)
mcpm install @spre-sre/lumino-mcp-server

# Or use full GitHub URL
mcpm install https://github.com/spre-sre/lumino-mcp-server.git

# For GitLab repositories (if hosted on GitLab)
mcpm install gl:@spre-sre/lumino-mcp-server

# Install for specific client
mcpm install @spre-sre/lumino-mcp-server --claude  # For Claude Code CLI
mcpm install @spre-sre/lumino-mcp-server --gemini  # For Gemini CLI

# Install globally (works with both Claude and Gemini)
mcpm install @spre-sre/lumino-mcp-server --global

短縮構文の説明：

• @owner/repo - GitHub からインストールします（デフォルト：https://github.com/owner/repo.git）
• gl:@owner/repo - GitLab からインストールします（https://gitlab.com/owner/repo.git）
• 完全な URL - 任意の Git リポジトリで使用できます

これにより、次の処理が行われます。

• リポジトリを ~/.mcp/servers/lumino-mcp-server/ にクローンします
• Python プロジェクトを自動検出し、uv（または pip）を使って依存関係をインストールします
• Claude Code CLI または Gemini CLI の設定に自動的に登録します

LUMINO を管理する

# List installed servers
mcpm list

# Update LUMINO
mcpm update lumino-mcp-server

# Remove LUMINO
mcpm remove lumino-mcp-server

---

方法 2：手動で設定する

手動でセットアップする場合や Claude Desktop／Cursor を設定する場合は、クライアントごとのガイドに従ってください。

Claude Desktop

1. 設定ファイルの場所を確認します：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. LUMINO の設定を追加します：

{
  "mcpServers": {
    "lumino": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/lumino-mcp-server",
        "python",
        "main.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

3. Claude Desktop を再起動します

4. インストールを確認します：Claude Desktop でハンマーアイコン（🔨）を探すと、利用可能なツールを確認できます

---

Claude Code CLI

オプション A：MCPM を使用する（上記の方法 1 を参照）

オプション B：Claude Code による自動セットアップ（推奨。最も簡単な方法です）

上記のクイックスタートセクションにあるセットアップ用プロンプトをコピーして、Claude Code に貼り付けます。Claude がリポジトリをクローンし、依存関係をインストールして、プロジェクト用に MCP サーバーを設定します。

オプション C：手動で設定する

1. クローンしてインストールします：

git clone https://github.com/spre-sre/lumino-mcp-server.git
cd lumino-mcp-server
uv sync  # Creates .venv with all dependencies

2. プロジェクトのルートに .mcp.json を作成します（プロジェクトローカルの設定の場合）。または、~/.claude.json を更新します（グローバル設定の場合）。

{
  "mcpServers": {
    "lumino": {
      "type": "stdio",
      "command": "/absolute/path/to/lumino-mcp-server/.venv/bin/python",
      "args": ["/absolute/path/to/lumino-mcp-server/main.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

重要：/absolute/path/to/lumino-mcp-server を、リポジトリをクローンした実際の絶対パスに置き換えてください（例：/Users/username/projects/lumino-mcp-server）。

3. インストールを確認します：

# Check MCP servers
claude mcp list

# Test with a query
claude "List all namespaces in my cluster"

---

Gemini CLI

オプション A：MCPM を使用する（推奨。上記の方法 1 を参照）

オプション B：手動で設定する

1. 設定ファイルの場所を確認します：

   • macOS／Linux：~/.config/gemini/mcp_servers.json
   • Windows：%APPDATA%\gemini\mcp_servers.json

2. LUMINO の設定を追加します：

{
  "mcpServers": {
    "lumino": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/lumino-mcp-server",
        "python",
        "main.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

3. インストールを確認します：

# Check MCP servers
gemini mcp list

# Test with a query
gemini "Show me failed pipeline runs"

---

Cursor IDE

1. Cursor の設定を開きます：

   • Cmd+,（macOS）または Ctrl+,（Windows／Linux）を押します
   • 「MCP」または「Model Context Protocol」を検索します

2. MCP サーバーの設定を追加します：

Cursor の MCP 設定で、次の内容を追加します。

{
  "mcpServers": {
    "lumino": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/lumino-mcp-server",
        "python",
        "main.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

別の方法 - Cursor の settings.json を使用する場合：

1. コマンドパレットを開きます（Cmd+Shift+P または Ctrl+Shift+P）
2. 「Preferences: Open User Settings (JSON)」と入力します
3. MCP の設定を追加します。

{
  "mcp.servers": {
    "lumino": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/lumino-mcp-server",
        "python",
        "main.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

3. Cursor IDE を再起動します

4. インストールを確認します：Cursor の AI チャットを開き、LUMINO のツールが利用可能か確認します

---

設定に関する注意事項

/path/to/lumino-mcp-server を、リポジトリをクローンした実際のパスに置き換えてください：

# Example paths:
# macOS/Linux: /Users/username/projects/lumino-mcp-server
# Windows: C:\Users\username\projects\lumino-mcp-server

# If installed via MCPM:
# ~/.mcp/servers/lumino-mcp-server/

環境変数（任意）：

必要に応じて、これらを env セクションに追加します。

{
  "env": {
    "PYTHONUNBUFFERED": "1",
    "KUBERNETES_NAMESPACE": "default",
    "PROMETHEUS_URL": "http://prometheus:9090",
    "LOG_LEVEL": "INFO"
  }
}

---

代替の Python パッケージマネージャーを使用する

uv の代わりに pip を使用する場合

{
  "command": "python",
  "args": [
    "/path/to/lumino-mcp-server/main.py"
  ]
}

注：先に仮想環境を有効化してください。

cd /path/to/lumino-mcp-server
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

poetry を使用する場合

{
  "command": "poetry",
  "args": [
    "run",
    "python",
    "main.py"
  ],
  "cwd": "/path/to/lumino-mcp-server"
}

---

設定のテスト

いずれかのクライアントを設定したら、接続をテストします。

1. ツールが読み込まれているか確認する：

   • Claude Desktop：🔨 ハンマーアイコンを確認します
   • Claude Code CLI：claude mcp list
   • Gemini CLI：gemini mcp list
   • Cursor：AI チャットで利用可能なツールを確認します

2. 簡単なクエリをテストする：

"List all namespaces in my Kubernetes cluster"

3. サーバーログを確認する（問題が発生した場合）：

# Run server manually to see errors
cd /path/to/lumino-mcp-server
uv run python main.py

期待される出力：

MCP Server running in stdio mode
Available tools: 39
Waiting for requests...

---

高度な設定

複数のクラスター

異なるクラスター向けに複数の LUMINO インスタンスを設定します。

{
  "mcpServers": {
    "lumino-prod": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/lumino-mcp-server", "python", "main.py"],
      "env": {
        "KUBECONFIG": "/path/to/prod-kubeconfig.yaml"
      }
    },
    "lumino-dev": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/lumino-mcp-server", "python", "main.py"],
      "env": {
        "KUBECONFIG": "/path/to/dev-kubeconfig.yaml"
      }
    }
  }
}

カスタムログレベル

{
  "env": {
    "LOG_LEVEL": "DEBUG",
    "MCP_SERVER_LOG_LEVEL": "DEBUG"
  }
}

---

サポートされるトランスポート

サーバーは適切なトランスポートを自動的に検出します。

• stdio - ローカルのデスクトップ統合用（Claude Desktop、Claude Code CLI、Gemini CLI、Cursor）
• streamable-http - Kubernetes デプロイ用（KUBERNETES_NAMESPACE が設定されている場合）

パフォーマンスに関する考慮事項

大規模クラスター向けの最適化

LUMINO は、あらゆる規模のクラスターを効率的に処理できるよう設計されています。

クラスターの規模	推奨事項	ツール戦略
小規模（< 50 個のポッド）	デフォルト設定を使用します	すべてのツールが最適に動作します
中規模（50～500 個のポッド）	名前空間フィルタリングを使用します	自動サンプリング機能を備えた適応型ツールを活用します
大規模（500 個以上のポッド）	時間枠と名前空間を指定します	保守的なツールとストリーミングツールを使用します
非常に大規模（1000 個以上のポッド）	フィルターとページネーションを組み合わせます	対象を絞ったクエリで段階的に分析します

トークン予算の管理

LUMINO は AI コンテキストの制限を自動的に管理します。

• 適応型サンプリング - データ量が多い場合、スマートツールがデータを自動サンプリングします
• 段階的な読み込み - ストリーム分析では、データをチャンク単位で処理します
• トークン予算 - 設定可能な上限により、コンテキストのオーバーフローを防ぎます
• ハイブリッド戦略 - 最適な分析方法を自動的に選択します

クエリ最適化のヒント

名前空間フィルタリングを使用する

✅ "Analyze logs for pods in namespace production"
❌ "Analyze all pod logs in the cluster"

時間枠を指定する

✅ "Show events from the last 2 hours"
❌ "Show all events" (might return thousands)

スマートツールを活用する

✅ "smart_summarize_pod_logs" - Adaptive analysis
❌ Direct log dumps - No processing

段階的な分析を使用する

✅ Start with "overview" → drill down to "detailed"
❌ Jump directly to "deep_dive" on large datasets

パフォーマンス指標

操作	典型的な応答時間	スケーラビリティ
名前空間の一覧表示	< 1s	O(1)
ポッドログの取得（1 個のポッド）	1-3s	O(log size)
パイプライン実行の分析	2-5s	O(task count)
クラスター全体の検索	5-15s	O(namespace count)
ML 異常検出	3-10s	O(data points)
トポロジーマッピング	5-20s	O(resource count)

キャッシュ戦略

LUMINO は、頻繁にアクセスされるデータにインテリジェントキャッシュを使用します。

• 15 分間のキャッシュ - Web から取得したコンテンツ用
• セッションキャッシュ - ハイブリッドログ分析用
• ML モデルの永続化 - 予測モデルとトレーニングデータはローカルの ~/.lumino/ に保存されます（ML Model Persistence を参照）

同時リクエスト

サーバーは複数の同時リクエストを効率的に処理します。

• スレッドセーフな操作 - ツールを安全に並列実行できます
• コネクションプーリング - Kubernetes API 接続を再利用します
• 非同期 HTTP - Prometheus クエリをノンブロッキングで実行します

リソース使用量

サーバーのリソース要件

デプロイ	CPU	メモリ	ディスク
ローカル（stdio）	100-500m	256-512Mi	最小限
Kubernetes	200m-1	512Mi-1Gi	最小限
高負荷	1-2	1-2Gi	最小限

注：LUMINO が必要とするリソースは最小限です。ML モデルとトレーニングデータはローカルの ~/.lumino/ に永続化されます（ML Model Persistence を参照）。処理の大部分は AI アシスタントで行われます。

トラブルシューティング

よくある問題

Kubernetes クラスターが見つかりません

Error: Unable to load kubeconfig

~/.kube/config に有効な kubeconfig があること、またはクラスター内で実行していることを確認してください。

リソースへのアクセスが拒否されました

Error: Forbidden - User cannot list resource

RBAC 権限を確認してください。サーバーには、クエリ対象のリソースへの読み取りアクセス権が必要です。

ツールがタイムアウトします 大規模なクラスターでは、一部のツールがタイムアウトする場合があります。フィルタリングオプション（namespace、ラベル）を使って対象範囲を絞り込んでください。

依存関係

• mcp[cli]>=1.10.1 - Model Context Protocol SDK
• kubernetes>=32.0.1 - Kubernetes Python クライアント
• pandas>=2.0.0 - データ分析
• scikit-learn>=1.6.1 - ML アルゴリズム
• prometheus-client>=0.22.0 - Prometheus 統合
• aiohttp>=3.12.2 - 非同期 HTTP クライアント

コントリビューション

コントリビューションを歓迎します！プルリクエストを送信する前に、コントリビューションガイドをお読みください。

セキュリティ

セキュリティ上の脆弱性については、セキュリティポリシーをご覧ください。

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

謝辞

• FastMCP フレームワークを使用して構築
• 複雑な Kubernetes 環境を管理する SRE チームのニーズに着想を得ています