kubesense-mcp

KubeSense MCP

每个 KubeSense 查询技能都基于此工具层。此技能负责维护共享约定——字段名称、WHERE 语法和输出格式——这样每个信号对应的技能就不必各自重新定义。

路由

用户询问……	阅读
日志、错误消息、grep	kubesense-logs
延迟、p99、请求、跨度、哪个环节出了问题	kubesense-traces
CPU、内存、磁盘、PromQL	kubesense-metrics
正在运行什么、Pod 重启、发生了哪些变化	kubesense-infra
告警——列出、调查、创建	kubesense-alerts

连接

由 kubeapi 通过 Streamable HTTP 在 /mcp 上提供服务，挂载在 /api 组之外。 使用与 REST API 相同的凭据。

# API key — recommended for agents, does not expire
claude mcp add --scope user --transport http kubesense \
  https://<your-kubesense-host>/mcp \
  --header "x-api-key: <your-api-key>"

# JWT access token — expires
claude mcp add --scope user --transport http kubesense \
  https://<your-kubesense-host>/mcp \
  --header "Authorization: Bearer <access-token>"

存活状态：GET /mcp_health。如需确认当前身份验证对应的用户，请调用 get-current-user——无需参数，开销低，根据请求凭据解析。

RBAC 会针对 logs、traces、infrastructure（metrics + nodes/pods）和 alerts 这些模块，在每次工具调用时进行解析。权限错误会指出相应模块。analyze-telemetry 会解析其子查询涉及的所有模块。

在服务端设置 MCP_LOG_LEVEL=debug，即可记录每次调用的参数载荷，而无需提高 全局日志级别。

工具（38）

发现 — 查询前调用

工具	返回内容
get-trace-or-log-fields	时间窗口内日志或追踪的字段目录
get-available-metrics	指标名称
get-metric-labels	某个指标上的标签名称

查询

工具	返回内容
search-logs	原始日志行（默认 10 条）
search-traces	原始 span 行（默认 10 条）
analyze-logs	聚合后的日志序列
analyze-traces	聚合后的 span 序列
analyze-metrics	PromQL 结果
analyze-telemetry	在一次调用中执行多个查询和公式
get-distributed-trace	一个 trace_id 的完整 span 树
execute-sql	对日志或追踪执行原始 ClickHouse SELECT 后返回的行
validate-sql	SQL 查询的试运行结果，以及将要执行的 SQL
validate-spl	SPL 查询的试运行结果，以及编译得到的 SQL
execute-spl	对日志执行 SPL 管道后返回的行

对于 analyze-* 无法表达的操作——连接、CTE 链、窗口函数、跨聚合运算——可使用 execute-sql / validate-sql。它们接受与其他工具相同的目录标签，以及发现工具未列出的少数字段。作用域受限的角色无法使用。参见 kubesense-sql。

筛选条件绝不是使用 SQL 的理由。如果条件可以写入 where 字符串（Advanced 查询语言），请使用 search-* / analyze-*：服务端会编译查询以使用索引，而 SQL 会按原样执行——在 SQL 中直接使用 body LIKE '%…%' 会扫描时间窗口内的每一行日志。

execute-spl / validate-spl 是 Logs explorer 的管道式 SPL 语言，仅适用于日志。请先验证：SPL 解析器会接受未知字段和未知函数，因此错误名称也能通过编译，只有在 execute-spl 已经付出扫描开销后才会失败。请注意，SPL 使用 STORAGE 列名（level、pod_name、cluster）——这与此处其他工具要求使用的目录标签恰好相反——而且其解析器会接受未知字段和函数，因此只有验证才能在运行查询前确认查询是否有误。参见 kubesense-spl。

清单 — 参见 kubesense-infra

list-clusters · list-nodes · get-node-detail · list-pods · get-pod-detail · list-workloads · get-workload-detail · list-issues · get-infra-issues · get-recent-changes

告警 — 参见 kubesense-alerts

list-alerts（外部 Alertmanager） · list-active-alerts（原生存储，正在触发） · list-alert-rules（规则定义） · get-alert-details · get-alert-history · list-notification-channels · find-investigation-for-alert

身份

get-current-user — 返回 username、name、email、role、auth_type。请注意， username 和 email 经常不同；list-alert-rules 的 created_by 等所有权字段会按 username 匹配。

验证 — 检查文档，不存储任何内容

validate-alert-json · validate-dashboard-json

