Lumino MCP Server

🚀 LUMINO MCP 服務器

LUMINO MCP 服務器是一個開源的 MCP（模型上下文協議）服務器，它為站點可靠性工程師（SRE）和 DevOps 團隊提供智能可觀測性、預測分析和 AI 驅動的自動化功能，適用於 Kubernetes、OpenShift 和 Tekton 環境。

🚀 快速開始

對於 Claude Code CLI 用戶（最簡單方式）

只需將以下提示粘貼到 Claude Code 中，讓它為你配置 Lumino MCP 服務器：

將 Lumino MCP 服務器作為項目本地的 MCP 集成進行配置：

1. 克隆倉庫：
   git clone https://github.com/spre-sre/lumino-mcp-server.git

2. 使用 uv 安裝 Python 依賴項：
   cd lumino-mcp-server && uv sync

3. 在當前項目根目錄（而非 lumino-mcp-server 內部）創建 .mcp.json 文件，並使用以下配置。
   重要提示：將 <ABSOLUTE_PATH_TO_LUMINO> 替換為克隆的 lumino-mcp-server 目錄的實際絕對路徑：

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

4. 創建 .mcp.json 文件後，告知用戶：
   - 完全退出 Claude Code
   - 連接到他們的 Kubernetes 或 OpenShift 集群（kubectl/oc login）
   - 在該項目目錄中重新啟動 Claude Code
   - 他們將看到一個批准 Lumino MCP 服務器的提示
   - 批准後，Lumino 工具將可用（使用 /mcp 命令進行檢查）

對於其他 MCP 客戶端

選擇你喜歡的安裝方法：

• MCPM（推薦）：mcpm install @spre-sre/lumino-mcp-server
• 手動設置：請參閱詳細的 MCP 客戶端集成 說明

驗證安裝

安裝完成後，使用以下簡單查詢進行測試：

"列出我的 Kubernetes 集群中的所有命名空間"

✨ 主要特性

Kubernetes 與 OpenShift 操作

• 命名空間和 Pod 管理
• 靈活輸出格式的資源查詢
• 跨集群基於標籤的資源搜索
• OpenShift 操作符和 MachineConfigPool 狀態查詢
• etcd 日誌分析

Tekton 管道智能

• 跨命名空間的管道和任務運行監控
• 可選清理的詳細日誌檢索
• 失敗管道的根本原因分析
• 跨集群管道跟蹤
• CI/CD 性能基線設定

高級日誌分析

• 可配置詳細級別的智能日誌摘要
• 大日誌量的流式分析
• 多種策略結合的混合分析
• 使用 NLP 技術的語義搜索
• 帶嚴重程度分類的異常檢測

預測性和主動監控

• 使用 z 分數分析的統計異常檢測
• 用於早期預警的預測性日誌分析
• 資源瓶頸預測
• 帶過期警報的證書健康監控
• TLS 證書問題調查

事件智能

• 多種策略的智能事件檢索
• 漸進式事件分析（從概述到深入分析）
• 基於機器學習模式檢測的高級分析
• 日誌與事件關聯

模擬和假設分析

• 配置更改的蒙特卡羅模擬
• 部署前的影響分析
• 可配置容差的風險評估
• 受影響組件識別

📦 安裝指南

使用 uv（推薦）

# 克隆倉庫
git clone https://github.com/spre-sre/lumino-mcp-server.git
cd lumino-mcp-server

# 安裝依賴項
uv sync

# 運行服務器
uv run python main.py

使用 pip

# 克隆倉庫
git clone https://github.com/spre-sre/lumino-mcp-server.git
cd lumino-mcp-server

# 創建虛擬環境
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 安裝依賴項
pip install -e .

# 運行服務器
python main.py

💻 使用示例

🔍 智能根本原因分析

使用自動化分析來調查和診斷複雜故障：

"為命名空間 ci-cd 中失敗的管道運行 'build-api-pr-456' 生成全面的根本原因分析報告"

