hny-mcp

Instructions

Implementation Reference

• src/tools/analyze-columns.ts:41-174 (handler)

  The main handler function for the 'analyze_columns' tool. It validates inputs, calls the API to perform column analysis, processes the results to compute statistics, top values, cardinality, and returns a formatted JSON response.
  handler: async (params: z.infer<typeof ColumnAnalysisSchema>) => { 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.columns || params.columns.length === 0) { throw new Error("Missing required parameter: columns"); } if (params.columns.length > 10) { throw new Error("Too many columns requested. Maximum is 10."); } // Execute the analysis via the API const result = await api.analyzeColumns(params.environment, params.dataset, params); // Initialize the response const simplifiedResponse: SimplifiedColumnAnalysis = { columns: params.columns, count: result.data?.results?.length || 0, totalEvents: 0, // Will be populated below if available }; // Add top values if we have results if (result.data?.results && result.data.results.length > 0) { const results = result.data.results as QueryResultValue[]; const firstResult = results[0]; try { // Calculate total events across all results const totalCount = results.reduce((sum, row) => { const count = row.COUNT as number | undefined; // Only add if it's a number, otherwise use 0 return sum + (typeof count === 'number' ? count : 0); }, 0); simplifiedResponse.totalEvents = totalCount; // Add top values with their counts and percentages simplifiedResponse.topValues = results.map(row => { // For multi-column analysis, combine values into a descriptive string const combinedValue = params.columns .map(col => { const colValue = row[col] !== undefined ? row[col] : null; return `${col}: ${colValue}`; }) .join(', '); const count = typeof row.COUNT === 'number' ? row.COUNT : 0; return { value: combinedValue, count, percentage: totalCount > 0 ? ((count / totalCount) * 100).toFixed(2) + '%' : '0%' }; }); // Initialize stats container for each numeric column const numericStats: Record<string, NumericStatsWithInterpretation> = {}; // Process numeric metrics for each column if available if (firstResult) { params.columns.forEach(column => { // Check if we have numeric metrics for this column const avgKey = `AVG(${column})`; if (avgKey in firstResult) { const stats: NumericStatistics = {}; // Extract metrics for this column if (typeof firstResult[avgKey] === 'number') stats.avg = firstResult[avgKey] as number; if (typeof firstResult[`P95(${column})`] === 'number') stats.p95 = firstResult[`P95(${column})`] as number; if (typeof firstResult[`MAX(${column})`] === 'number') stats.max = firstResult[`MAX(${column})`] as number; if (typeof firstResult[`MIN(${column})`] === 'number') stats.min = firstResult[`MIN(${column})`] as number; // Calculate range if we have min and max if (stats.min !== undefined && stats.max !== undefined) { stats.range = stats.max - stats.min; } // Only add if we have at least one stat if (Object.keys(stats).length > 0) { numericStats[column] = { ...stats, interpretation: generateInterpretation(stats, column) } as NumericStatsWithInterpretation; } } }); } // Add stats if we have any if (Object.keys(numericStats).length > 0) { simplifiedResponse.stats = numericStats; } // Add cardinality information (unique combinations of values) const uniqueValueCombinations = new Set(); results.forEach(row => { const combinationKey = params.columns .map(col => `${col}:${row[col] !== undefined ? row[col] : 'null'}`) .join('|'); uniqueValueCombinations.add(combinationKey); }); const uniqueCount = uniqueValueCombinations.size; simplifiedResponse.cardinality = { uniqueCount, classification: getCardinalityClassification(uniqueCount) }; } catch (processingError) { // Handle errors during result processing, but still return partial results console.error("Error processing column analysis results:", processingError); simplifiedResponse.processingError = `Error processing results: ${processingError instanceof Error ? processingError.message : String(processingError)}`; } } return { content: [ { type: "text", text: JSON.stringify(simplifiedResponse, null, 2), }, ], }; } catch (error) { return handleToolError(error, "analyze_columns"); } }
• src/types/schema.ts:215-220 (schema)

  Zod schema defining the input parameters for the analyze_columns tool: environment, dataset, columns (array 1-10), optional timeRange.
  export const ColumnAnalysisSchema = z.object({ environment: z.string().min(1).trim().describe("The Honeycomb environment containing the dataset"), dataset: z.string().min(1).trim().describe("The dataset containing the column to analyze"), columns: z.array(z.string()).min(1).max(10).describe("The names of the columns to analyze"), timeRange: z.number().positive().optional().describe("Time range in seconds to analyze. Default is 2 hours."), });
• src/tools/index.ts:25-108 (registration)

  The registerTools function imports and creates the analyze_columns tool (line 33), adds it to the tools array, and registers it with the MCP server in the loop, including specific validation for analyze_columns.
  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; } } ); } }
