Kubernetes MCP Server

请按照专用的 Claude Code 入门指南操作，该指南位于我们的用户文档中。

如需使用专用 ServiceAccount 和只读访问权限进行安全的生产环境配置，请同时参阅 Kubernetes 配置指南。

• configuration_contexts_list - 列出 kubeconfig 文件中所有可用的 context 名称及关联的服务器 URL

• targets_list - 列出所有可用目标

• configuration_view - 获取当前 Kubernetes 配置内容，并以 kubeconfig YAML 格式返回

  • minified (boolean) - 返回精简版配置。若设为 true，则仅保留当前 context 及该 context 的相关配置部分。若设为 false，则在配置中返回所有 context、集群、身份验证信息和用户。（可选，默认值为 true）

• events_list - 列出当前集群所有命名空间中的 Kubernetes 事件（警告、错误、状态变更），用于调试和故障排查。使用 limit 和 continue 可逐页获取较大的列表。

  • continue (string) - 上一页的 continue 字段中的不透明令牌。使用相同的 limit、namespace 和选择器，不作修改地发送该令牌，以获取下一页。首次调用时省略。
  • fieldSelector (string) - 可选的 Kubernetes 字段选择器，用于按字段值筛选事件（例如 'type=Warning'、'involvedObject.name=my-pod'）。支持的字段：involvedObject.kind、involvedObject.name、involvedObject.namespace、involvedObject.uid、involvedObject.apiVersion、involvedObject.resourceVersion、involvedObject.fieldPath、reason、reportingComponent、source、type。请参阅 https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
  • limit (integer) - 要返回的最大条目数。省略或设为 0 表示列出所有条目；若响应超过 max_backend_response_bytes，则会失败。发生这种情况时，请缩小 limit 后重试。API 返回的条目数可能少于请求的数量。
  • namespace (string) - 可选的 Namespace，用于指定要从中检索事件的命名空间。若未提供，则列出所有命名空间中的事件。

• namespaces_list - 列出当前集群中的所有 Kubernetes 命名空间。使用 limit 和 continue 可逐页获取较大的列表。

  • continue (string) - 上一页的 continue 字段中的不透明令牌。使用相同的 limit、namespace 和选择器，不作修改地发送该令牌，以获取下一页。首次调用时省略。
  • fieldSelector (string) - 可选的 Kubernetes 字段选择器，用于按字段值筛选命名空间（例如 'metadata.name=default'、'status.phase=Active'）。支持的字段：metadata.name、status.phase。请参阅 https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
  • limit (integer) - 要返回的最大条目数。省略或设为 0 表示列出所有条目；若响应超过 max_backend_response_bytes，则会失败。发生这种情况时，请缩小 limit 后重试。API 返回的条目数可能少于请求的数量。

• projects_list - 列出当前集群中的所有 OpenShift 项目。使用 limit 和 continue 可逐页获取较大的列表。

  • continue (string) - 上一页的 continue 字段中的不透明令牌。使用相同的 limit、namespace 和选择器，不作修改地发送该令牌，以获取下一页。首次调用时省略。
  • limit (integer) - 要返回的最大条目数。省略或设为 0 表示列出所有条目；若响应超过 max_backend_response_bytes，则会失败。发生这种情况时，请缩小 limit 后重试。API 返回的条目数可能少于请求的数量。

• helm_list - 列出当前命名空间或指定命名空间中的所有 Helm release（如果指定，也可以列出所有命名空间中的 release）。使用 limit 和 offset 对返回的 release 分页。Helm 会在应用分页之前加载 release 密钥，因此，即使密钥列表超出 max_backend_response_bytes，操作仍可能失败。

  • all_namespaces (boolean) - 如果为 true，则忽略 namespace 参数，列出所有命名空间中的所有 Helm release（可选）
  • limit (integer) - 要返回的 release 数量上限。省略或设为 0，则返回 Helm 加载的所有 release。完整的一页会告知下一个 offset。
  • namespace (string) - 要从中列出 Helm release 的命名空间（可选；如果未提供，则列出所有命名空间）
  • offset (integer) - 要跳过的 release 数量。若收到完整的一页，请使用相同的 limit 发送下一页的 offset。

• helm_uninstall - 卸载当前命名空间或指定命名空间中的 Helm release

  • name (string) (required) - 要卸载的 Helm release 名称
  • namespace (string) - 要从中卸载 Helm release 的命名空间（可选；如果未提供，则使用当前命名空间）

• kcp_workspaces_list - 列出当前集群中所有可用的 kcp 工作区

• kcp_workspace_describe - 获取特定 kcp 工作区的详细信息

  • workspace (string) (required) - 要描述的工作区名称或路径

