Tusk Drift MCP

Instructions

Implementation Reference

• src/tools/listDistinctValues.ts:46-70 (handler)

  The core handler function for the list_distinct_values tool. Parses input using the schema, calls the API client to fetch distinct values, formats them by frequency with counts, and returns formatted text response.

  export async function handleListDistinctValues(
    client: TuskDriftApiClient,
    args: Record<string, unknown>
  ): Promise<{ content: Array<{ type: "text"; text: string }> }> {
    const input = listDistinctValuesInputSchema.parse(args) as ListDistinctValuesInput;
    const result = await client.listDistinctValues(input);
  
    const header = `Distinct values for "${result.field}" (${result.values.length} unique values):\n`;
  
    const valuesList = result.values
      .map((v, i) => {
        const valueStr = typeof v.value === "string" ? v.value : JSON.stringify(v.value);
        return `${i + 1}. ${valueStr} (${v.count} occurrences)`;
      })
      .join("\n");
  
    return {
      content: [
        {
          type: "text",
          text: header + valuesList,
        },
      ],
    };
  }

• src/tools/listDistinctValues.ts:5-44 (registration)

  MCP Tool object definition with name, description, and input schema for list_distinct_values. Exported and collected into tools array.

  export const listDistinctValuesTool: Tool = {
    name: "list_distinct_values",
    description: `List unique values for a field, ordered by frequency.
  
  Use this tool to:
  - Discover available endpoints (field: "name")
  - See all instrumentation packages in use (field: "packageName")
  - Find unique environments (field: "environment")
  - Explore JSONB values like status codes (field: "outputValue.statusCode")
  
  This helps you understand what values exist before building specific queries.`,
    inputSchema: {
      type: "object",
      properties: {
        observableServiceId: {
          type: "string",
          description: "Service ID to query. Required if multiple services are available.",
        },
        field: {
          type: "string",
          description:
            "Field to get distinct values for. Can be a column name or JSONB path (e.g., 'name', 'packageName', 'outputValue.statusCode')",
        },
        where: {
          type: "object",
          description: "Optional filter to scope the distinct values",
        },
        jsonbFilters: {
          type: "array",
          description: "Optional JSONB filters to scope the distinct values",
        },
        limit: {
          type: "number",
          description: "Maximum distinct values to return (default 50)",
          default: 50,
        },
      },
      required: ["field"],
    },
  };

• src/types.ts:195-201 (schema)

  Zod input schema used for validation in the handler and registered for MCP tool input validation.

  export const listDistinctValuesInputSchema = z.object({
    observableServiceId: z.string().optional().describe("Service ID to query (required if multiple services available)"),
    field: z.string().describe("Field to get distinct values for (e.g., 'name', 'packageName', 'outputValue.statusCode')"),
    where: spanWhereClauseSchema.optional().describe("Filter conditions"),
    jsonbFilters: z.array(jsonbFilterSchema).optional().describe("JSONB path filters"),
    limit: z.number().min(1).max(100).default(50).describe("Max distinct values to return"),
  });

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

  Central registration: adds listDistinctValuesTool to tools array and maps 'list_distinct_values' to its handler function. Used by main server to register all tools.

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