"分析過去 6 小時內生產命名空間中 Pod 崩潰的原因，並將其與資源事件關聯起來"

"調查影響 ingress-nginx 命名空間中服務的 TLS 證書問題"

🎯 預測智能與預測

在問題影響系統之前預測問題：

"預測未來 48 小時內所有生產命名空間的資源瓶頸"

"分析歷史管道性能，並檢測過去 30 天內構建時間的異常"

"檢查集群證書健康狀況，並提醒我未來 60 天內即將過期的證書"

"使用預測性日誌分析識別監控命名空間中潛在的故障"

🧪 模擬和假設分析

在將更改應用到生產環境之前安全地測試更改：

"模擬將後端服務命名空間中所有 Pod 的內存限制增加到 4Gi 的影響"

"運行將部署擴展到 10 個副本的假設場景，並分析資源消耗"

"模擬 nginx 入口控制器的配置更改，並評估對現有流量的風險"

🗺️ 拓撲和依賴映射

瞭解系統架構和組件關係：

"生成微服務命名空間中所有服務、部署及其依賴項的即時拓撲圖"

"映射支付服務的完整依賴圖，包括所有連接的資源"

"顯示受 cert-manager 服務影響的組件拓撲"

🔬 高級調查和取證

通過多方面分析深入研究複雜問題：

"對生產命名空間進行自適應調查 - 分析日誌、事件和資源模式"

"為數據處理命名空間中的資源約束和瓶頸創建詳細的調查報告"

"跟蹤提交 SHA abc123def 從源代碼到跨所有命名空間部署的管道執行過程"

"在過去 24 小時內語義搜索 '與過期令牌相關的身份驗證失敗'"

📊 CI/CD 管道智能

優化和排除持續交付管道的故障：

"為所有 Tekton 管道建立性能基線，並標記偏差超過 2 個標準差的運行"

"跟蹤圖像 'api:v2.5.3' 從構建到生產部署的完整管道流程"

"分析 tekton-pipelines 命名空間中失敗的管道運行，並識別常見的失敗模式"

"將當前管道運行時間與 30 天基線進行比較，並突出顯示性能下降"

🎨 漸進式事件分析

從概述到深入分析的多級事件調查：

"從 kube-system 命名空間的事件概述開始，然後深入研究關鍵問題"

"對過去 12 小時內監控命名空間的事件進行基於機器學習模式檢測的高級分析"

"將事件與 Pod 日誌關聯起來，以確定應用程序命名空間中 CrashLoopBackOff 的根本原因"

🚀 即時監控和警報

隨時瞭解集群健康狀況和管道狀態：

"顯示集群範圍內所有 Tekton 管道運行的狀態，並突出顯示長時間運行的管道"

"列出過去一小時內所有失敗的任務運行，並提供錯誤詳細信息和建議操作"

"監控 OpenShift 集群操作符，並在任何組件降級時發出警報"

"檢查 MachineConfigPool 狀態，並顯示正在更新的節點"

🔐 安全與合規

確保集群安全和證書管理：

"掃描所有命名空間以查找即將過期的證書，並生成續訂計劃"

"調查導致 istio-system 命名空間中握手失敗的 TLS 證書問題"

"審核所有秘密和配置映射，以查找敏感數據暴露模式"

📈 高級分析和機器學習洞察

利用機器學習進行模式檢測：

"使用流式日誌分析處理數據管道命名空間中的大日誌量，並檢測錯誤模式"

"使用機器學習分析檢測 API 網關命名空間中日誌模式的異常，設置中等嚴重程度閾值"

"使用 Prometheus 指標分析資源利用率趨勢，並預測容量需求"

📚 詳細文檔

配置

Kubernetes 認證

服務器會自動檢測 Kubernetes 配置：

1. 集群內配置 - 當在 Kubernetes Pod 內運行時
2. 本地 kubeconfig - 當在本地運行時（使用 ~/.kube/config）

