Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/mcp-shorten-trace-ops-tool-name.md
Original file line number Diff line number Diff line change
@@ -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.
139 changes: 70 additions & 69 deletions MCP.md

Large diffs are not rendered by default.

39 changes: 23 additions & 16 deletions packages/api/src/mcp/__tests__/trace.int.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand All @@ -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 () => {
Comment thread
brandon-pereira marked this conversation as resolved.
Resolved
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();

Expand Down Expand Up @@ -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'",
Expand All @@ -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'",
Expand All @@ -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'",
Expand All @@ -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'",
Expand Down Expand Up @@ -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}'`,
Expand Down Expand Up @@ -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}'`,
Expand All @@ -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}'`,
Expand All @@ -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}'`,
Expand All @@ -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}'`,
Expand All @@ -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',
Expand Down Expand Up @@ -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}'`,
Expand Down Expand Up @@ -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}'`,
Expand Down
2 changes: 1 addition & 1 deletion packages/api/src/mcp/tools/query/builderCatalog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand Down
2 changes: 1 addition & 1 deletion packages/api/src/mcp/tools/query/serviceHealth/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 ' +
Expand Down
6 changes: 3 additions & 3 deletions packages/api/src/mcp/tools/trace/breakdown.ts
Original file line number Diff line number Diff line change
@@ -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),
Expand Down Expand Up @@ -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,
Expand All @@ -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".`,
);
}

Expand Down
2 changes: 1 addition & 1 deletion packages/api/src/mcp/tools/trace/waterfall.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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' +
Expand Down
Loading