diff --git a/.changeset/mcp-shorten-trace-ops-tool-name.md b/.changeset/mcp-shorten-trace-ops-tool-name.md new file mode 100644 index 000000000..12153bc44 --- /dev/null +++ b/.changeset/mcp-shorten-trace-ops-tool-name.md @@ -0,0 +1,9 @@ +--- +'@hyperdx/api': patch +--- + +fix(mcp): Rename `clickstack_trace_top_time_consuming_operations` to `clickstack_trace_top_time_consuming_ops` + +The old name was the longest MCP tool name and exceeded the tool-name length +limit some MCP clients enforce. Clients that call the tool by its old name +need to switch to the new one. diff --git a/MCP.md b/MCP.md index b5b070344..57ec8dfdf 100644 --- a/MCP.md +++ b/MCP.md @@ -134,56 +134,59 @@ with: ## Available Tools -| Tool | Description | -| ----------------------------- | -------------------------------------------------------------------------------------------- | -| `clickstack_list_sources` | List all data sources and connections as a lightweight catalog (IDs, names, kinds) | -| `clickstack_describe_source` | Full column schema, attribute keys, sampled low-cardinality values, and a round-trippable `config` block (the exact shape `clickstack_save_source` accepts, incl. correlation IDs) for a single source; for metric sources also returns a per-kind metric-name sample | -| `clickstack_describe_table` | Inspect a ClickHouse table that is not a registered source: columns, keys, engine, skipping indices, approximate size, and an optional row sample. Without a table, lists the tables in a database (paginated) | -| `clickstack_save_source` | Create (omit id) or update (provide id) a data source (log, trace, session, metric, or promql) so shipped telemetry becomes queryable. To clone a source, read its `config` from `clickstack_describe_source`, drop `id`, and pass it here | -| `clickstack_delete_source` | Permanently delete a data source by ID | -| `clickstack_list_metrics` | Paginated catalog of metric names on a metric source with optional kind / namePattern / time-window filters | -| `clickstack_describe_metric` | Per-metric drill-down: kind(s), unit, description, attribute keys per map column, and sampled values | -| `clickstack_service_health` | One-call service health on a trace source: throughput, error rate, p50/p95 and top errors per service, compared with yesterday and ranked worst first | -| `clickstack_timeseries` | Plot metrics over time as a line or stacked bar chart (works on log, trace, and metric sources) | -| `clickstack_table` | Compute aggregated metrics as a table, single number, or pie chart (works on log, trace, and metric sources) | -| `clickstack_search` | Browse individual log, event, or trace rows | -| `clickstack_event_patterns` | Discover the most common log messages and event patterns using Drain clustering | -| `clickstack_event_deltas` | Compare two row groups and rank properties by how their value distributions differ | -| `clickstack_emerging_signals` | Detect NEW or GONE log/event patterns between a baseline and a current window (two-window Drain novelty diff) | -| `clickstack_sql` | Execute raw ClickHouse SQL for advanced queries (JOINs, CTEs, sub-queries); pass `queries` to run up to 10 in parallel | -| `clickstack_promql` | Run a PromQL expression (range or instant) against a PromQL source. Only registered when PromQL is enabled | -| `clickstack_get_dashboard` | List all dashboards or get full detail for a specific dashboard | -| `clickstack_save_dashboard` | Create or update a dashboard with tiles (charts, tables, numbers, search, markdown) | -| `clickstack_delete_dashboard` | Permanently delete a dashboard and its attached alerts | -| `clickstack_query_tile` | Execute the query for a specific dashboard tile to validate results | -| `clickstack_query_tiles` | Batch-validate many dashboard tiles in one call, returning a per-tile success/failure summary | -| `clickstack_get_saved_search` | List all saved searches or get full detail for a specific saved search | -| `clickstack_save_saved_search` | Create or update a saved search (reusable query against a data source) | -| `clickstack_get_alert` | List alerts (summary) or get full detail with evaluation history; filter by state | -| `clickstack_save_alert` | Create a new alert or update an existing one | -| `clickstack_trace_waterfall` | Fetch all spans in a single trace as a parent/child waterfall tree with optional correlated logs | -| `clickstack_trace_top_time_consuming_operations` | Aggregate breakdown of child operations by cumulative time across matching parent traces | -| `clickstack_get_webhook` | List available webhook destinations for use as alert notification channels | -| `clickstack_save_webhook` | Create (omit id) or update (provide id) a webhook notification destination (slack, generic, or incidentio) | -| `clickstack_delete_webhook` | Permanently delete a webhook by ID (blocked while alerts still reference it) | +| Tool | Description | +| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `clickstack_list_sources` | List all data sources and connections as a lightweight catalog (IDs, names, kinds) | +| `clickstack_describe_source` | Full column schema, attribute keys, sampled low-cardinality values, and a round-trippable `config` block (the exact shape `clickstack_save_source` accepts, incl. correlation IDs) for a single source; for metric sources also returns a per-kind metric-name sample | +| `clickstack_describe_table` | Inspect a ClickHouse table that is not a registered source: columns, keys, engine, skipping indices, approximate size, and an optional row sample. Without a table, lists the tables in a database (paginated) | +| `clickstack_save_source` | Create (omit id) or update (provide id) a data source (log, trace, session, metric, or promql) so shipped telemetry becomes queryable. To clone a source, read its `config` from `clickstack_describe_source`, drop `id`, and pass it here | +| `clickstack_delete_source` | Permanently delete a data source by ID | +| `clickstack_list_metrics` | Paginated catalog of metric names on a metric source with optional kind / namePattern / time-window filters | +| `clickstack_describe_metric` | Per-metric drill-down: kind(s), unit, description, attribute keys per map column, and sampled values | +| `clickstack_service_health` | One-call service health on a trace source: throughput, error rate, p50/p95 and top errors per service, compared with yesterday and ranked worst first | +| `clickstack_timeseries` | Plot metrics over time as a line or stacked bar chart (works on log, trace, and metric sources) | +| `clickstack_table` | Compute aggregated metrics as a table, single number, or pie chart (works on log, trace, and metric sources) | +| `clickstack_search` | Browse individual log, event, or trace rows | +| `clickstack_event_patterns` | Discover the most common log messages and event patterns using Drain clustering | +| `clickstack_event_deltas` | Compare two row groups and rank properties by how their value distributions differ | +| `clickstack_emerging_signals` | Detect NEW or GONE log/event patterns between a baseline and a current window (two-window Drain novelty diff) | +| `clickstack_sql` | Execute raw ClickHouse SQL for advanced queries (JOINs, CTEs, sub-queries); pass `queries` to run up to 10 in parallel | +| `clickstack_promql` | Run a PromQL expression (range or instant) against a PromQL source. Only registered when PromQL is enabled | +| `clickstack_get_dashboard` | List all dashboards or get full detail for a specific dashboard | +| `clickstack_save_dashboard` | Create or update a dashboard with tiles (charts, tables, numbers, search, markdown) | +| `clickstack_delete_dashboard` | Permanently delete a dashboard and its attached alerts | +| `clickstack_query_tile` | Execute the query for a specific dashboard tile to validate results | +| `clickstack_query_tiles` | Batch-validate many dashboard tiles in one call, returning a per-tile success/failure summary | +| `clickstack_get_saved_search` | List all saved searches or get full detail for a specific saved search | +| `clickstack_save_saved_search` | Create or update a saved search (reusable query against a data source) | +| `clickstack_get_alert` | List alerts (summary) or get full detail with evaluation history; filter by state | +| `clickstack_save_alert` | Create a new alert or update an existing one | +| `clickstack_trace_waterfall` | Fetch all spans in a single trace as a parent/child waterfall tree with optional correlated logs | +| `clickstack_trace_top_time_consuming_ops` | Aggregate breakdown of child operations by cumulative time across matching parent traces | +| `clickstack_get_webhook` | List available webhook destinations for use as alert notification channels | +| `clickstack_save_webhook` | Create (omit id) or update (provide id) a webhook notification destination (slack, generic, or incidentio) | +| `clickstack_delete_webhook` | Permanently delete a webhook by ID (blocked while alerts still reference it) | > **Maintainers:** when adding/removing/renaming a query tool, update this table > and — for builder (non-SQL) tools — the hand-curated `BUILDER_TOOLS_LIST` in -> `packages/api/src/mcp/tools/query/builderCatalog.ts`. It isn't auto-derived, so -> it drifts silently. +> `packages/api/src/mcp/tools/query/builderCatalog.ts`. It isn't auto-derived, +> so it drifts silently. ### Metric Sources `clickstack_timeseries`, `clickstack_table`, and the dashboard builder tile -tools accept metric sources transparently. Each `select` item on a metric -query must set `metricType` (`"gauge"`, `"sum"`, `"histogram"`, or -`"exponential histogram"`) and -`metricName` (the OTel metric name, e.g. `system.cpu.utilization`). -`valueExpression` defaults to `"Value"` when omitted, so a typical metric -series looks like: +tools accept metric sources transparently. Each `select` item on a metric query +must set `metricType` (`"gauge"`, `"sum"`, `"histogram"`, or +`"exponential histogram"`) and `metricName` (the OTel metric name, e.g. +`system.cpu.utilization`). `valueExpression` defaults to `"Value"` when omitted, +so a typical metric series looks like: ```jsonc -{ "aggFn": "avg", "metricType": "gauge", "metricName": "system.cpu.utilization" } +{ + "aggFn": "avg", + "metricType": "gauge", + "metricName": "system.cpu.utilization", +} ``` Per-kind aggregation guidance: @@ -191,36 +194,34 @@ Per-kind aggregation guidance: - **Gauge**: `avg`, `last_value`, `min`, or `max`. Set `"isDelta": true` for Prometheus-style delta over each bucket. - **Sum (counter)**: `"increase"` returns the per-bucket counter increase - (reset-aware), or `sum` / `avg` on the computed rate. `increase` combined - with `groupBy` is capped at the top 20 groups by the renderer; the tool - emits a neutral hint when the cap may apply. + (reset-aware), or `sum` / `avg` on the computed rate. `increase` combined with + `groupBy` is capped at the top 20 groups by the renderer; the tool emits a + neutral hint when the cap may apply. - **Histogram**: `"quantile"` with `level` ∈ {0.5, 0.9, 0.95, 0.99} for percentiles, or `"count"` for the total bucket count. -- **Exponential histogram**: `"quantile"` with `level` ∈ - {0.5, 0.9, 0.95, 0.99} for percentiles, or `"count"` for the total bucket - count. +- **Exponential histogram**: `"quantile"` with `level` ∈ {0.5, 0.9, 0.95, 0.99} + for percentiles, or `"count"` for the total bucket count. `summary` metrics are not yet supported by the query renderer. Discovery workflow for metrics: -1. `clickstack_list_sources` to find the metric source ID and its - `metricTables` map. -2. `clickstack_describe_source` to see columns, attribute keys, and a - per-kind metric-name sample. -3. `clickstack_list_metrics` for paginated catalog access with optional - kind / namePattern / time-window filters; pass `nextCursor` unchanged - for the next page. -4. `clickstack_describe_metric` to drill into a specific metric and - discover its attribute keys + sampled values before authoring queries. +1. `clickstack_list_sources` to find the metric source ID and its `metricTables` + map. +2. `clickstack_describe_source` to see columns, attribute keys, and a per-kind + metric-name sample. +3. `clickstack_list_metrics` for paginated catalog access with optional kind / + namePattern / time-window filters; pass `nextCursor` unchanged for the next + page. +4. `clickstack_describe_metric` to drill into a specific metric and discover its + attribute keys + sampled values before authoring queries. 5. `clickstack_timeseries` / `clickstack_table` to chart the metric. ### PromQL Sources Available when PromQL is enabled for the deployment (self-hosted: the API's -`ENABLE_PROMQL` setting). With it off, PromQL sources, tiles, label filters, -the `clickstack_promql` tool and the PromQL prompt sections are all hidden -from MCP. +`ENABLE_PROMQL` setting). With it off, PromQL sources, tiles, label filters, the +`clickstack_promql` tool and the PromQL prompt sections are all hidden from MCP. A source with `kind: "promql"` holds Prometheus metrics, either on a Prometheus-compatible endpoint or in a ClickHouse `TimeSeries` table. The @@ -231,23 +232,23 @@ builder tools do not read it; use PromQL: 2. `clickstack_describe_source` lists its metric names and label names. 3. `clickstack_promql` runs an expression. A `range` query (default) returns `{ __hdx_time_bucket, series_name, value }` rows plus `seriesLabels`; an - `instant` query evaluates at `endTime` and returns one row per series with - a column per label. `granularity` sets the step and `$__interval` in the - same `" "` format PromQL tiles use. + `instant` query evaluates at `endTime` and returns one row per series with a + column per label. `granularity` sets the step and `$__interval` in the same + `" "` format PromQL tiles use. 4. `clickstack_save_dashboard` with a `configType: "promql"` tile keeps the - chart; `clickstack_query_tile` returns the same rows for the same - expression and granularity. `PROMETHEUS_LABEL` filters give the dashboard - a label dropdown that tiles reference as `{job=~"$job"}`. + chart; `clickstack_query_tile` returns the same rows for the same expression + and granularity. `PROMETHEUS_LABEL` filters give the dashboard a label + dropdown that tiles reference as `{job=~"$job"}`. ```jsonc { "sourceId": "", "expression": "sum by (job) (rate(http_requests_total[$__rate_interval]))", "startTime": "2026-01-01T00:00:00Z", - "endTime": "2026-01-01T01:00:00Z" + "endTime": "2026-01-01T01:00:00Z", } ``` -The `$__interval`, `$__rate_interval` and `$__range` macros expand as they do -in a PromQL tile. Dashboard variables do not resolve in `clickstack_promql`; -write the value inline. +The `$__interval`, `$__rate_interval` and `$__range` macros expand as they do in +a PromQL tile. Dashboard variables do not resolve in `clickstack_promql`; write +the value inline. diff --git a/packages/api/src/mcp/__tests__/trace.int.test.ts b/packages/api/src/mcp/__tests__/trace.int.test.ts index 722af8b2b..3c72c0439 100644 --- a/packages/api/src/mcp/__tests__/trace.int.test.ts +++ b/packages/api/src/mcp/__tests__/trace.int.test.ts @@ -159,6 +159,13 @@ describe('MCP Trace Tools', () => { // ─── Schema serialization ────────────────────────────────────────────────── describe('schema serialization', () => { + // Some MCP clients cap tool name length, often after prefixing the server name. + it('should keep every tool name within 40 characters', async () => { + const { tools } = await client.listTools(); + const tooLong = tools.map(t => t.name).filter(name => name.length > 40); + expect(tooLong).toEqual([]); + }); + it('should expose clickstack_trace_waterfall with expected properties', async () => { const { tools } = await client.listTools(); const tool = tools.find(t => t.name === 'clickstack_trace_waterfall'); @@ -174,10 +181,10 @@ describe('MCP Trace Tools', () => { expect(tool!.inputSchema.required).toContain('sourceId'); }); - it('should expose clickstack_trace_top_time_consuming_operations with expected properties', async () => { + it('should expose clickstack_trace_top_time_consuming_ops with expected properties', async () => { const { tools } = await client.listTools(); const tool = tools.find( - t => t.name === 'clickstack_trace_top_time_consuming_operations', + t => t.name === 'clickstack_trace_top_time_consuming_ops', ); expect(tool).toBeDefined(); @@ -1050,13 +1057,13 @@ describe('MCP Trace Tools', () => { }); }); - // ─── clickstack_trace_top_time_consuming_operations ─────────────────────────── + // ─── clickstack_trace_top_time_consuming_ops ─────────────────────────── - describe('clickstack_trace_top_time_consuming_operations', () => { + describe('clickstack_trace_top_time_consuming_ops', () => { it('should return error for non-existent source', async () => { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: '000000000000000000000000', parentFilter: "ServiceName = 'api-gateway'", @@ -1071,7 +1078,7 @@ describe('MCP Trace Tools', () => { it('should return error for non-trace source', async () => { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: logSource._id.toString(), parentFilter: "ServiceName = 'api-gateway'", @@ -1086,7 +1093,7 @@ describe('MCP Trace Tools', () => { it('should return error for invalid time range', async () => { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: traceSource._id.toString(), parentFilter: "ServiceName = 'api-gateway'", @@ -1101,7 +1108,7 @@ describe('MCP Trace Tools', () => { it('should return empty operations when no traces match', async () => { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: traceSource._id.toString(), parentFilter: "ServiceName = 'nonexistent-service'", @@ -1208,7 +1215,7 @@ describe('MCP Trace Tools', () => { it('should break down child operations ranked by total time', async () => { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: traceSource._id.toString(), parentFilter: `ServiceName = '${PARENT_SVC}' AND SpanName = '${PARENT_OP}'`, @@ -1245,7 +1252,7 @@ describe('MCP Trace Tools', () => { // Only trace 2 has a parent >= 850ms (900ms) const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: traceSource._id.toString(), parentFilter: `ServiceName = '${PARENT_SVC}' AND SpanName = '${PARENT_OP}'`, @@ -1270,7 +1277,7 @@ describe('MCP Trace Tools', () => { it('should respect topN parameter', async () => { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: traceSource._id.toString(), parentFilter: `ServiceName = '${PARENT_SVC}' AND SpanName = '${PARENT_OP}'`, @@ -1295,7 +1302,7 @@ describe('MCP Trace Tools', () => { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: traceSource._id.toString(), parentFilter: `ServiceName = '${PARENT_SVC}' AND SpanName = '${PARENT_OP}'`, @@ -1320,7 +1327,7 @@ describe('MCP Trace Tools', () => { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: traceSource._id.toString(), parentFilter: `ServiceName = '${PARENT_SVC}' AND SpanName = '${PARENT_OP}'`, @@ -1340,7 +1347,7 @@ describe('MCP Trace Tools', () => { it('should return error for invalid parentFilter SQL', async () => { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: traceSource._id.toString(), parentFilter: 'INVALID SQL @@@ SYNTAX', @@ -1370,7 +1377,7 @@ describe('MCP Trace Tools', () => { try { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: traceSource._id.toString(), parentFilter: `ServiceName = '${PARENT_SVC}' AND SpanName = '${PARENT_OP}'`, @@ -1438,7 +1445,7 @@ describe('MCP Trace Tools', () => { try { const result = await callTool( client, - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { sourceId: traceSource._id.toString(), parentFilter: `ServiceName = '${PARENT_SVC}' AND SpanName = '${PARENT_OP}'`, diff --git a/packages/api/src/mcp/tools/query/builderCatalog.ts b/packages/api/src/mcp/tools/query/builderCatalog.ts index ec195b744..ff79e655d 100644 --- a/packages/api/src/mcp/tools/query/builderCatalog.ts +++ b/packages/api/src/mcp/tools/query/builderCatalog.ts @@ -14,7 +14,7 @@ export const BUILDER_TOOLS_LIST = [ ' • clickstack_event_deltas — attributes that differ between two row groups', ' • clickstack_emerging_signals — patterns new or gone vs a baseline window', ' • clickstack_trace_waterfall — one trace as a parent/child span tree', - ' • clickstack_trace_top_time_consuming_operations — slowest child operations in a trace', + ' • clickstack_trace_top_time_consuming_ops — slowest child operations in a trace', ].join('\n'); /** When raw SQL is actually warranted. */ diff --git a/packages/api/src/mcp/tools/query/serviceHealth/index.ts b/packages/api/src/mcp/tools/query/serviceHealth/index.ts index d45d08258..85cd56342 100644 --- a/packages/api/src/mcp/tools/query/serviceHealth/index.ts +++ b/packages/api/src/mcp/tools/query/serviceHealth/index.ts @@ -51,7 +51,7 @@ const DESCRIPTION = 'For a flagged service, check its own runtime metrics (memory, GC, CPU, ' + 'restarts by pod) on the metric source before blaming dependencies, then ' + 'use clickstack_event_deltas and ' + - 'clickstack_trace_top_time_consuming_operations.\n\n' + + 'clickstack_trace_top_time_consuming_ops.\n\n' + 'CALIBRATION: flags fire only past fixed thresholds (see `usage` in the ' + 'response); smaller swings are usually normal variance, and no flags is ' + 'a valid result for a routine check. Thresholds apply to service-wide ' + diff --git a/packages/api/src/mcp/tools/trace/breakdown.ts b/packages/api/src/mcp/tools/trace/breakdown.ts index e480c2a56..ea4e0c5a6 100644 --- a/packages/api/src/mcp/tools/trace/breakdown.ts +++ b/packages/api/src/mcp/tools/trace/breakdown.ts @@ -1,5 +1,5 @@ /** - * clickstack_trace_top_time_consuming_operations + * clickstack_trace_top_time_consuming_ops * * Aggregate counterpart to clickstack_trace_waterfall. Given a parent-span * filter (a service + operation, optionally constrained to slow durations), @@ -62,7 +62,7 @@ export function registerTraceBreakdown({ const { teamId } = context; registerTool( - 'clickstack_trace_top_time_consuming_operations', + 'clickstack_trace_top_time_consuming_ops', { title: 'Top Time-Consuming Operations Across Matching Traces', annotations: READ_ONLY_TOOL, @@ -86,7 +86,7 @@ export function registerTraceBreakdown({ } if (source.kind !== SourceKind.Trace) { return mcpUserError( - `Source ${input.sourceId} is kind="${source.kind}". clickstack_trace_top_time_consuming_operations requires a source of kind="trace".`, + `Source ${input.sourceId} is kind="${source.kind}". clickstack_trace_top_time_consuming_ops requires a source of kind="trace".`, ); } diff --git a/packages/api/src/mcp/tools/trace/waterfall.ts b/packages/api/src/mcp/tools/trace/waterfall.ts index 46d9125a1..e7760f6be 100644 --- a/packages/api/src/mcp/tools/trace/waterfall.ts +++ b/packages/api/src/mcp/tools/trace/waterfall.ts @@ -318,7 +318,7 @@ export function registerTraceWaterfall({ "instead of writing TraceId self-JOINs in raw SQL; it uses the source's " + 'configured trace, span, and parent-span ID expressions.\n\n' + 'NOT FOR AGGREGATE QUESTIONS. "Where does the time go across many slow traces ' + - 'of operation X" is clickstack_trace_top_time_consuming_operations, called ' + + 'of operation X" is clickstack_trace_top_time_consuming_ops, called ' + 'once per (service, operation) with minParentDurationMs. Use this tool for a ' + 'single concrete example, typically after that breakdown has pointed at a ' + 'suspicious operation.\n\n' +