Lumino

LUMINO MCP 服务

一个开源 MCP（Model Context Protocol）服务，为 SRE 提供智能可观测性、预测分析和 AI 驱动的自动化能力，适用于 Kubernetes、OpenShift 和 Tekton 环境。

目录

• 概览
• 功能
• 快速开始
• 团队入门指南
• 前置条件
• 安装
• 使用示例
• 配置
• ML 模型持久化
• KubeArchive 集成
• Prometheus/Thanos 集成
• 可用工具
• 架构
• 工作原理
• MCP 客户端集成
• 性能注意事项
• 故障排查
• 依赖项
• 参与贡献
• 安全
• 许可证
• 致谢

团队入门指南

刚接触 SPRE MCP 诊断技术栈（Lumino、PagerDuty、Slack、DevLake、ngit-memory、GitHub、GitLab、Konflux Portal、Sumo Logic、Jira）？从这里开始：

• docs/ONBOARDING_GUIDE.md — 设置、首次诊断、故障排查、三个完整示例以及预期的工具输出

概览

LUMINO MCP Server 改变了站点可靠性工程师（SRE）和 DevOps 团队与 Kubernetes 集群交互的方式。它通过 Model Context Protocol 提供 39 种专用工具，使 AI 助手能够：

• 监控集群健康状况、资源和流水线状态
• 分析日志、事件和异常，使用统计与机器学习技术
• 排查失败流水线的问题并自动分析根本原因
• 预测资源瓶颈和潜在问题，防患于未然
• 模拟配置变更，以便在部署前评估影响

功能

Kubernetes 和 OpenShift 运维

• 命名空间和 Pod 管理
• 使用灵活的输出格式查询资源
• 在集群中按标签搜索资源
• OpenShift Operator 和 MachineConfigPool 状态
• etcd 日志分析

Tekton 流水线智能分析

• 跨命名空间监控流水线和任务运行
• 获取详细日志，可选择清理日志
• 分析失败流水线的根本原因
• 跨集群追踪流水线
• 建立 CI/CD 性能基线

高级日志分析

• 智能日志摘要，可配置详细程度
• 对大量日志进行流式分析
• 结合多种策略进行混合分析
• 使用 NLP 技术进行语义搜索
• 检测异常并按严重程度分类

预测式与主动监控

• 使用 z-score 分析进行统计异常检测
• 预测性日志分析，实现早期预警
• 预测资源瓶颈
• 监控证书健康状况并在即将到期时发出提醒
• 调查 TLS 证书问题

事件智能分析

• 使用多种策略智能检索事件
• 渐进式事件分析（从概览到深入调查）
• 使用 ML 模式检测进行高级分析
• 关联日志与事件

模拟与假设分析

• 使用 Monte Carlo 方法模拟配置变更
• 在部署前分析影响
• 使用可配置的容错度评估风险
• 识别受影响的组件

快速开始

不到 2 分钟即可开始使用 LUMINO：

Claude Code CLI 用户（最简单）

只需粘贴以下提示词，让 Claude Code 为你配置 Lumino MCP 服务：

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 权限 - 能够列出 Pod、命名空间和其他资源

可选（推荐）

• 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 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 客户端实时查看日志
KUBEARCHIVE_HOST	显式指定的 KubeArchive API 端点 URL	自动检测	使用自定义 KubeArchive 端点或非标准部署时
KUBEARCHIVE_ENABLED	启用/禁用 KubeArchive 集成	true	设置为 false 可完全禁用 KubeArchive 查询
THANOS_URL	Thanos Query 端点 URL（指标的最高优先级）	自动检测	使用自定义 Thanos Query 端点时；其优先级高于 PROMETHEUS_URL
PROMETHEUS_TOKEN	用于 Prometheus/Thanos 身份验证的 Bearer 令牌	自动检测	自动检测失败时显式指定身份验证令牌
OPENSHIFT_TOKEN	用于 Prometheus/Thanos 的 OpenShift Bearer 令牌	自动检测	OpenShift 集群中作为 PROMETHEUS_TOKEN 的替代项
OC_TOKEN	OpenShift CLI 令牌回退选项	自动检测	Prometheus/Thanos 身份验证的最后备用令牌

ML 模型持久化

predictive_log_analyzer 工具会在本地 ~/.lumino/ 中持久化已训练的 ML 模型和训练数据。这样可以在服务重启后复用模型，并根据历史故障模式进行增量学习。

目录结构

~/.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）包含四张表：

表	用途
log_samples	预处理后的日志样本，包含提取的特征、命名空间、Pod 名称、错误指示信息和消息熵
failure_labels	从 Kubernetes 事件、失败的 PipelineRun 和不健康的 Pod 状态中收集的故障事件。故障类型包括：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、使用的样本数、使用的标签数、性能指标和完成状态