两者都接受一个 document（JSON 对象或包含 JSON 对象的字符串），并一次性报告所有 架构问题，格式为 path / rule / message，其中 path 是指向待修正值的 JSON Pointer。 只读，可重复调用且不收费。创建文档或移交文档前，请使用对应工具检查你手动编写的内容。

写入 — 修改状态

create-alert · create-dashboard

两者都带有写入注解，并需要用户批准。调用前，请明确说明你要创建的内容。每个工具都会 根据与上方验证工具相同的架构进行验证，并报告相同的问题；因此，先验证就能将拒绝转化为修正机会。

先发现，再查询

绝不要猜名称。 无论是字段、指标、集群还是标签，都不要猜。

logs / traces:  get-trace-or-log-fields  →  search-* / analyze-*
metrics:        get-available-metrics     →  get-metric-labels  →  analyze-metrics
clusters:       list-clusters             →  anything with a "clusters" filter

这在此处格外重要，原因有二：

1. 字段名称会被拒绝，并返回错误，指出正确的标签——这很好，但前提是你要阅读错误，而不是直接重试。
2. 错误的集群名称或指标名称不会报错——它会返回空结果，无法与“值为零”区分开来。

向 get-trace-or-log-fields 传入与查询相同的时间窗口：属性键的作用范围是特定时间窗口，不同窗口中的属性键也不同。

字段名称约定

日志/追踪输入——where、required_fields、group_by_fields、fields、sort_by——只接受目录标签。存储列名会被拒绝：

field "pod_name" is a storage column; use the catalog label "instance" instead
  (call get-trace-or-log-fields to see all labels)

unknown field "service" for signal=logs; call get-trace-or-log-fields to discover
  valid fields (attributes carry an @ prefix)

概念	日志	追踪
严重级别 / 结果	type（ERROR——大写）	status（error——小写）
Pod	instance	instance
容器	container	container
节点	node	node_name
服务身份	不可用——使用 workload	service
工作负载	workload	workload
HTTP 方法	—	method
HTTP 状态	—	status_code
端点	—	resource
Span 角色	—	role
协议	—	protocol
消息文本	body	不可用
延迟	—	duration

每种信号的完整表格，包括隐藏但可接受的字段及所有存储映射，详见 references/field-catalog.md。

警告

两种信号对 node/node_name 的命名以及严重级别的名称和大小写都不一致，而且只有追踪信号具有 service。把一种信号的字段名称带到另一种信号中，是最常见的错误。

枚举值的大小写应查看发现结果中的 enum_values 列，切勿查看 example 列——示例生成器会对多个枚举字段静默返回空值（日志中的 type；追踪中的 method、protocol、status_code）。

WHERE 语法

type = ERROR AND namespace = production
status = error AND role = server
namespace IN (production, staging)
NOT (env_type = dev)
body ILIKE "%timeout%"
duration > 500
@user.id = abc-123

解析器接受的运算符： = != < > <= >= LIKE ILIKE SUBSTR_ILIKE IN——可与 AND / OR / NOT 及括号组合使用。

警告

发现结果中的 operators 列夸大了支持范围。图例中列出的 HAS_TOKEN、HAS_ALL、HAS_ANY、 LIKE_AND、ILIKE_LOG、IS_IP_ADDRESS、EXIST 都没有 WHERE 字符串语法。body HAS_TOKEN oom 会导致解析错误。在两种信号中，exist(@field) 都无法使用（它会生成带值的 EXIST，并被验证器拒绝）——不存在可用的存在性检查。

引号。 不带引号的值只能包含字母、数字、_、.、-。包含斜杠、冒号、% 或空格的值必须用双引号括起：

resource = "/api/v1/checkout"           ✓
timestamp > "2026-07-30T10:00:00Z"      ✓
resource = /api/v1/checkout             ✗ parse error

NOT IN 不是叶子运算符。 应写作 NOT (namespace IN (kube-system, default))。

属性在 WHERE 中带 @——但仅适用于日志。在追踪中，@attr 过滤器会被作为未知字段拒绝（这是服务端缺陷；工具说明声称它们可用）。追踪属性仍可通过 {"field": "db.system", "is_attribute": true} 用于 group_by_fields / fields / required_fields / sort_by——两种信号都不需要在此处加 @。

duration 输入单位为毫秒，输出单位为纳秒——详见 kubesense-traces。

选择工具