環境變量

變量	描述	默認值	使用場景
KUBERNETES_NAMESPACE	K8s 模式下的命名空間	-	當服務器在 Kubernetes Pod 內運行時
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 客戶端使用以查看即時日誌

可用工具

Kubernetes 核心（4 個工具）

工具	描述
list_namespaces	列出集群中的所有命名空間
list_pods_in_namespace	列出帶有狀態和位置信息的 Pod
get_kubernetes_resource	獲取任何 Kubernetes 資源，輸出格式靈活
search_resources_by_labels	通過標籤跨命名空間搜索資源

Tekton 管道（6 個工具）

工具	描述
list_pipelineruns	列出帶有狀態和時間信息的 PipelineRuns
list_taskruns	列出 TaskRuns，可根據管道進行過濾
get_pipelinerun_logs	檢索管道日誌，可選擇清理
list_recent_pipeline_runs	所有命名空間中的最近管道
find_pipeline	通過模式匹配查找管道
get_tekton_pipeline_runs_status	集群範圍內的管道狀態摘要

日誌分析（6 個工具）

工具	描述
analyze_logs	從日誌文本中提取錯誤模式
smart_summarize_pod_logs	智能日誌摘要
stream_analyze_pod_logs	大日誌的流式分析
analyze_pod_logs_hybrid	組合分析策略
detect_log_anomalies	帶嚴重程度級別的異常檢測
semantic_log_search	基於 NLP 的語義日誌搜索

事件分析（3 個工具）

工具	描述
smart_get_namespace_events	使用策略進行智能事件檢索
progressive_event_analysis	多級事件分析
advanced_event_analytics	基於機器學習的事件模式檢測

故障分析與根本原因分析（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 或圖像跟蹤管道

拓撲與預測（2 個工具）

工具	描述
live_system_topology_mapper	即時系統拓撲映射
predictive_log_analyzer	從日誌模式中預測問題

模擬（1 個工具）

工具	描述
what_if_scenario_simulator	模擬配置更改

架構

lumino-mcp-server/
├── main.py                 # 入口點，帶有傳輸檢測
├── src/
│   ├── server-mcp.py       # 包含所有 37 個工具的 MCP 服務器
│   └── helpers/
│       ├── constants.py    # 共享常量
│       ├── event_analysis.py    # 事件處理邏輯
│       ├── failure_analysis.py  # 根本原因分析算法
│       ├── log_analysis.py      # 日誌處理
│       ├── resource_topology.py # 拓撲映射
│       ├── semantic_search.py   # NLP 搜索
│       └── utils.py             # 實用函數
└── pyproject.toml          # 項目配置

工作原理

LUMINO 通過模型上下文協議在 AI 助手和你的 Kubernetes 基礎設施之間架起橋樑：

┌─────────────────────────────────────────────────────────────────┐
│                        AI 助手層                        │
│          (Claude Desktop, Claude Code CLI, Gemini CLI)          │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ 自然語言查詢
                             │ "分析失敗的管道"
                             │ "預測資源瓶頸"
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                     模型上下文協議                       │
│                      (MCP 通信)                         │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ 工具調用與結果
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                       LUMINO MCP 服務器                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │ 日誌分析 │  │ 事件智能  │  │ 預測性  │         │
│  │   (6 個工具)  │  │  (3 個工具)   │  │  (2 個工具)   │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │   管道   │  │  模擬  │  │   拓撲   │         │
│  │  (6 個工具)   │  │  (1 個工具)    │  │  (2 個工具)   │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             │ Kubernetes API 調用
                             │ Prometheus 查詢
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Kubernetes/OpenShift 集群                  │
│                                                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │   Pods   │  │ Services │  │ Tekton   │  │etcd/Logs │       │
│  └──────────┘  └──────────┘  │Pipelines │  └──────────┘       │
│  ┌──────────┐  ┌──────────┐  └──────────┘  ┌──────────┐       │
│  │  Events  │  │ Configs  │  ┌──────────┐  │Prometheus│       │
│  └──────────┘  └──────────┘  │OpenShift │  └──────────┘       │
│                               │Operators │                       │
│                               └──────────┘                       │
└─────────────────────────────────────────────────────────────────┘