四张表都定义了 cluster_id 列以支持多集群。目前，只有 log_samples 和 failure_labels 会在写入时主动填充该列；log_failure_correlations 和 training_runs 将其留空（NULL）。集群 ID 来源于活动 kubeconfig 上下文名称（例如 api-stone-prod-p02-hjvn-p1-openshiftapps-com:6443）；如果在 Pod 内运行，则回退为 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。当 Pod、PipelineRun 或 TaskRun 已从运行中的集群中清理后，LUMINO 会使用 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. 集群内 Service Account 令牌（/var/run/secrets/kubernetes.io/serviceaccount/token）
3. 现有 Kubernetes 客户端令牌（从服务器启动时初始化的 API 客户端中提取）
4. OpenShift oc whoami -t 令牌（用于 OpenShift 集群）
5. 自动创建的短期 Service Account 令牌（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

自动清理层

不使用显式上下文管理时，该类会提供三种备用清理机制：

1. atexit 处理程序 —— 在解释器正常关闭时清理端口转发
2. 信号处理程序（SIGTERM/SIGINT） —— 在终止时进行平稳清理，并串联调用原始处理程序
3. __del__ 终结器 —— 最后的备用机制（不保证触发时机）

推荐使用上下文管理器，以确保确定性地清理资源。

KubeArchive 配置

有关 KUBEARCHIVE_HOST 和 KUBEARCHIVE_ENABLED 环境变量，请参阅上文的配置部分。

Prometheus/Thanos 集成

LUMINO 会自动发现 Prometheus 或 Thanos Query 端点，供 prometheus_query、resource_bottleneck_forecaster 和 ci_cd_performance_baselining_tool 工具使用。Thanos Query 实现了 Prometheus HTTP API；在可用时优先使用，因为它能提供跨副本的统一去重视图。

端点发现优先级

优先级	来源	端点类型
0	THANOS_URL 环境变量	thanos
1	PROMETHEUS_URL 环境变量	prometheus
2	预定义的集群端点（在代码中）	不定
3	5 分钟 TTL 缓存	缓存
4	自动发现链（见下文）	已检测
5	预定义的回退端点	不定

自动发现顺序取决于运行时环境：

• 集群内：Thanos 服务 --> Prometheus 服务 --> Prometheus Operator CRD --> OpenShift Routes
• 本地／集群外：OpenShift Routes --> Thanos 服务 --> Prometheus Operator CRD --> Prometheus 服务

自动发现详情

OpenShift Routes：搜索 openshift-monitoring 命名空间。优先选择 thanos-querier Route，而不是 prometheus-k8s。如果没有，则回退到名称中包含 prometheus 的任意 Route。根据 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 Pipelines（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	集群 Operator 健康状况
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 综合 → 助手将结果整理为易于理解的见解

主要功能

• 最少的本地状态 - 实时查询集群；可选在 ~/.lumino/ 中持久化 ML 模型，用于预测分析（参见 ML 模型持久化）
• 自动检测传输方式 - 在 stdio（本地）和 HTTP（K8s）模式之间切换
• 令牌预算管理 - 采用自适应策略处理大量日志
• 智能缓存 - 为频繁访问的数据提供智能缓存
• 安全至上 - 使用现有 kubeconfig RBAC 权限，无需单独认证

MCP 客户端集成

方法 1：使用 MCPM（推荐用于 Claude Code CLI / Gemini CLI）

安装 LUMINO MCP 服务以供 Claude Code CLI 或 Gemini CLI 使用的最简单方法是使用 MCPM——一款 MCP 服务包管理器。

安装 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 包管理器

使用 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  # 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 个 pod）	使用默认设置	所有工具均可发挥最佳性能
中型（50-500 个 pod）	使用命名空间筛选	使用支持自动采样的自适应工具
大型（500+ 个 pod）	指定时间窗口和命名空间	使用保守型和流式工具
超大型（1000+ 个 pod）	结合使用筛选条件和分页	使用针对性查询进行渐进式分析

令牌预算管理

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)
获取 Pod 日志（1 个 Pod）	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 模型持久化）

并发请求

服务可高效处理多个并发请求：

• 线程安全操作 - 支持安全的并行工具执行
• 连接池 - 重用 Kubernetes API 连接
• 异步 HTTP - Prometheus 查询不会阻塞

资源使用

服务资源需求

部署方式	CPU	内存	磁盘
本地（stdio）	100-500m	256-512Mi	最低
Kubernetes	200m-1	512Mi-1Gi	最低
高负载	1-2	1-2Gi	最低

注意：LUMINO 所需资源极少。ML 模型和训练数据会持久化存储在本地 ~/.lumino/ 中（参见 ML 模型持久化）。大部分处理工作由 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 - ML 算法
• prometheus-client>=0.22.0 - Prometheus 集成
• aiohttp>=3.12.2 - 异步 HTTP 客户端

贡献

欢迎贡献！提交拉取请求前，请阅读我们的贡献指南。

安全

有关安全漏洞的信息，请参阅我们的安全策略。

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

致谢

• 使用 FastMCP 框架构建
• 灵感源自 SRE 团队管理复杂 Kubernetes 环境的需求