问题	工具
“显示最近的错误”	search-logs
“过去一小时有多少个错误”	analyze-logs、row_count
“结账的 p99 延迟是多少”	analyze-traces，对 duration 使用 p99
“这个请求为什么失败”	get-distributed-trace
“CPU 使用率”	get-available-metrics → analyze-metrics
“错误率是多少”	使用公式的 analyze-telemetry
“当前运行着什么／有什么故障／发生了什么变化”	清单工具——一次调用即可获取原本需要多次查询才能得到的信息

使用 analyze-* 聚合，不要对 search-* 分页。 读取原始行来计算数量速度更慢、消耗的令牌也多得多；而且由于跨集群的分页扫描按小时桶优先排序，甚至无法保证结果完整。

每个 analyze-* 工具的 query_type：range = 时间序列（趋势），instant = 每个序列一个值（总量、当前状态、前 N 项）。

时间范围采用 RFC3339 格式（2026-07-30T10:00:00Z）。从较窄范围开始（15–30 分钟），再逐步扩大。发现工具默认查询最近一小时；清单工具也一样。

多数据源查询和公式

analyze-telemetry 可在一次调用中运行多个查询并将它们组合起来。这是获取比率、错误率或百分比的唯一方法。

{
  "from_time": "2026-07-30T10:00:00Z",
  "to_time": "2026-07-30T11:00:00Z",
  "query_type": "instant",
  "queries": {
    "A": { "selectedMode": "traces", "value_operation": "row_count" },
    "B": { "selectedMode": "traces", "where": "status = error", "value_operation": "row_count" },
    "C": { "query_type": "formula", "expression": "(B/A)*100" }
  }
}

查询使用单字母标签作为键。公式条目使用 "query_type": "formula"，并通过 expression 引用其他标签。跨信号示例请参见 references/multi-query.md。

读取输出

输出有三种格式，均旨在节省令牌：

TSV（search-*、所有清单和告警列表工具）——一行 # key=value 元数据，接着是标题行，然后每条记录占一行。单元格为空表示字段不存在。## name 行用于开始带标签的子表格（例如 ## services、## silences）。

列式 JSON（所有 analyze-*）——results 按查询标签分组：

• range：共用一个 timestamps 数组（Unix 秒，仅输出一次），每个序列都包含一个未封装的 values 数组，并按位置对齐——values[i] 是 timestamps[i] 对应的值，null = 该时间桶中没有数据。
• instant：没有 timestamps；每个序列都包含一个标量 value。
• total_series / truncated 报告应用前 N 项限制之前存在的非零序列数。

含子表格的记录（get-*-detail）——标量以 field<TAB>value 行表示，嵌套数组以 ## name TSV 块表示，映射以紧凑 JSON 表示。空字段会省略。

时间戳始终为毫秒精度的 RFC3339 UTC 格式——与 from_time/to_time 接受的格式完全相同，因此可以直接将单元格复制回去作为游标。

分页

search-logs / search-traces 没有 page 或 offset。分页时请缩小 to_time 范围；时间窗口采用左闭右开，因此不会重复游标行。

取页面中的最小时间戳（日志取 timestamp，追踪取 start_timestamp），并将其原样作为下一个 to_time 传入。毫秒精度必须完全一致。

清单和告警工具支持常规分页，可使用 page/page_size（默认值为 50）或 limit/offset。

请参阅各信号对应的技能，了解会导致原始数据穷举扫描不可靠的排序注意事项；如果答案是一个数字，请优先使用聚合。

规则

1. 查询前先发现字段、指标和集群，切勿猜测。
2. 传给 get-trace-or-log-fields 的时间窗口必须与查询使用的相同。
3. 仅使用目录中的标签。字段出错时，读取建议的标签；不要用相同名称重试。
4. 不要在不同信号之间沿用字段名（node 与 node_name；type 与 status；service 仅用于 traces）。
5. 枚举值的大小写以 enum_values 为准，而非 example。
6. WHERE 运算符仅限：= != < > <= >= LIKE ILIKE SUBSTR_ILIKE IN。值包含 /、:、% 或空格时，必须加引号。使用 NOT (x IN (...))，绝不可写 x NOT IN (...)。
7. value_operation 必须是 row_count，绝不能是 count。
8. 数值使用 analyze-*，search-* 仅用于读取记录。
9. 比率和百分比使用 analyze-telemetry + 公式。
10. 空结果不等于零——报告数值前，先核实名称并扩大时间窗口。
11. create-alert 会修改状态：说明你要创建什么，并先调用 list-notification-channels，否则不会通知任何人。