工作流程

1. 用戶查詢 → AI 助手接收自然語言請求
2. MCP 轉換 → 助手將查詢轉換為適當的工具調用
3. LUMINO 處理 → 服務器執行 Kubernetes/Prometheus 操作
4. 數據分析 → 機器學習/統計算法處理原始數據
5. AI 合成 → 助手將結果格式化為人類可讀的見解

關鍵特性

• 無狀態設計 - 無數據持久化，即時查詢集群
• 自動傳輸檢測 - 在 stdio（本地）和 HTTP（K8s）模式之間切換
• 令牌預算管理 - 自適應策略處理大日誌量
• 智能緩存 - 對頻繁訪問的數據進行智能緩存
• 安全優先 - 使用現有的 kubeconfig RBAC 權限，無需單獨認證

🔧 技術細節

MCP 客戶端集成

方法 1：使用 MCPM（推薦用於 Claude Code CLI / Gemini CLI）

使用 MCPM（一個 MCP 服務器包管理器）是為 Claude Code CLI 或 Gemini CLI 安裝 LUMINO MCP 服務器的最簡單方法。

安裝 MCPM

# 克隆並構建 MCPM
git clone https://github.com/spre-sre/mcpm.git
cd mcpm
go build -o mcpm .

# 可選：添加到 PATH
sudo mv mcpm /usr/local/bin/

要求：Go 1.23+、Git、Python 3.10+、uv（或 pip）

安裝 LUMINO MCP 服務器

# 從 GitHub 倉庫安裝（短語法）
mcpm install @spre-sre/lumino-mcp-server

# 或使用完整的 GitHub URL
mcpm install https://github.com/spre-sre/lumino-mcp-server.git

# 對於 GitLab 倉庫（如果託管在 GitLab 上）
mcpm install gl:@spre-sre/lumino-mcp-server

# 為特定客戶端安裝
mcpm install @spre-sre/lumino-mcp-server --claude  # 對於 Claude Code CLI
mcpm install @spre-sre/lumino-mcp-server --gemini  # 對於 Gemini CLI

# 全局安裝（適用於 Claude 和 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

# 列出已安裝的服務器
mcpm list

# 更新 LUMINO
mcpm update lumino-mcp-server

# 移除 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  # 創建包含所有依賴項的 .venv

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. 驗證安裝：

# 檢查 MCP 服務器
claude mcp list

# 使用查詢進行測試
claude "列出我的集群中的所有命名空間"

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. 驗證安裝：

# 檢查 MCP 服務器
gemini mcp list

# 使用查詢進行測試
gemini "顯示失敗的管道運行"

Cursor IDE

1. 打開 Cursor 設置：
   • 按 Cmd+,（macOS）或 Ctrl+,（Windows/Linux）
   • 搜索 "MCP" 或 "模型上下文協議"
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 替換為你克隆倉庫的實際路徑：

# 示例路徑：
# macOS/Linux: /Users/username/projects/lumino-mcp-server
# Windows: C:\Users\username\projects\lumino-mcp-server

# 如果通過 MCPM 安裝：
# ~/.mcp/servers/lumino-mcp-server/

環境變量（可選）： 如果需要，將這些添加到 env 部分：

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

使用替代 Python 包管理器

使用 pip 代替 uv

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

注意：確保你首先激活了虛擬環境：

cd /path/to/lumino-mcp-server
python -m venv venv
source venv/bin/activate  # 在 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. 測試簡單查詢：

"列出我的 Kubernetes 集群中的所有命名空間"

3. 檢查服務器日誌（如果有問題）：

