Tusk Drift MCP

Instructions

Implementation Reference

• src/tools/getSpansByIds.ts:42-94 (handler)

  Main handler function: parses input with schema, calls API client.getSpansByIds, formats spans as markdown text response.

  export async function handleGetSpansByIds(
    client: TuskDriftApiClient,
    args: Record<string, unknown>
  ): Promise<{ content: Array<{ type: "text"; text: string }> }> {
    const input = getSpansByIdsInputSchema.parse(args) as GetSpansByIdsInput;
    const result = await client.getSpansByIds(input);
  
    if (result.spans.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No spans found for the provided IDs.`,
          },
        ],
      };
    }
  
    const spansText = result.spans
      .map((span, i) => {
        const lines = [
          `## Span ${i + 1}: ${span.name}`,
          `- **ID:** ${span.id}`,
          `- **Trace ID:** ${span.traceId}`,
          `- **Span ID:** ${span.spanId}`,
          `- **Package:** ${span.packageName}`,
          `- **Duration:** ${span.duration.toFixed(2)}ms`,
          `- **Status:** ${span.status.code === 0 ? "OK" : span.status.code === 1 ? "UNSET" : "ERROR"}`,
          `- **Timestamp:** ${span.timestamp}`,
          `- **Root Span:** ${span.isRootSpan ? "Yes" : "No"}`,
        ];
  
        if (span.inputValue) {
          lines.push(`\n**Input:**\n\`\`\`json\n${JSON.stringify(span.inputValue, null, 2)}\n\`\`\``);
        }
  
        if (span.outputValue) {
          lines.push(`\n**Output:**\n\`\`\`json\n${JSON.stringify(span.outputValue, null, 2)}\n\`\`\``);
        }
  
        return lines.join("\n");
      })
      .join("\n\n---\n\n");
  
    return {
      content: [
        {
          type: "text",
          text: `Found ${result.spans.length} spans:\n\n${spansText}`,
        },
      ],
    };
  }

• src/types.ts:244-249 (schema)

  Zod input schema defining parameters: observableServiceId, ids (array 1-20), includePayloads, maxPayloadLength.

  export const getSpansByIdsInputSchema = z.object({
    observableServiceId: z.string().optional().describe("Service ID to query (required if multiple services available)"),
    ids: z.array(z.string()).min(1).max(20).describe("Span recording IDs to fetch"),
    includePayloads: z.boolean().default(true).describe("Include inputValue/outputValue"),
    maxPayloadLength: z.number().min(0).default(500).describe("Truncate payload strings"),
  });

• src/tools/getSpansByIds.ts:5-40 (registration)

  Tool object registration: defines name, description, and inline JSON schema (mirrors Zod schema). Exported and collected in tools/index.ts for MCP server.

  export const getSpansByIdsTool: Tool = {
    name: "get_spans_by_ids",
    description: `Fetch specific span recordings by their IDs.
  
  Use this tool when you have span IDs from a previous query and need the full details including payloads.
  
  This is useful for:
  - Getting full details for spans found via query_spans
  - Examining specific requests in detail
  - Comparing multiple specific spans`,
    inputSchema: {
      type: "object",
      properties: {
        observableServiceId: {
          type: "string",
          description: "Service ID to query. Required if multiple services are available.",
        },
        ids: {
          type: "array",
          items: { type: "string" },
          description: "Span recording IDs to fetch (max 20)",
        },
        includePayloads: {
          type: "boolean",
          description: "Include full inputValue/outputValue",
          default: true,
        },
        maxPayloadLength: {
          type: "number",
          description: "Truncate payload strings to this length",
          default: 500,
        },
      },
      required: ["ids"],
    },
  };

• src/tools/index.ts:10-31 (registration)

  Central registration: adds getSpansByIdsTool to tools[] array and maps get_spans_by_ids to handleGetSpansByIds in toolHandlers. Used by src/index.ts to register with MCP server.

  export const tools: Tool[] = [
    querySpansTool,
    getSchemaTool,
    listDistinctValuesTool,
    aggregateSpansTool,
    getTraceTool,
    getSpansByIdsTool,
  ];
  
  export type ToolHandler = (
    client: TuskDriftApiClient,
    args: Record<string, unknown>
  ) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
  
  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/apiClient.ts:101-112 (helper)

  API client helper: makes HTTP POST to /api/drift/query/spans-by-id with resolved service ID and input params.

  /**
   * Get span recordings by IDs
   */
  async getSpansByIds(input: GetSpansByIdsInput): Promise<{
    spans: SpanRecording[];
  }> {
    const { observableServiceId, ...rest } = input;
    return this.request("/spans-by-id", {
      observableServiceId: this.resolveServiceId(observableServiceId),
      ...rest,
    });
  }