hny-mcp

Instructions

Implementation Reference

• src/tools/get-trace-link.ts:30-94 (handler)

  The main handler function that executes the get_trace_link tool logic: validates inputs, fetches team slug, constructs the Honeycomb trace deep link URL with optional span and time range, and returns formatted response.

  handler: async (params: z.infer<typeof TraceDeepLinkSchema>) => {
    try {
      // Validate required parameters
      if (!params.environment) {
        throw new Error("Missing required parameter: environment");
      }
      if (!params.dataset) {
        throw new Error("Missing required parameter: dataset");
      }
      if (!params.traceId) {
        throw new Error("Missing required parameter: traceId");
      }
  
      // Get the team slug for the environment
      const teamSlug = await api.getTeamSlug(params.environment);
      
      // Start building the trace URL
      let traceUrl = `https://ui.honeycomb.io/${teamSlug}/environments/${params.environment}/trace?trace_id=${encodeURIComponent(params.traceId)}`;
      
      // Add optional parameters if provided
      if (params.spanId) {
        traceUrl += `&span=${encodeURIComponent(params.spanId)}`;
      }
      
      if (params.traceStartTs) {
        traceUrl += `&trace_start_ts=${params.traceStartTs}`;
      }
      
      if (params.traceEndTs) {
        traceUrl += `&trace_end_ts=${params.traceEndTs}`;
      }
      
      // Add dataset parameter for more specific context
      if (params.dataset) {
        // Insert the dataset before the trace part in the URL
        traceUrl = traceUrl.replace(
          `/trace?`,
          `/datasets/${encodeURIComponent(params.dataset)}/trace?`
        );
      }
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              url: traceUrl,
              environment: params.environment,
              dataset: params.dataset,
              traceId: params.traceId,
              team: teamSlug
            }, null, 2),
          },
        ],
        metadata: {
          environment: params.environment,
          dataset: params.dataset,
          traceId: params.traceId,
          team: teamSlug
        }
      };
    } catch (error) {
      return handleToolError(error, "get_trace_link");
    }
  }

• src/types/schema.ts:398-416 (schema)

  Zod schema defining the input parameters and validation for the get_trace_link tool, including environment, dataset, traceId, optional spanId and timestamps with refinement for timestamp order.

   * Schema for generating a trace deep link
   */
  export const TraceDeepLinkSchema = z.object({
    environment: z.string().min(1).trim().describe("The Honeycomb environment"),
    dataset: z.string().min(1).trim().describe("The dataset containing the trace"),
    traceId: z.string().describe("The unique trace ID"),
    spanId: z.string().optional().describe("The unique span ID to jump to within the trace"),
    traceStartTs: z.number().int().nonnegative().optional().describe("Start timestamp in Unix epoch seconds"),
    traceEndTs: z.number().int().nonnegative().optional().describe("End timestamp in Unix epoch seconds"),
  }).refine(data => {
    // If both timestamps are provided, ensure end > start
    if (data.traceStartTs !== undefined && data.traceEndTs !== undefined) {
      return data.traceEndTs > data.traceStartTs;
    }
    return true;
  }, {
    message: "End timestamp must be greater than start timestamp",
    path: ["traceEndTs"]
  });