• kiali_get_mesh_traffic_graph - 返回指定命名空间的服务间流量拓扑、依赖关系和网络指标（吞吐量、响应时间、mTLS）。使用此工具诊断路由问题、延迟，或查找上游/下游依赖项。

  • graphType (string) - 图的粒度。'app' 按应用名称聚合，'versionedApp' 按版本区分，'workload' 映射特定的 Pod/Deployment。默认值：versionedApp。
  • meshCluster (string) - 可选的 Istio 网格集群名称，来自 kiali_list_mesh_clusters（例如 west）。省略时，Kiali 默认使用其主集群。
  • namespaces (string)` (required) - 要映射的逗号分隔命名空间列表

• kiali_get_mesh_status - 获取 Istio 服务网格的总体运行状况、拓扑和环境详情。返回多集群控制平面状态（istiod）、数据平面命名空间运行状况（包括 ambient mesh 状态）、可观测性技术栈运行状况（Prometheus、Grafana 等）以及组件连通性。将此工具作为诊断整个网格问题、验证 Istio/Kiali 版本，或在深入检查特定工作负载前检查整体运行状况的第一步。

• kiali_manage_istio_config - 创建、修补或删除 Istio、Gateway API 和 Inference API 配置。支持 Istio 资源（networking.istio.io、security.istio.io）、Gateway API 资源（gateway.networking.k8s.io），以及在集群上已安装时的 Inference API 资源（inference.networking.k8s.io）。读取列表和对象请使用 manage_istio_config_read。

  • action（string）（必需） - 要执行的操作（写入）
  • data（string）- 资源的 JSON 或 YAML 数据。执行 create 和 patch 操作时必需。执行 create 时，可提供部分内容（例如仅提供 spec），系统会将其与带默认值的有效模板合并。数组（如 servers、http 等）会被整体替换，因此请包含所需的所有元素。
  • group（string）（必需） - Istio 对象的 API 组。Gateway API 资源请使用 'gateway.networking.k8s.io'。Inference API 资源请使用 'inference.networking.k8s.io'。
  • kind（string）（必需） - Istio 对象的类型（例如，'VirtualService'、'DestinationRule'）。
  • meshCluster（string）- 可选的 Istio 网格集群名称，取自 kiali_list_mesh_clusters（例如 west）。省略时，Kiali 默认使用其所在的集群。
  • namespace（string）（必需） - 包含 Istio 对象的命名空间。
  • object（string）（必需） - Istio 对象的名称。
  • version（string）（必需） - API 版本。所有资源类型均使用 'v1'。

• kiali_list_mesh_clusters - 返回 Kiali 可访问的 Istio 网格集群列表。每个条目都包含集群名称，以及该集群是否为 home 集群（即部署 Kiali 的集群）。目标集群未知时，请在其他 Kiali 工具中使用 meshCluster 前调用此工具。

• kiali_get_resource_details - 获取资源列表，或检索特定资源的详细数据。如果省略 'resourceName'，则返回列表。如果提供了 'resourceName'，则返回该特定资源的详细信息。

  • meshCluster (string) - 可选的 Istio 网格集群名称，来自 kiali_list_mesh_clusters（例如 west）。省略时，Kiali 默认使用其主集群。
  • namespaces (string) - 要查询的命名空间，以逗号分隔的列表（例如 'bookinfo' 或 'bookinfo,default'）。如果未提供，则会查询所有可访问的命名空间。
  • resourceName (string) - 可选。资源的具体名称。如果留空，工具会返回指定类型的所有资源列表。如果提供，则会返回该特定资源的详细信息。
  • resourceType (string) （必填） - 要查询的资源类型。对于 Kiali 应用（按 Kubernetes 'app' 标签分组），使用 'app'。对于 ArgoCD Application CRD，使用 'argoapp'（需要安装 ArgoCD，且 Kiali 服务账号必须具有 applications.argoproj.io 的读取权限）。

• kiali_list_traces - 列出某个命名空间中某项服务的分布式跟踪记录。返回摘要（namespace、service、total_found、avg_duration_ms）以及包含 id、duration_ms、spans_count、root_op、slowest_service、has_errors 的跟踪记录列表。使用带有跟踪 ID 的 get_trace_details 获取完整层级结构。

  • errorOnly (boolean) - 如果为 true，则只考虑包含错误的跟踪记录。默认为 false。
  • limit (integer) - 要返回的跟踪记录的最大数量。默认为 10。
  • lookbackSeconds (integer) - 向前回溯搜索的时长。默认为 600（10m）。
  • meshCluster (string) - 可选的 Istio 网格集群名称，来自 kiali_list_mesh_clusters（例如 west）。省略时，Kiali 默认使用其主集群。
  • namespace (string) （必填） - 服务所在的 Kubernetes 命名空间。
  • serviceName (string) （必填） - 要搜索跟踪记录的服务名称（必填）。最多返回 limit 条跟踪记录。

• kiali_get_trace_details - 根据 trace_id 获取单条分布式跟踪记录，并返回其调用层级结构（包含持续时间、状态和嵌套调用的服务树）。使用此工具可在调用 list_traces 后深入查看特定跟踪记录。

  • traceId (string) （必填） - 要获取并汇总的跟踪 ID。如果提供，则忽略 namespace/service_name。

• kiali_get_pod_performance - 返回易读的文本摘要，对比当前 Pod 的 CPU/内存用量（来自 Prometheus）与 Kubernetes 请求/限制（来自 Pod 规格）。可用于回答“此工作负载是否使用了过多内存？”等问题。

  • meshCluster (string) - 可选的 Istio 网格集群名称，来自 kiali_list_mesh_clusters（例如 west）。省略时，Kiali 默认使用其主集群。
  • namespace (string) （必填） - Pod 所在的 Kubernetes 命名空间。
  • podName (string) - Kubernetes Pod 名称。如果提供了 workloadName，工具会先尝试从该工作负载中解析一个 Pod。
  • queryTime (string) - 可选的查询结束时间戳（RFC3339）。默认为当前时间。
  • timeRange (string) - 用于计算 CPU 速率的时间窗口（Prometheus 时长格式，如 '5m'、'10m'、'1h'、'1d'）。默认为 '10m'。
  • workloadName (string) - Kubernetes 工作负载名称（例如 Deployment/StatefulSet 等）。工具会查找该工作负载并选取其中一个 Pod。如果未找到，则会将此值作为 podName 处理。

• kiali_get_logs - 获取 Kubernetes Pod（或可解析为 Pod 的工作负载名称）在某个命名空间中的日志。输出为纯文本，与 kubernetes-mcp-server 的 pods_log 格式一致。line_count 字段表示返回的日志总行数。请分析所有日志行，但除非用户明确要求原始输出，否则请总结结果。不要遗漏任何错误或警告行。

  • container (string) - 可选。要获取日志的 Pod 容器名称。
  • format (string) - 聊天输出格式。'codeblock' 会用 ~~~ 围住日志（推荐）。'plain' 返回类似 kubernetes-mcp-server pods_log 的原始文本。
  • meshCluster (string) - 可选。来自 kiali_list_mesh_clusters 的 Istio 网格集群名称（例如 west）。省略时，Kiali 默认使用其主集群。
  • name (string) (required) - 要获取日志的 Pod 名称。如果该 Pod 不存在，则会将其视为工作负载名称，并选择一个正在运行的 Pod。
  • namespace (string) (required) - 获取 Pod 日志的命名空间
  • previous (boolean) - 可选。返回先前已终止容器的日志
  • severity (string) - 可选。在客户端应用的严重性筛选条件。接受 'ERROR'、'WARN' 或 'ERROR,WARN' 这类组合。
  • tail (integer) - 从日志末尾获取的行数（可选，默认值为 50）。不得超过 200 行。
  • workload (string) - 可选。覆盖工作负载名称（在名称查找失败时使用）。

• kiali_get_metrics - 返回给定资源的 Istio 指标精简 JSON 摘要（延迟分位数、流量趋势、吞吐量、有效载荷大小）。

  • byLabels (string) - 用于对指标分组的逗号分隔标签列表（例如 'source_workload,destination_service'）。可选
  • direction (string) - 流量方向。可选，默认为 'outbound'
  • meshCluster (string) - 可选。来自 kiali_list_mesh_clusters 的 Istio 网格集群名称（例如 west）。省略时，Kiali 默认使用其主集群。
  • namespace (string) (required) - 获取指标的命名空间
  • quantiles (string) - 直方图指标分位数的逗号分隔列表（例如 '0.5,0.95,0.99'）。可选
  • rateInterval (string) - 指标的速率间隔（例如 '1m'、'5m'）。可选，默认为 '10m'
  • reporter (string) - 指标报告方。逗号分隔的列表，可选值为 'source'、'destination'、'waypoint'，或特殊值 'both'（不筛选报告方）。可选，默认为 'source'。示例：'source,waypoint'
  • requestProtocol (string) - 按请求协议筛选（例如 'http'、'grpc'、'tcp'）。可选
  • resourceName (string) (required) - 要获取指标的资源名称
  • resourceType (string) (required) - 资源类型
  • step (string) - 数据点之间的步长（秒）（例如 '15'）。可选，默认为 15 秒

• vm_clone - 在 KubeVirt 上通过创建 VirtualMachineClone 资源克隆 VirtualMachine。此操作会使用 KubeVirt Clone API，以新名称创建源 VM 的副本

  • name (string) (required) - 要克隆的源虚拟机名称
  • namespace (string) (required) - 源虚拟机所在的命名空间
  • targetName (string) (required) - 新克隆虚拟机的名称

• vm_console_screenshot - 将 KubeVirt 上 VirtualMachine 的图形（VNC）控制台截取为 PNG 图像。可使用此工具查看 VM 屏幕上当前显示的内容（例如固件、引导加载程序或登录提示）。只读：绝不会向来宾发送输入。

  • name (string) (required) - 虚拟机名称
  • namespace (string) (required) - 虚拟机所在的命名空间

• vm_create - 使用指定配置在 KubeVirt 上创建 VirtualMachine，并自动解析实例类型、偏好设置和容器磁盘镜像。默认情况下，VM 将以 Halted 状态创建；使用 autostart 参数可立即启动。

  • autostart (boolean) - 可选标志，用于在创建后自动启动 VM（将 runStrategy 设置为 Always，而非 Halted）。默认为 false。
  • instancetype (string) - VM 的可选实例类型名称（例如，'u1.small'、'u1.medium'、'u1.large'）
  • name (string) (required) - 虚拟机名称
  • namespace (string) (required) - 虚拟机所在的命名空间
  • networks (array) - 要附加到 VM 的可选辅助网络接口。每个条目指定要附加的 Multus NetworkAttachmentDefinition。接受简单字符串（NetworkAttachmentDefinition 名称）或包含 'name'（VM 中的接口名称）和 'networkName'（NetworkAttachmentDefinition 名称）属性的对象。每个网络都会在 VM 上创建一个桥接接口。
  • performance (string) - VM 实例类型的可选性能系列提示（例如，'u1' 表示通用型，'o1' 表示超分配型，'c1' 表示计算优化型，'m1' 表示内存优化型）。如果未指定，则默认为 'u1'（通用型）。
  • preference (string) - VM 的可选偏好设置名称
  • size (string) - VM 的可选工作负载规模提示（例如，'small'、'medium'、'large'、'xlarge'）。如果未明确指定实例类型，则用于自动选择合适的实例类型。
  • storage (string) - 使用 DataSources 时，VM 根磁盘的可选存储大小（例如，'30Gi'、'50Gi'、'100Gi'）。默认为 30Gi。使用容器磁盘时将忽略此项。
  • workload (string) - VM 的工作负载。接受 OS 名称（例如，'fedora'（默认）、'ubuntu'、'centos'、'centos-stream'、'debian'、'rhel'、'opensuse'、'opensuse-tumbleweed'、'opensuse-leap'）或完整的容器磁盘镜像 URL

• vm_guest_info - 从 VirtualMachine 的 QEMU guest agent 获取来宾操作系统信息。要求在 VM 内安装并运行 guest agent。提供有关 OS、文件系统、网络接口和已登录用户的详细信息。

  • info_type (string) - 要获取的信息类型：'all'（默认值，所有可用信息）、'os'（操作系统详情）、'filesystem'（磁盘和文件系统信息）、'users'（已登录用户）、'network'（网络接口和 IP）
  • name (string) (required) - 虚拟机名称
  • namespace (string) (required) - 虚拟机所在的命名空间

• vm_lifecycle - 管理 KubeVirt VirtualMachine 生命周期：启动、停止、重启、暂停或取消暂停 VM

  • action (string) (required) - 要执行的生命周期操作：'start'（将 runStrategy 改为 Always）、'stop'（将 runStrategy 改为 Halted）、'restart'（先停止再启动 VM）、'pause'（就地挂起正在运行的 VMI）或 'unpause'（恢复已暂停的 VMI）
  • name (string) (required) - 虚拟机名称
  • namespace (string) (required) - 虚拟机所在的命名空间

• vm_create_from_template - 根据 KubeVirt 上的 VirtualMachineTemplate（virt-template）创建 VirtualMachine。在服务器端处理模板以替换参数（必填值、默认值和密码等自动生成的值），然后在同一命名空间中创建生成的 VirtualMachine。不支持跨命名空间使用模板。

  • namespace（string）（必填） - VirtualMachineTemplate 和生成的 VirtualMachine 所在的命名空间（必须相同）
  • parameters（object）- 要替换到模板中的参数值。键为参数名称（例如 VM_NAME），值为字符串。必须提供必填参数；如果省略可选参数，则使用其默认值；如果未提供带有 generate/from 的参数，则会自动生成。
  • template_name（string）（必填） - 用于创建 VM 的 VirtualMachineTemplate 名称

• vm_troubleshoot - 通过自动根因检测诊断 KubeVirt VirtualMachine 问题。收集 VM 状态、VMI 状态、卷、DataVolume/PVC 状态、cloud-init 配置、Pod 状态、日志和事件，然后运行启发式检查，以识别具体问题并建议修复方法。返回包含 CRITICAL/WARNING 发现项和可执行修复步骤的“Detected Issues”部分，后面附上原始诊断数据。用户询问 VM 为何无法启动、卡在 Provisioning、陷入 crashloop、迁移失败或表现异常时，请始终先使用此工具。如果用户要求修复或处理问题，请使用报告中的 Suggested Fixes，并通过 vm_lifecycle（重启）或 resources_create_or_update 执行。

  • name（string）（必填） - 要排查的 VirtualMachine 名称
  • namespace（string）（必填） - 要排查的 VirtualMachine 所在命名空间

• netobserv_list_flows - 从 Loki 列出 NetObserv 网络流记录。用于调查某个命名空间或时间范围内工作负载、IP、端口或协议之间的流量。
  • endTime（integer）- 时间范围的结束时间，以 Unix 纪元秒数表示。默认为当前时间。
  • filters（string）- 传递给控制台插件的 NetObserv 过滤表达式（纯文本；客户端会对其进行 URL 编码）。

语法：

• key=value — 精确匹配；key=a,b — 同一键的多个值取 OR
• key~pattern — 正则表达式／包含匹配；key!~pattern — 非正则匹配
• key!=value — 不等于；key>number — 数值大于或等于（例如 Bytes>1000）
• 组内 AND：&（例如 SrcK8S_Namespace=default&Proto=6）
• 组间 OR：|（例如 SrcK8S_Name=pod-a|SrcK8S_Name=pod-b）

可能时，优先使用专用的 "namespace" 参数指定命名空间范围。 使用 Kubernetes 列表工具（namespaces、pods、deployments 等）来查找过滤值。

常见 Kubernetes 字段（Src/Dst 前缀相互对应）：

• SrcK8S_Namespace、DstK8S_Namespace、SrcK8S_Name、DstK8S_Name
• SrcK8S_Type、DstK8S_Type（例如 Pod、Service、Node）
• SrcK8S_OwnerName、DstK8S_OwnerName、SrcK8S_OwnerType、DstK8S_OwnerType（用于 Deployment、StatefulSet 等）
• SrcK8S_HostName、DstK8S_HostName、SrcK8S_Zone、DstK8S_Zone、K8S_ClusterName、UDN

网络与流量：

• SrcAddr、DstAddr（IP）、SrcPort、DstPort、Proto（IANA 编号，例如 6=TCP、17=UDP）
• FlowDirection（0=Ingress、1=Egress、2=Inner）、Bytes、Packets、Dscp、Flags

数据包丢弃（通常带有 recordType flowLog 和 packetLoss dropped/hasDrops）：

• PktDropPackets、PktDropBytes、PktDropLatestState、PktDropLatestDropCause

DNS：

• DnsName、DnsId、DnsLatencyMs、DnsErrno、DnsFlagsResponseCode

• loki_list_instances - 列出 Kubernetes 集群中可用的 LokiStack 实例。 使用由 Loki Operator 管理的堆栈时，请先调用此工具，以便向其他 Loki 工具传入 lokiNamespace 和 lokiName。

• loki_label_names - 列出指定时间范围内可用的 Loki 标签名称。在编写 LogQL 查询前使用此工具。

  • end (string) - 结束时间，格式为 RFC3339、Unix 时间戳、NOW 或相对于 NOW 的表达式（可选）。
  • lokiName (string) - LokiStack 的名称。使用 loki_list_instances 查找有效值。
  • lokiNamespace (string) - LokiStack 所在的 Kubernetes 命名空间。使用 loki_list_instances 查找有效值。
  • start (string) - 开始时间，格式为 RFC3339、Unix 时间戳、NOW 或相对于 NOW 的表达式（可选）。
  • tenant (string) - Loki 租户 ID（X-Scope-OrgID）。对于 LokiStack 网关模式（例如 openshift-network），此参数会选择 /api/logs/v1/<tenant> 路径；对于 openshift-network，请使用 network。

• loki_label_values - 列出 Loki 标签键的可能取值。使用此工具在 LogQL 中构造精确的标签匹配器。

  • end (string) - 结束时间，格式为 RFC3339、Unix 时间戳、NOW 或相对于 NOW 的表达式（可选）。
  • label (string) （必填） - 要检查的标签键（例如 namespace、pod、container）。
  • lokiName (string) - LokiStack 的名称。使用 loki_list_instances 查找有效值。
  • lokiNamespace (string) - LokiStack 所在的 Kubernetes 命名空间。使用 loki_list_instances 查找有效值。
  • start (string) - 开始时间，格式为 RFC3339、Unix 时间戳、NOW 或相对于 NOW 的表达式（可选）。
  • tenant (string) - Loki 租户 ID（X-Scope-OrgID）。对于 LokiStack 网关模式（例如 openshift-network），此参数会选择 /api/logs/v1/<tenant> 路径；对于 openshift-network，请使用 network。

• loki_query_range - 执行 Loki LogQL 范围查询，并返回匹配的日志流和日志行。

• list_metrics - 必须首先执行：列出 Prometheus 中所有可用的指标名称。

在使用任何其他查询工具之前，必须调用此工具。

对于每个可观测性问题，都必须首先调用此工具，以便：

1. 发现此环境中实际存在的指标
2. 找到查询中要使用的确切指标名称
3. 避免查询不存在的指标
4. 始终应提供 name_regex 参数，并尽可能猜测指标名称的形式。
5. 不要在 name_regex 参数中使用 .* 或 .+ 之类的通用正则表达式。请使用 kube.*、node.* 等具体模式。

正则表达式模式指南：

• Prometheus 指标通常带有前缀（例如，prometheus_tsdb_head_series、kube_pod_status_phase）
• 若要匹配包含某个子字符串的指标，请使用通配符：.*tsdb.* 可匹配 prometheus_tsdb_head_series
• 不使用通配符时，模式将进行精确匹配：tsdb 只匹配名称恰好为 tsdb 的指标（这种情况很少见）
• 常见模式：kube_pod.*（Pod）、.*memory.*（内存相关）、node_.*（节点指标）
• 如果没有结果，请尝试在搜索词前后添加 .*

绝不要跳过此步骤。绝不要猜测指标名称。不同环境中的指标名称各不相同。

调用此工具后：

1. 在返回的列表中搜索相关指标
2. 在后续查询中使用找到的确切指标名称
3. 如果没有相关指标，请告知用户

• name_regex (string) （必填） - 用于筛选指标名称的正则表达式模式。重要：指标名称通常带有前缀（例如，prometheus_tsdb_head_series）。使用通配符匹配子字符串：.*tsdb.* 可匹配任何包含 tsdb 的指标，而 tsdb 只匹配名称恰好为 tsdb 的指标。示例：http_.*（以 http_ 开头）、.*memory.*（包含 memory）、node_.*（以 node_ 开头）。此参数为必填项。不要传入 .* 或 .+ 之类的通用正则表达式。

• execute_instant_query - 执行 PromQL 即时查询，以获取当前值或某个时间点的值。

前提条件：必须先调用 list_metrics，以确认指标存在。

使用场景：

• 查询当前状态：“当前错误率是多少？”
• 查询某个时间点的快照：“有多少个 Pod 正在运行？”
• 查询最新值：“哪些 Pod 处于 Pending 状态？”

query 参数必须使用 list_metrics 返回的指标名称。

• query (string) （必填） - PromQL 查询字符串，使用经 list_metrics 验证的指标名称

• time (string) - 评估时间，格式为 RFC3339 或 Unix 时间戳。省略或使用 'NOW' 表示当前时间。

• execute_range_query - 执行 PromQL 范围查询，以获取一段时间内的时间序列数据。

前提条件：必须先调用 list_metrics，以确认指标存在。 适用场景：

• 随时间变化的趋势：“过去 1 小时的 CPU 使用率是多少？”
• 速率计算：“每秒有多少个请求？”
• 历史分析：“过去 5 分钟内是否发生过重启？”

时间参数：

• 'duration'：从现在往回查询的时长（例如，“5m”、“1h”、“24h”）
• 'step'：数据点的分辨率（例如，时长为 1 小时时使用“1m”，时长为 24 小时时使用“5m”）

'query' 参数必须使用 list_metrics 返回的指标名称。

• duration (string) - 从现在往回查询的时长（例如，'1h'、'30m'、'1d'、'2w'）（可选）

• end (string) - 结束时间，格式为 RFC3339 或 Unix 时间戳（可选）。当前时间请使用 NOW。

• query (string) （必填） - PromQL 查询字符串，使用通过 list_metrics 验证的指标名称

• start (string) - 开始时间，格式为 RFC3339 或 Unix 时间戳（可选）

• step (string) （必填） - 查询分辨率步长（例如，'15s'、'1m'、'1h'）。请根据时间范围选择：较短的范围使用较小的步长。

• show_timeseries - 将结果显示为交互式时间序列图表。

此工具的工作方式与 execute_range_query 类似，但会在 UI 客户端中将结果渲染为可视化图表。 当用户希望查看时间序列数据的图表或可视化内容，并通过图表提供答案时，请使用此工具。 在所有其他 Prometheus 工具调用完成并确定结果后，将 show_timeseries 作为最后一个工具调用。

时间参数：

• 'duration'：从现在往回查询的时长（例如，“5m”、“1h”、“24h”）
• 'step'：数据点的分辨率（例如，时长为 1 小时时使用“1m”，时长为 24 小时时使用“5m”）
• 'title'：描述性图表标题（例如，“过去 1 小时的 API 错误率”）
• 'description'：对图表含义或上下文的说明（例如，“显示按 Pod 拆分的每秒 HTTP 5xx 错误率”）

'query' 参数必须是范围查询，并且必须使用 list_metrics 返回的指标名称。

• description (string) - 对图表含义或上下文的说明（例如，'显示按 Pod 拆分的每秒 HTTP 5xx 错误率'）。提供后会显示在标题下方。

• duration (string) - 从现在往回查询的时长（例如，'1h'、'30m'、'1d'、'2w'）（可选）

• end (string) - 结束时间，格式为 RFC3339 或 Unix 时间戳（可选）。当前时间请使用 NOW。

• query (string) （必填） - PromQL 查询字符串，使用通过 list_metrics 验证的指标名称

• start (string) - 开始时间，格式为 RFC3339 或 Unix 时间戳（可选）

• step (string) （必填） - 查询分辨率步长（例如，'15s'、'1m'、'1h'）。请根据时间范围选择：较短的范围使用较小的步长。

• title (string) - 描述查询内容的易读图表标题（例如，'过去 1 小时的 API 错误率'）。提供后会显示在图表上方。

• get_label_names - 获取可用于筛选指标的所有标签名称（维度）。

适用场景（调用 list_metrics 后）：

• 了解如何筛选指标（按命名空间、Pod、服务等）
• 在 PromQL 查询中构造标签匹配器之前

'metric' 参数应使用 list_metrics 输出中的指标名称。

• end (string) - 标签发现的结束时间，格式为 RFC3339 或 Unix 时间戳（可选，默认为现在）

• metric (string) - 要获取标签名称的指标名称（来自 list_metrics）。留空则获取所有指标。

• start (string) - 标签发现的开始时间，格式为 RFC3339 或 Unix 时间戳（可选，默认为 1 小时前）

• get_label_values - 获取特定标签的所有唯一值。

适用场景（调用 list_metrics 和 get_label_names 后）：

• 查找用于筛选的确切标签值（命名空间名称、Pod 名称等）

• 在构造查询之前查看有哪些值 应使用 list_metrics 输出中的指标名称作为 metric 参数。

  • end（string）- 标签值发现的结束时间，格式为 RFC3339 或 Unix 时间戳（可选，默认为当前时间）
  • label（string）（必填）- 要获取其值的标签名称（来自 get_label_names）
  • metric（string）- 指标名称（来自 list_metrics），用于限定标签值的范围。留空表示所有指标。
  • start（string）- 标签值发现的开始时间，格式为 RFC3339 或 Unix 时间戳（可选，默认为 1 小时前）

• get_series - 获取与选择器匹配的时间序列并预览基数。

何时使用（可选，在调用 list_metrics 后）：

• 查询前验证标签筛选条件是否匹配预期的时间序列
• 检查基数，避免查询缓慢

基数指南：

• 少于 100 个时间序列：安全
• 100–1000 个：通常没问题
• 超过 1000 个：添加更多标签筛选条件

选择器应使用 list_metrics 输出中的指标名称。

• end（string）- 时间序列发现的结束时间，格式为 RFC3339 或 Unix 时间戳（可选，默认为当前时间）

• matches（string）（必填）- 使用 list_metrics 中指标名称的 PromQL 时间序列选择器

• start（string）- 时间序列发现的开始时间，格式为 RFC3339 或 Unix 时间戳（可选，默认为 1 小时前）

• get_alerts - 从 Alertmanager 获取告警。

何时使用：

• 调查问题时从此处开始：如果用户询问故障、错误、失败、服务中断、服务宕机，或集群中出现的任何异常情况
• 用户提到特定告警名称时，使用此工具获取该告警的完整标签（namespace、pod、service 等），这些信息对于使用其他工具进一步调查至关重要
• 查看集群中当前正在触发的告警
• 检查哪些告警处于活动、已静默或已抑制状态
• 在深入查看指标或日志之前了解当前情况

调查提示：告警标签通常包含使用 Prometheus 工具执行定向查询所需的确切标识符（pod 名称、namespace、job 名称）。

筛选：

• 使用 'active' 仅筛选活动告警（未解决）
• 使用 'silenced' 筛选已静默的告警
• 使用 'inhibited' 筛选已抑制的告警
• 使用 'filter' 应用标签匹配器（例如："alertname=HighCPU"）
• 使用 'receiver' 按接收器名称筛选告警

所有筛选参数均为可选。不使用筛选条件时，将返回所有告警。

• active（boolean）- 仅筛选活动告警（true/false，可选）

• filter（string）- 用于筛选告警的标签匹配器（例如：'alertname=HighCPU'，可选）

• inhibited（boolean）- 仅筛选已抑制的告警（true/false，可选）

• receiver（string）- 用于筛选告警的接收器名称（可选）

• silenced（boolean）- 仅筛选已静默的告警（true/false，可选）

• unprocessed（boolean）- 仅筛选尚未处理的告警（true/false，可选）

• get_silences - 从 Alertmanager 获取静默规则。

何时使用：

• 查看当前处于静默状态的告警
• 检查活动、待处理或已过期的静默规则
• 调查特定告警未触发通知的原因

筛选：

• 使用 'filter' 应用标签匹配器，以查找特定的静默规则

静默规则根据标签匹配器临时静默告警。此工具可帮助你了解环境中当前处于静默状态的内容。

• filter（string）- 用于筛选静默规则的标签匹配器（例如：'alertname=HighCPU'，可选）

• otelcol_list_components - 列出指定版本的可用 OpenTelemetry Collector 组件（接收器、处理器、导出器、扩展和连接器）。

  • version（string）- Collector 版本（例如：'v0.100.0'）。默认为最新可用版本。

• otelcol_get_component_schema - 获取 OpenTelemetry Collector 组件配置选项的 JSON 架构。

  • component_name (string) (必填) - 来自 otelcol_list_components 的组件名称（例如：'otlp'、'batch'、'debug'）
  • component_type (string) (必填) - 组件类型：receiver、processor、exporter、extension、connector
  • version (string) - Collector 版本（例如：'v0.100.0'）。默认为最新可用版本。

• otelcol_validate_config - 根据 JSON 架构验证 OpenTelemetry Collector 组件配置。

  • component_name (string) (必填) - 来自 otelcol_list_components 的组件名称（例如：'otlp'、'batch'、'debug'）
  • component_type (string) (必填) - 组件类型：receiver、processor、exporter、extension、connector
  • config (string) (必填) - 要验证的配置，以 YAML 或 JSON 字符串形式提供
  • format (string) - 配置格式：'yaml'（默认）或 'json'
  • version (string) - Collector 版本（例如：'v0.100.0'）。默认为最新可用版本。

• otelcol_get_versions - 列出可用的 OpenTelemetry Collector 版本并确定最新版本。

• tempo_list_instances - 列出 Kubernetes 集群中所有可用的 Tempo 实例。 在使用其他 Tempo 工具之前，请先调用此工具以发现可用的 Tempo 实例， 因为返回的 namespace、name 和 tenant 值是所有其他 Tempo 工具的必需参数。 请始终以表格形式打印此工具的输出。

• tempo_get_trace_by_id - 根据 trace ID 从 Tempo 检索单条分布式追踪。 返回包含所有 span 的完整追踪，包括服务名称、操作名称、持续时间和属性。 如果已有特定的 trace ID（例如来自搜索结果或日志），请使用此工具。

  • end (string) - 时间范围的可选结束时间，采用 RFC 3339 格式，例如 "2025-01-02T00:00:00Z"。 缩小时间范围以提升查询性能。
  • start (string) - 时间范围的可选开始时间，采用 RFC 3339 格式，例如 "2025-01-01T00:00:00Z"。 缩小时间范围以提升查询性能。
  • tempoName (string) (必填) - 要查询的 Tempo 实例名称。使用 tempo_list_instances 发现可用的实例名称。
  • tempoNamespace (string) (必填) - 部署 Tempo 实例的 Kubernetes 命名空间。使用 tempo_list_instances 发现可用的命名空间。
  • tenant (string) - 要查询的租户。对于多租户实例，此参数为必填项。使用 tempo_list_instances 发现每个实例可用的租户。
  • traceid (string) (必填) - 要检索的 trace ID，例如 "26dad4a0e2b0dd9a440dd5ff203a24a4"。

• tempo_search_traces - 使用 TraceQL 搜索 Tempo 中的分布式追踪。 使用此工具查找符合特定条件的追踪，例如服务名称、HTTP 状态码、持续时间或其他 span 或资源属性。

重要——“慢”或“长”追踪请求：不要猜测持续时间阈值。 首先调用此工具，不添加持续时间筛选条件，以确定延迟基线；然后使用该基线设置合理的阈值。 这两个步骤都必须执行——不要跳过第二次带持续时间筛选条件的搜索。 仅当用户提供了明确的持续时间（例如“查找耗时超过 2s 的追踪”）时，才跳过此两步流程。

• end (string) - 时间范围的结束时间，采用 RFC 3339 格式，例如 "2025-01-01T00:00:00Z"。 当前时间请使用 "NOW"。 要搜索完整时间范围，必须同时提供 start 和 end；如果省略，则只搜索最近一小段时间的数据。
• limit (integer) - 返回的追踪数量上限。如果未指定，则默认为服务端限制。
• query (string) (必填) - TraceQL 查询表达式。格式： query: "{ <filters joined by &&> }"

重要：status 的值（error、ok、unset）是关键字，不是字符串。请写 status=error，绝不要写 status="error"。

运算符：=、!=、>、<、>=、<=

常见属性：

• resource.service.name（服务名称）
• resource.k8s.namespace.name（Kubernetes 命名空间）
• resource.k8s.deployment.name（Kubernetes 部署）
• resource.k8s.statefulset.name（Kubernetes StatefulSet）
• resource.k8s.daemonset.name（Kubernetes DaemonSet）
• resource.k8s.replicaset.name（Kubernetes ReplicaSet）
• resource.k8s.pod.name（Kubernetes Pod）
• resource.k8s.container.name（Kubernetes 容器）
• resource.k8s.job.name（Kubernetes Job）
• resource.k8s.cronjob.name（Kubernetes CronJob）
• resource.k8s.node.name（Kubernetes 节点）
• resource.k8s.cluster.name（Kubernetes 集群）
• span.http.response.status_code（HTTP 响应码）
• span.http.request.method（HTTP 方法，例如 GET、POST）
• span.url.full（请求 URL）
• name（span 名称／操作名称，例如 "GET /api/users"）
• duration（跟踪时长，例如 100ms、2s）
• status（跟踪状态：ok、error、unset）

注意：较旧的插桩可能使用旧版 HTTP 属性名称（例如使用 span.http.status_code 代替 span.http.response.status_code）。 如果查询没有返回结果，请尝试使用 tempo_search_tags 检查存在哪些属性。

重要：

• 始终将筛选条件括在花括号 { } 中。
• 不要使用 SQL、PromQL 或 Lucene 语法。
• 不要省略属性名称中的 "resource." 或 "span." 前缀。
• 当用户提到 Kubernetes 资源类型（deployment、pod、namespace 等）时，请使用相应的 resource.k8s.* 属性，而不是 resource.service.name。

示例：

• { resource.service.name="frontend" }
• { resource.k8s.deployment.name="checkout" && span.http.response.status_code>=500 }
• { status=error && duration>2s }

如果不确定要按哪些属性筛选，请先使用 tempo_search_tags 查找可用属性，再构建查询。

• spss (integer) - 每条 trace 最多返回的匹配 span 数量。

• start (string) - 时间范围的起始时间，采用 RFC 3339 格式，例如 "2025-01-01T00:00:00Z"。 使用 "NOW" 表示当前时间。 应同时提供 start 和 end，才能搜索完整时间范围；如果省略，则只搜索近期数据中的一个较小时间窗口。

• tempoName (string) (必填) - 要查询的 Tempo 实例名称。使用 tempo_list_instances 查找可用的实例名称。

• tempoNamespace (string) (必填) - 部署 Tempo 实例的 Kubernetes 命名空间。使用 tempo_list_instances 查找可用的命名空间。

• tenant (string) - 要查询的租户。对于多租户实例，此参数为必填项。使用 tempo_list_instances 查找每个实例的可用租户。

• tempo_search_tags - 列出 Tempo 中按作用域分组的可用标签名称（属性键）。 使用此工具可发现可用于通过 tempo_search_traces 构建 TraceQL 查询的属性。 例如，此工具可能会显示诸如“service.name”（位于“resource”作用域）或“http.response.status_code”（位于“span”作用域）之类的标签名称。 若要在 TraceQL 查询中使用这些标签，请在前面加上作用域，例如“resource.service.name”或“span.http.response.status_code”。

  • end (string) - 时间范围的可选结束时间（采用 RFC 3339 格式，例如“2025-01-01T00:00:00Z”），用于筛选列出标签时纳入考虑的追踪。
  • limit (integer) - 每个作用域最多返回的标签名称数量。
  • maxStaleValues (integer) - 搜索提前停止前，连续未发现新标签名称的数据块数量上限。值越大，搜索越全面，但速度越慢。
  • query (string) - 可选的 TraceQL 查询，用于筛选列出标签时纳入考虑的追踪， 例如，{ resource.service.name="payment-service" }，只显示来自“payment-service”服务的追踪中存在的标签。
  • scope (string) - 将标签筛选到特定作用域。可选值： “resource”（服务级属性，例如 service.name）， “span”（单个 span 的属性，例如 http.response.status_code）， “intrinsic”（内置字段，例如 duration、status、name）。 若省略，则返回所有作用域中的标签。
  • start (string) - 时间范围的可选起始时间（采用 RFC 3339 格式，例如“2025-01-01T00:00:00Z”），用于筛选列出标签时纳入考虑的追踪。
  • tempoName (string) (required) - 要查询的 Tempo 实例名称。使用 tempo_list_instances 可发现可用的实例名称。
  • tempoNamespace (string) (required) - 部署 Tempo 实例的 Kubernetes 命名空间。使用 tempo_list_instances 可发现可用的命名空间。
  • tenant (string) - 要查询的租户。对于多租户实例，此参数为必填项。使用 tempo_list_instances 可发现每个实例的可用租户。

• tempo_search_tag_values - 列出 Tempo 中某个特定标签（属性键）的已知值。 使用此工具可发现某个标签对应的值，例如查找所有服务名称（“resource.service.name”的值）或所有 HTTP 方法（“span.http.request.method”的值）。 这有助于通过 tempo_search_traces 构建准确的 TraceQL 查询。

  • end (string) - 时间范围的可选结束时间（采用 RFC 3339 格式，例如“2025-01-01T00:00:00Z”），用于筛选列出值时纳入考虑的追踪。
  • limit (integer) - 最多返回的标签值数量。
  • maxStaleValues (integer) - 搜索提前停止前，连续未发现新值的数据块数量上限。值越大，搜索越全面，但速度越慢。
  • query (string) - 可选的 TraceQL 查询，用于筛选列出值时纳入考虑的追踪， 例如，{ resource.service.name="payment-service" }，只显示来自“payment-service”服务的追踪中的标签值。
  • start (string) - 时间范围的可选起始时间（采用 RFC 3339 格式，例如“2025-01-01T00:00:00Z”），用于筛选列出值时纳入考虑的追踪。
  • tag (string) (required) - 要获取值的完整限定标签名称，包含作用域前缀，例如“resource.service.name”或“span.http.response.status_code”。 使用 tempo_search_tags 可发现可用的标签名称。
  • tempoName (string) (required) - 要查询的 Tempo 实例名称。使用 tempo_list_instances 可发现可用的实例名称。
  • tempoNamespace (string) (required) - 部署 Tempo 实例的 Kubernetes 命名空间。使用 tempo_list_instances 可发现可用的命名空间。
  • tenant (string) - 要查询的租户。对于多租户实例，此参数为必填项。使用 tempo_list_instances 可发现每个实例的可用租户。

• tekton_pipelinerun_lifecycle - 管理 Tekton PipelineRun 的生命周期：使用相同的规范重新启动它，或将 spec.status 设为 Cancelled 来取消它。

  • action (string) (required) - 要执行的生命周期操作：'restart' 使用相同的规范创建新的 PipelineRun；'cancel' 将 spec.status 设为 Cancelled。
  • name (string) (required) - 要管理的 PipelineRun 名称
  • namespace (string) - PipelineRun 所属的命名空间

• tekton_pipelinerun_logs - 获取 Tekton PipelineRun 所拥有的所有 TaskRun 的日志。无需手动查找 Pod，即可使用此工具检查 PipelineRun 的执行输出。

  • name (string) (required) - 要获取日志的 PipelineRun 名称
  • namespace (string) - PipelineRun 所属的命名空间
  • step (string) - 要包含在匹配的 TaskRun 中的步骤名称
  • tail (integer) - 从每个容器日志末尾获取的行数（默认值：100）
  • task (string) - 用于筛选的 Pipeline 任务名称（tekton.dev/pipelineTask 标签）

• tekton_task_start - 通过创建引用 Tekton Task 的 TaskRun 来启动 Tekton Task

  • name (string) (required) - 要启动的 Task 名称
  • namespace (string) - Task 所属的命名空间
  • params (object) - 传递给 Task 的参数值。键为参数名称；值可以是字符串、字符串数组或对象（字符串到字符串的映射），具体取决于 Task 规范中定义的参数类型

• tekton_taskrun_restart - 使用相同的规范创建新的 TaskRun，以重新启动 Tekton TaskRun

  • name (string) (required) - 要重新启动的 TaskRun 名称
  • namespace (string) - TaskRun 所属的命名空间

• tekton_taskrun_logs - 通过解析 Tekton TaskRun 底层的 Pod，获取其日志

  • name (string) (required) - 要获取日志的 TaskRun 名称
  • namespace (string) - TaskRun 所属的命名空间
  • step (string) - 要包含的步骤名称。若省略，则返回所有步骤和 sidecar 的日志
  • tail (integer) - 从日志末尾获取的行数（可选，默认值：100）

• cluster-health-check - 对 Kubernetes/OpenShift 集群进行全面的健康状况评估
  • namespace (string) - 可选，用于限定健康检查范围的命名空间（默认值：所有命名空间）
  • check_events (string) - 是否包含近期警告/错误事件（true/false，默认值：true）

• mesh-list-applications - 列出网格命名空间中的应用

  • namespace (string) - 可选，用于筛选应用的命名空间（默认值：所有命名空间）

• list-istio-config - 列出网格命名空间中的 Istio 配置资源

  • namespace (string) - 可选，用于筛选 Istio 配置的命名空间（默认值：所有命名空间）

• mesh-list-namespaces - 列出所有命名空间及其 sidecar 注入状态和 Istio 标签

• mesh-list-services - 列出网格命名空间中的服务

  • namespace (string) - 可选，用于筛选服务的命名空间（默认值：所有命名空间）

• mesh-list-workloads - 列出网格命名空间中的工作负载

  • namespace (string) - 可选，用于筛选工作负载的命名空间（默认值：所有命名空间）

• vm-troubleshoot - 生成分步故障排查指南，用于诊断 KubeVirt VirtualMachine 问题

  • namespace (string) (required) - 要排查的 VirtualMachine 所在的命名空间
  • name (string) (required) - 要排查的 VirtualMachine 名称

• windows-golden-image - 指导如何通过 KubeVirt windows-efi-installer Tekton 流水线创建 Windows 黄金镜像

  • winImageDownloadURL (string) (required) - Microsoft Windows ISO 下载 URL（必须以 https:// 开头）
  • namespace (string) - PipelineRun 的目标命名空间
  • windowsVersion (string) - Windows 版本：10、11、2k22（默认）或 2k25
  • pipelineVersion (string) - 流水线版本（默认：latest）。如有需要，可使用特定版本，例如 0.25.0

• hco-status - 生成 HyperConverged Cluster Operator (HCO) 状态报告，该 Operator 管理 KubeVirt 及相关组件

• pipeline-troubleshoot - 收集 PipelineRun 状态、其 Pipeline 定义、TaskRun、失败或出错步骤的日志、警告事件、Pipeline-as-Code Repository，以及 TektonConfig 上下文，用于排查 Tekton 问题
  • namespace (string) (required) - 要排查的 PipelineRun 所在的命名空间
  • name (string) (required) - 要排查的 PipelineRun 名称