# 手動運行服務器以查看錯誤
cd /path/to/lumino-mcp-server
uv run python main.py

預期輸出：

MCP Server running in stdio mode
Available tools: 37
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 個 Pod)	使用默認設置	所有工具均可最佳運行
中型 (50 - 500 個 Pod)	使用命名空間過濾	利用自適應工具和自動採樣
大型 (500+ 個 Pod)	指定時間窗口和命名空間	使用保守和流式工具
超大型 (1000+ 個 Pod)	結合過濾器和分頁	進行漸進式分析和有針對性的查詢

令牌預算管理

LUMINO 自動管理 AI 上下文限制：

• 自適應採樣 - 當數據量較大時，智能工具自動對數據進行採樣
• 漸進式加載 - 流式分析以塊為單位處理數據
• 令牌預算 - 可配置的限制防止上下文溢出
• 混合策略 - 自動選擇最佳分析方法

查詢優化提示

使用命名空間過濾

✅ "分析生產命名空間中 Pod 的日誌"
❌ "分析集群中所有 Pod 的日誌"

指定時間窗口

✅ "顯示過去 2 小時內的事件"
❌ "顯示所有事件"（可能返回數千條）

利用智能工具

✅ "smart_summarize_pod_logs" - 自適應分析
❌ 直接轉儲日誌 - 無處理

使用漸進式分析

✅ 從 "概述" 開始 → 深入到 "詳細"
❌ 直接對大型數據集進行 "深入分析"

性能指標

操作	典型響應時間	可擴展性
列出命名空間	< 1s	O(1)
獲取 Pod 日誌（1 個 Pod）	1 - 3s	O(log 大小)
分析管道運行	2 - 5s	O(任務數量)
集群範圍搜索	5 - 15s	O(命名空間數量)
機器學習異常檢測	3 - 10s	O(數據點數量)
拓撲映射	5 - 20s	O(資源數量)

緩存策略

LUMINO 對頻繁訪問的數據使用智能緩存：

• 15 分鐘緩存 - 用於從網絡獲取的內容
• 會話緩存 - 用於混合日誌分析
• 無持久化 - 所有數據即時查詢集群

併發請求

服務器高效處理多個併發請求：

• 線程安全操作 - 安全的並行工具執行
• 連接池 - 重用 Kubernetes API 連接
• 異步 HTTP - 非阻塞的 Prometheus 查詢

資源使用

服務器資源要求

部署方式	CPU	內存	磁盤
本地（stdio）	100 - 500m	256 - 512Mi	最小
Kubernetes	200m - 1	512Mi - 1Gi	最小
高負載	1 - 2	1 - 2Gi	最小

注意：LUMINO 是無狀態的，需要的資源最少。大多數處理在 AI 助手中進行。

故障排除

常見問題

未找到 Kubernetes 集群

Error: Unable to load kubeconfig

確保你在 ~/.kube/config 有有效的 kubeconfig 文件，或者正在集群內運行。

資源權限被拒絕

Error: Forbidden - User cannot list resource

檢查你的 RBAC 權限。服務器需要對你要查詢的資源具有讀取權限。

工具超時 對於大型集群，某些工具可能會超時。使用過濾選項（命名空間、標籤）來縮小範圍。

依賴項

• mcp[cli]>=1.10.1 - 模型上下文協議 SDK
• kubernetes>=32.0.1 - Kubernetes Python 客戶端
• pandas>=2.0.0 - 數據分析
• scikit-learn>=1.6.1 - 機器學習算法
• prometheus-client>=0.22.0 - Prometheus 集成
• aiohttp>=3.12.2 - 異步 HTTP 客戶端

📄 許可證

本項目採用 Apache 許可證 2.0 版 - 有關詳細信息，請參閱 LICENSE 文件。

致謝

• 使用 FastMCP 框架構建
• 受管理複雜 Kubernetes 環境的 SRE 團隊需求的啟發