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,
  ];