Tusk Drift MCP

Instructions

Implementation Reference

• src/tools/getSchema.ts:53-94 (handler)

  The core handler function for the 'get_schema' tool. It validates the input using Zod schema, calls the API client's getSchema method, and formats the result into markdown sections for display.

  export async function handleGetSchema(
    client: TuskDriftApiClient,
    args: Record<string, unknown>
  ): Promise<{ content: Array<{ type: "text"; text: string }> }> {
    const input = getSchemaInputSchema.parse(args) as GetSchemaInput;
    const result = await client.getSchema(input);
  
    const sections: string[] = [];
  
    if (result.description) {
      sections.push(`## Description\n${result.description}`);
    }
  
    if (result.commonJsonbFields) {
      sections.push(`## Common Queryable Fields
  
  **inputValue fields:** ${result.commonJsonbFields.inputValue.join(", ") || "(none)"}
  
  **outputValue fields:** ${result.commonJsonbFields.outputValue.join(", ") || "(none)"}`);
    }
  
    if (result.inputSchema) {
      sections.push(`## Input Schema\n\`\`\`json\n${JSON.stringify(result.inputSchema, null, 2)}\n\`\`\``);
    }
  
    if (result.outputSchema) {
      sections.push(`## Output Schema\n\`\`\`json\n${JSON.stringify(result.outputSchema, null, 2)}\n\`\`\``);
    }
  
    if (result.exampleSpanRecording) {
      sections.push(`## Example Span\n\`\`\`json\n${JSON.stringify(result.exampleSpanRecording, null, 2)}\n\`\`\``);
    }
  
    return {
      content: [
        {
          type: "text",
          text: sections.join("\n\n") || "No schema information available.",
        },
      ],
    };
  }

• src/tools/getSchema.ts:5-51 (registration)

  Tool registration object defining the 'get_schema' tool, including its name, description, and JSON input schema for MCP.

  export const getSchemaTool: Tool = {
    name: "get_schema",
    description: `Get schema and structure information for span recordings on Tusk Drift.
  
  Use this tool to:
  - Understand what fields are available for a specific instrumentation type
  - See example payloads for HTTP requests, database queries, etc.
  - Learn what to filter on before querying spans
  
  Common package names:
  - http: Incoming HTTP requests (has statusCode, method, url, headers)
  - fetch: Outgoing HTTP calls
  - pg: PostgreSQL queries (has db.statement, db.name)
  - grpc: gRPC calls
  - express: Express.js middleware spans`,
    inputSchema: {
      type: "object",
      properties: {
        observableServiceId: {
          type: "string",
          description: "Service ID to query. Required if multiple services are available.",
        },
        packageName: {
          type: "string",
          description: "Package name to get schema for (e.g., 'http', 'pg', 'fetch')",
        },
        instrumentationName: {
          type: "string",
          description: "Specific instrumentation name",
        },
        name: {
          type: "string",
          description: "Span name to get schema for (e.g., '/api/users')",
        },
        showExample: {
          type: "boolean",
          description: "Include an example span with real data",
          default: true,
        },
        maxPayloadLength: {
          type: "number",
          description: "Truncate example payload strings to this length",
          default: 500,
        },
      },
    },
  };

• src/types.ts:186-193 (schema)

  Zod schema for validating inputs to the 'get_schema' tool, used in the handler for parsing arguments.

  export const getSchemaInputSchema = z.object({
    observableServiceId: z.string().optional().describe("Service ID to query (required if multiple services available)"),
    packageName: z.string().optional().describe("Package name (e.g., 'http', 'pg', 'fetch')"),
    instrumentationName: z.string().optional().describe("Instrumentation name"),
    name: z.string().optional().describe("Span name to filter by"),
    showExample: z.boolean().default(true).describe("Include an example span"),
    maxPayloadLength: z.number().min(0).default(500).describe("Truncate example payload strings"),
  });

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

  Registration of all tools including 'get_schema' (via getSchemaTool) in the tools array exported for use in the main MCP server.

  export const tools: Tool[] = [
    querySpansTool,
    getSchemaTool,
    listDistinctValuesTool,
    aggregateSpansTool,
    getTraceTool,
    getSpansByIdsTool,
  ];

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

  Mapping of tool names to their handler functions, including 'get_schema' to handleGetSchema, used by the MCP server.

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