• src/api/client.ts:513-579 (helper)

  HoneycombAPI method called by the tool handler to execute the actual column analysis query on the Honeycomb API, building the AnalysisQuery with breakdowns, calculations, and fetching results.
  async analyzeColumns( environment: string, datasetSlug: string, params: z.infer<typeof ColumnAnalysisSchema>, ) { // Get column information for each requested column const columnPromises = params.columns.map(columnName => this.getColumnByName(environment, datasetSlug, columnName) ); const columns = await Promise.all(columnPromises); const query: AnalysisQuery = { calculations: [{ op: "COUNT" }], breakdowns: [...params.columns], time_range: params.timeRange || 3600, limit: 10, }; // Only add orders if we have columns if (params.columns && params.columns.length > 0) { query.orders = [ { column: params.columns[0] as string, // Force type assertion order: "descending", } ]; } // Add numeric calculations for any numeric columns const numericColumns = columns.filter( col => col.type === "integer" || col.type === "float" ); numericColumns.forEach(column => { const numericCalculations: QueryCalculation[] = [ { op: "AVG", column: column.key_name }, { op: "P95", column: column.key_name }, { op: "MAX", column: column.key_name }, { op: "MIN", column: column.key_name }, ]; if (!query.calculations) { query.calculations = []; } query.calculations.push(...numericCalculations); }); try { const results = await this.queryAndWaitForResults( environment, datasetSlug, query, ); return { data: { results: results.data?.results || [], series: results.data?.series || [], }, links: results.links, }; } catch (error) { throw new Error( `Column analysis failed: ${error instanceof Error ? error.message : "Unknown error"}`, ); } }
• src/tools/analyze-columns.ts:30-176 (helper)

  Factory function that creates the tool object with name, description, schema, and handler for registration.
  export function createAnalyzeColumnsTool(api: HoneycombAPI) { return { name: "analyze_columns", description, schema: ColumnAnalysisSchema.shape, /** * Handles the analyze_column tool request * * @param params - The parameters for the column analysis * @returns A formatted response with column analysis data */ handler: async (params: z.infer<typeof ColumnAnalysisSchema>) => { 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.columns || params.columns.length === 0) { throw new Error("Missing required parameter: columns"); } if (params.columns.length > 10) { throw new Error("Too many columns requested. Maximum is 10."); } // Execute the analysis via the API const result = await api.analyzeColumns(params.environment, params.dataset, params); // Initialize the response const simplifiedResponse: SimplifiedColumnAnalysis = { columns: params.columns, count: result.data?.results?.length || 0, totalEvents: 0, // Will be populated below if available }; // Add top values if we have results if (result.data?.results && result.data.results.length > 0) { const results = result.data.results as QueryResultValue[]; const firstResult = results[0]; try { // Calculate total events across all results const totalCount = results.reduce((sum, row) => { const count = row.COUNT as number | undefined; // Only add if it's a number, otherwise use 0 return sum + (typeof count === 'number' ? count : 0); }, 0); simplifiedResponse.totalEvents = totalCount; // Add top values with their counts and percentages simplifiedResponse.topValues = results.map(row => { // For multi-column analysis, combine values into a descriptive string const combinedValue = params.columns .map(col => { const colValue = row[col] !== undefined ? row[col] : null; return `${col}: ${colValue}`; }) .join(', '); const count = typeof row.COUNT === 'number' ? row.COUNT : 0; return { value: combinedValue, count, percentage: totalCount > 0 ? ((count / totalCount) * 100).toFixed(2) + '%' : '0%' }; }); // Initialize stats container for each numeric column const numericStats: Record<string, NumericStatsWithInterpretation> = {}; // Process numeric metrics for each column if available if (firstResult) { params.columns.forEach(column => { // Check if we have numeric metrics for this column const avgKey = `AVG(${column})`; if (avgKey in firstResult) { const stats: NumericStatistics = {}; // Extract metrics for this column if (typeof firstResult[avgKey] === 'number') stats.avg = firstResult[avgKey] as number; if (typeof firstResult[`P95(${column})`] === 'number') stats.p95 = firstResult[`P95(${column})`] as number; if (typeof firstResult[`MAX(${column})`] === 'number') stats.max = firstResult[`MAX(${column})`] as number; if (typeof firstResult[`MIN(${column})`] === 'number') stats.min = firstResult[`MIN(${column})`] as number; // Calculate range if we have min and max if (stats.min !== undefined && stats.max !== undefined) { stats.range = stats.max - stats.min; } // Only add if we have at least one stat if (Object.keys(stats).length > 0) { numericStats[column] = { ...stats, interpretation: generateInterpretation(stats, column) } as NumericStatsWithInterpretation; } } }); } // Add stats if we have any if (Object.keys(numericStats).length > 0) { simplifiedResponse.stats = numericStats; } // Add cardinality information (unique combinations of values) const uniqueValueCombinations = new Set(); results.forEach(row => { const combinationKey = params.columns .map(col => `${col}:${row[col] !== undefined ? row[col] : 'null'}`) .join('|'); uniqueValueCombinations.add(combinationKey); }); const uniqueCount = uniqueValueCombinations.size; simplifiedResponse.cardinality = { uniqueCount, classification: getCardinalityClassification(uniqueCount) }; } catch (processingError) { // Handle errors during result processing, but still return partial results console.error("Error processing column analysis results:", processingError); simplifiedResponse.processingError = `Error processing results: ${processingError instanceof Error ? processingError.message : String(processingError)}`; } } return { content: [ { type: "text", text: JSON.stringify(simplifiedResponse, null, 2), }, ], }; } catch (error) { return handleToolError(error, "analyze_columns"); } } }; }