• src/tools/get-trace-link.ts:12-96 (helper)

  Factory function that creates the complete MCP tool definition object for 'get_trace_link', including name, description, input schema, and handler function.

  export function createTraceDeepLinkTool(api: HoneycombAPI) {
    return {
      name: "get_trace_link",
      description: "Generates a direct deep link to a specific trace in the Honeycomb UI. This tool creates a URL that opens a specific distributed trace, optionally positioning to a particular span and time range. If no time range is specified, the trace must have been generated within two hours from the current time. If only the start time is provided, the end time is assumed to be 10 minutes from the start time.",
      schema: {
        environment: z.string().min(1).trim().describe("The Honeycomb environment"),
        dataset: z.string().min(1).trim().describe("The dataset containing the trace"),
        traceId: z.string().describe("The unique trace ID"),
        spanId: z.string().optional().describe("The unique span ID to jump to within the trace"),
        traceStartTs: z.number().int().nonnegative().optional().describe("Start timestamp in Unix epoch seconds"),
        traceEndTs: z.number().int().nonnegative().optional().describe("End timestamp in Unix epoch seconds")
      },
      /**
       * Handler for the get_trace_link tool
       * 
       * @param params - The parameters for the tool
       * @returns A URL for direct access to the trace in the Honeycomb UI
       */
      handler: async (params: z.infer<typeof TraceDeepLinkSchema>) => {
        try {
          // Validate required parameters
          if (!params.environment) {
            throw new Error("Missing required parameter: environment");
          }
          if (!params.dataset) {
            throw new Error("Missing required parameter: dataset");
          }
          if (!params.traceId) {
            throw new Error("Missing required parameter: traceId");
          }
  
          // Get the team slug for the environment
          const teamSlug = await api.getTeamSlug(params.environment);
          
          // Start building the trace URL
          let traceUrl = `https://ui.honeycomb.io/${teamSlug}/environments/${params.environment}/trace?trace_id=${encodeURIComponent(params.traceId)}`;
          
          // Add optional parameters if provided
          if (params.spanId) {
            traceUrl += `&span=${encodeURIComponent(params.spanId)}`;
          }
          
          if (params.traceStartTs) {
            traceUrl += `&trace_start_ts=${params.traceStartTs}`;
          }
          
          if (params.traceEndTs) {
            traceUrl += `&trace_end_ts=${params.traceEndTs}`;
          }
          
          // Add dataset parameter for more specific context
          if (params.dataset) {
            // Insert the dataset before the trace part in the URL
            traceUrl = traceUrl.replace(
              `/trace?`,
              `/datasets/${encodeURIComponent(params.dataset)}/trace?`
            );
          }
          
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify({
                  url: traceUrl,
                  environment: params.environment,
                  dataset: params.dataset,
                  traceId: params.traceId,
                  team: teamSlug
                }, null, 2),
              },
            ],
            metadata: {
              environment: params.environment,
              dataset: params.dataset,
              traceId: params.traceId,
              team: teamSlug
            }
          };
        } catch (error) {
          return handleToolError(error, "get_trace_link");
        }
      }
    };
  }

• src/tools/index.ts:25-108 (registration)

  The registerTools function that instantiates the get_trace_link tool via createTraceDeepLinkTool(api) and registers it (along with others) to the MCP server using a generic wrapper handler.

  export function registerTools(server: McpServer, api: HoneycombAPI) {
    const tools = [
      // Dataset tools
      createListDatasetsTool(api),
      createListColumnsTool(api),
  
      // Query tools
      createRunQueryTool(api),
      createAnalyzeColumnsTool(api),
  
      // Board tools
      createListBoardsTool(api),
      createGetBoardTool(api),
  
      // Marker tools
      createListMarkersTool(api),
  
      // Recipient tools
      createListRecipientsTool(api),
  
      // SLO tools
      createListSLOsTool(api),
      createGetSLOTool(api),
  
      // Trigger tools
      createListTriggersTool(api),
      createGetTriggerTool(api),
      
      // Trace tools
      createTraceDeepLinkTool(api),
      
      // Instrumentation tools
      createInstrumentationGuidanceTool(api)
    ];
  
    // Register each tool with the server
    for (const tool of tools) {
      // Register the tool with the server using type assertion to bypass TypeScript's strict type checking
      (server as any).tool(
        tool.name,
        tool.description,
        tool.schema, 
        async (args: Record<string, any>, extra: any) => {
          try {
            // Validate and ensure required fields are present before passing to handler
            if (tool.name.includes("analyze_columns") && (!args.environment || !args.dataset || !args.columns)) {
              throw new Error("Missing required fields: environment, dataset, and columns are required");
            } else if (tool.name.includes("run_query") && (!args.environment || !args.dataset)) {
              throw new Error("Missing required fields: environment and dataset are required");
            }
            
            // Use type assertion to satisfy TypeScript's type checking
            const result = await tool.handler(args as any);
            
            // If the result already has the expected format, return it directly
            if (result && typeof result === 'object' && 'content' in result) {
              return result as any;
            }
            
            // Otherwise, format the result as expected by the SDK
            return {
              content: [
                {
                  type: "text",
                  text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
                },
              ],
            } as any;
          } catch (error) {
            // Format errors to match the SDK's expected format
            return {
              content: [
                {
                  type: "text",
                  text: error instanceof Error ? error.message : String(error),
                },
              ],
              isError: true,
            } as any;
          }
        }
      );
    }
  }