JinDaGe - lumino-mcp-server MCP Details

article

README

🚀 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 配置：

集群内配置 - 当在 Kubernetes Pod 内运行时
本地 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 │                       │
│                               └──────────┘                       │
└─────────────────────────────────────────────────────────────────┘

工作流程

用户查询 → AI 助手接收自然语言请求
MCP 转换 → 助手将查询转换为适当的工具调用
LUMINO 处理 → 服务器执行 Kubernetes/Prometheus 操作
数据分析 → 机器学习/统计算法处理原始数据
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

找到你的配置文件位置：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
- Linux：~/.config/Claude/claude_desktop_config.json
添加 LUMINO 配置：

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

重启 Claude Desktop
验证：在 Claude Desktop 中查找锤子图标（🔨）以查看可用工具

Claude Code CLI

选项 A：使用 MCPM（见方法 1 以上） 选项 B：通过 Claude Code 自动配置（推荐且最简单的方法）将快速开始部分中的配置提示复制并粘贴到 Claude Code 中。Claude 将克隆仓库、安装依赖项并为你的项目配置 MCP 服务器。 选项 C：手动配置

克隆并安装：

git clone https://github.com/spre-sre/lumino-mcp-server.git
cd lumino-mcp-server
uv sync  # 创建包含所有依赖项的 .venv

在项目根目录创建 .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：手动配置

找到你的配置文件位置：
- macOS/Linux：~/.config/gemini/mcp_servers.json
- Windows：%APPDATA%\gemini\mcp_servers.json
添加 LUMINO 配置：

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

验证安装：

# 检查 MCP 服务器
gemini mcp list

# 使用查询进行测试
gemini "显示失败的管道运行"

Cursor IDE

打开 Cursor 设置：
- 按 Cmd+,（macOS）或 Ctrl+,（Windows/Linux）
- 搜索 "MCP" 或 "模型上下文协议"
添加 MCP 服务器配置：在 Cursor 的 MCP 设置中，添加：

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

替代方法 - 使用 Cursor 的 settings.json：

打开命令面板（Cmd+Shift+P 或 Ctrl+Shift+P）
输入 "Preferences: Open User Settings (JSON)"
添加 MCP 配置：

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

重启 Cursor IDE
验证：打开 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"
}

测试你的配置

配置任何客户端后，测试连接：

检查工具是否加载：
- Claude Desktop：查找 🔨 锤子图标
- Claude Code CLI：claude mcp list
- Gemini CLI：gemini mcp list
- Cursor：检查 AI 聊天中是否有可用工具
测试简单查询：

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

检查服务器日志（如果有问题）：

# 手动运行服务器以查看错误
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 团队需求的启发