Tusk Drift MCP

Instructions

Implementation Reference

• src/tools/aggregateSpans.ts:79-119 (handler)

  The handler function that executes the aggregate_spans tool logic: validates input with Zod schema, calls the API client to aggregate spans, formats results into a human-readable text table.
  export async function handleAggregateSpans( client: TuskDriftApiClient, args: Record<string, unknown> ): Promise<{ content: Array<{ type: "text"; text: string }> }> { const input = aggregateSpansInputSchema.parse(args) as AggregateSpansInput; const result = await client.aggregateSpans(input); const header = `Aggregation Results (${result.results.length} rows):\n`; const rows = result.results .map((row, i) => { const groupStr = Object.entries(row.groupValues) .map(([k, v]) => `${k}=${v}`) .join(", "); const metrics: string[] = []; if (row.count !== undefined) metrics.push(`count: ${row.count}`); if (row.errorCount !== undefined) metrics.push(`errors: ${row.errorCount}`); if (row.errorRate !== undefined) metrics.push(`error rate: ${(row.errorRate * 100).toFixed(2)}%`); if (row.avgDuration !== undefined) metrics.push(`avg: ${row.avgDuration.toFixed(2)}ms`); if (row.minDuration !== undefined) metrics.push(`min: ${row.minDuration.toFixed(2)}ms`); if (row.maxDuration !== undefined) metrics.push(`max: ${row.maxDuration.toFixed(2)}ms`); if (row.p50Duration !== undefined) metrics.push(`p50: ${row.p50Duration.toFixed(2)}ms`); if (row.p95Duration !== undefined) metrics.push(`p95: ${row.p95Duration.toFixed(2)}ms`); if (row.p99Duration !== undefined) metrics.push(`p99: ${row.p99Duration.toFixed(2)}ms`); const timeBucketStr = row.timeBucket ? ` [${row.timeBucket}]` : ""; return `${i + 1}. ${groupStr || "(all)"}${timeBucketStr}\n ${metrics.join(" | ")}`; }) .join("\n\n"); return { content: [ { type: "text", text: header + rows, }, ], }; }
• src/types.ts:203-235 (schema)

  Zod schema defining the input structure and validation for the aggregate_spans tool, including filters, grouping, metrics, and limits.
  export const aggregateSpansInputSchema = z.object({ observableServiceId: z.string().optional().describe("Service ID to query (required if multiple services available)"), where: spanWhereClauseSchema.optional().describe("Filter conditions"), groupBy: z .array(z.enum(["name", "packageName", "instrumentationName", "environment", "statusCode"])) .optional() .describe("Fields to group by"), metrics: z .array( z.enum([ "count", "errorCount", "errorRate", "avgDuration", "minDuration", "maxDuration", "p50Duration", "p95Duration", "p99Duration", ]) ) .min(1) .describe("Metrics to calculate"), timeBucket: z.enum(["hour", "day", "week"]).optional().describe("Time bucket for time-series data"), orderBy: z .object({ metric: z.string(), direction: z.enum(["ASC", "DESC"]), }) .optional() .describe("Order by metric"), limit: z.number().min(1).max(100).default(20).describe("Max results"), });
• src/tools/aggregateSpans.ts:5-77 (registration)

  MCP Tool object definition for 'aggregate_spans', including name, detailed description, and JSON input schema compatible with MCP.
  export const aggregateSpansTool: Tool = { name: "aggregate_spans", description: `Calculate aggregated metrics and statistics across spans. Use this tool to: - Get latency percentiles for endpoints (p50, p95, p99) - Calculate error rates by endpoint - Get request counts over time - Compare performance across environments Examples: - Endpoint latency: groupBy = ["name"], metrics = ["count", "avgDuration", "p95Duration"] - Error rates: groupBy = ["name"], metrics = ["count", "errorCount", "errorRate"] - Hourly trends: timeBucket = "hour", metrics = ["count", "errorRate"]`, inputSchema: { type: "object", properties: { observableServiceId: { type: "string", description: "Service ID to query. Required if multiple services are available.", }, where: { type: "object", description: "Filter conditions (same as query_spans)", }, groupBy: { type: "array", description: "Fields to group by", items: { type: "string", enum: ["name", "packageName", "instrumentationName", "environment", "statusCode"], }, }, metrics: { type: "array", description: "Metrics to calculate", items: { type: "string", enum: [ "count", "errorCount", "errorRate", "avgDuration", "minDuration", "maxDuration", "p50Duration", "p95Duration", "p99Duration", ], }, }, timeBucket: { type: "string", description: "Time bucket for time-series data", enum: ["hour", "day", "week"], }, orderBy: { type: "object", description: "Order results by a metric", properties: { metric: { type: "string" }, direction: { type: "string", enum: ["ASC", "DESC"] }, }, }, limit: { type: "number", description: "Maximum results to return", default: 20, }, }, required: ["metrics"], }, };
• src/tools/index.ts:24-31 (registration)

  Central registration mapping the tool name 'aggregate_spans' to its handler function handleAggregateSpans.
  export const toolHandlers: Record<string, ToolHandler> = { query_spans: handleQuerySpans, get_schema: handleGetSchema, list_distinct_values: handleListDistinctValues, aggregate_spans: handleAggregateSpans, get_trace: handleGetTrace, get_spans_by_ids: handleGetSpansByIds, };
• src/tools/index.ts:10-17 (registration)

  Export of all tools array including the aggregateSpansTool for MCP server registration.
  export const tools: Tool[] = [ querySpansTool, getSchemaTool, listDistinctValuesTool, aggregateSpansTool, getTraceTool, getSpansByIdsTool, ];