hny-mcp

Instructions

Implementation Reference

• src/tools/run-query.ts:225-322 (handler)

  Main handler for run_query tool: normalizes parameters, fixes common input errors, validates query, executes with retry logic using executeQuery helper, formats results, handles errors.
  handler: async (params: any) => { try { // Handle query object nesting - common mistake is to put params inside a 'query' property if (params.query && typeof params.query === 'object' && params.environment && params.dataset) { console.warn("Detected nested query object - pulling properties to top level"); // Merge query properties into top level, but don't overwrite existing top-level properties for (const [key, value] of Object.entries(params.query)) { if (params[key] === undefined) { params[key] = value; } } // We've processed the query object, now delete it to avoid confusion delete params.query; } // Handle common field name mistakes if (params.group_by && !params.breakdowns) { params.breakdowns = params.group_by; delete params.group_by; console.warn("Detected 'group_by' field - renamed to 'breakdowns'"); } // Handle order_by -> orders conversion if (params.order_by && !params.orders) { // Convert single order_by object to orders array if (!Array.isArray(params.order_by)) { params.orders = [params.order_by]; } else { params.orders = params.order_by; } delete params.order_by; console.warn("Detected 'order_by' field - renamed to 'orders'"); } // Handle having -> havings conversion if (params.having && !params.havings) { params.havings = params.having; delete params.having; console.warn("Detected 'having' field - renamed to 'havings'"); } // Validate calculations array and field names if (params.calculations) { for (const calc of params.calculations) { // Handle operation -> op conversion if needed if (calc.operation && !calc.op) { calc.op = calc.operation; delete calc.operation; console.warn("Detected 'operation' field in calculation - renamed to 'op'"); } // Handle field -> column conversion if needed if (calc.field && !calc.column) { calc.column = calc.field; delete calc.field; console.warn("Detected 'field' field in calculation - renamed to 'column'"); } // We now rely on Zod schema refinements for validation of column rules } } // Validate parameters with our standard validation validateQuery(params); // Check if any calculations use HEATMAP const hasHeatmap = params.calculations.some((calc: any) => calc.op === "HEATMAP"); // Execute the query with retry logic for transient API issues const maxRetries = 3; let lastError: unknown = null; for (let attempt = 1; attempt <= maxRetries; attempt++) { try { return await executeQuery(api, params, hasHeatmap); } catch (error) { lastError = error; console.error(`Query attempt ${attempt} failed: ${error instanceof Error ? error.message : String(error)}`); // Only retry if not the last attempt if (attempt < maxRetries) { console.error(`Retrying in ${attempt * 500}ms...`); await new Promise(resolve => setTimeout(resolve, attempt * 500)); } } } // If we get here, all attempts failed throw lastError || new Error("All query attempts failed"); } catch (error) { return handleToolError(error, "run_query", { environment: params.environment, dataset: params.dataset }); } }, };
• src/tools/run-query.ts:90-218 (schema)

  Zod schema definition for run_query tool inputs with detailed descriptions, enums for ops, and superRefine validation to enforce rules like no 'column' for COUNT ops.
  schema: { environment: z.string().min(1).trim().describe("The Honeycomb environment to query"), dataset: z.string().min(1).trim().describe("The dataset to query. Use __all__ to query across all datasets in the environment."), calculations: z.array(z.object({ op: z.enum([ "COUNT", "CONCURRENCY", "SUM", "AVG", "COUNT_DISTINCT", "MAX", "MIN", "P001", "P01", "P05", "P10", "P20", "P25", "P50", "P75", "P80", "P90", "P95", "P99", "P999", "RATE_AVG", "RATE_SUM", "RATE_MAX", "HEATMAP", ]).describe(`⚠️⚠️⚠️ CRITICAL RULES FOR OPERATIONS: 1. FOR COUNT OPERATIONS: - NEVER include a "column" field - CORRECT: {"op": "COUNT"} - INCORRECT: {"op": "COUNT", "column": "anything"} 2. FOR PERCENTILES: - Use the exact P* operations (P95, P99, etc.) - CORRECT: {"op": "P95", "column": "duration_ms"} - INCORRECT: {"op": "PERCENTILE", "percentile": 95} 3. ALL operations EXCEPT COUNT and CONCURRENCY REQUIRE a column field COMMON ERRORS TO AVOID: - DO NOT include "column" with COUNT or CONCURRENCY - DO NOT use "PERCENTILE" - use "P95", "P99", etc. instead - DO NOT misspell operation names`), column: z.string().min(1).trim().optional().describe("⚠️ CRITICAL: NEVER include this field when op is COUNT or CONCURRENCY. REQUIRED for all other operations."), }).superRefine((calculation, ctx) => { // Prevent column for COUNT or CONCURRENCY if ((calculation.op === "COUNT" || calculation.op === "CONCURRENCY") && calculation.column !== undefined) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: `ERROR: ${calculation.op} operations MUST NOT have a column field. Remove the "column" field entirely.`, path: ["column"] }); } // Require column for all other operations if (!(calculation.op === "COUNT" || calculation.op === "CONCURRENCY") && calculation.column === undefined) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: `ERROR: ${calculation.op} operations REQUIRE a column field.`, path: ["column"] }); } })).describe("⚠️ CRITICAL RULE: For COUNT or CONCURRENCY operations, you MUST OMIT the 'column' field COMPLETELY - do not include it at all. For all other operations, the 'column' field is REQUIRED."), breakdowns: z.array(z.string().min(1).trim()).optional().describe("MUST use field name 'breakdowns' (not 'group_by'). Columns to group results by."), filters: z.array(z.object({ column: z.string().min(1).trim().describe("MUST use field name 'column'. Name of the column to filter on."), op: z.enum([ "=", "!=", ">", ">=", "<", "<=", "starts-with", "does-not-start-with", "ends-with", "does-not-end-with", "exists", "does-not-exist", "contains", "does-not-contain", "in", "not-in" ]).describe(`MUST use field name 'op'. Available operators: - Equality: "=", "!=" - Comparison: ">", ">=", "<", "<=" - String: "starts-with", "does-not-start-with", "ends-with", "does-not-end-with", "contains", "does-not-contain" - Existence: "exists", "does-not-exist" - Arrays: "in", "not-in" (use with array values)`), value: z.any().optional().describe("MUST use field name 'value'. Comparison value. Optional for exists operators. Use arrays for in/not-in.") })).optional().describe("MUST use field name 'filters' (an array of filter objects). Pre-calculation filters for the query."), filter_combination: z.enum(["AND", "OR"]).optional().describe("MUST use field name 'filter_combination' (not 'combine_filters'). How to combine filters: AND or OR. Default: AND."), orders: z.array(z.object({ column: z.string().min(1).trim().describe("MUST use field name 'column'. Column to order by. Required when sorting by a column directly."), op: z.string().optional().describe("MUST use field name 'op' when provided. Operation to order by. Must match a calculation operation."), order: z.enum(["ascending", "descending"]).optional().describe("MUST use field name 'order' when provided. Available values: \"ascending\" (low to high) or \"descending\" (high to low).") })).optional().describe("MUST use field name 'orders' (not 'sort' or 'order_by'). Array of sort configurations."), limit: z.number().int().positive().optional().describe("MUST use field name 'limit'. Maximum number of result rows to return."), time_range: z.number().positive().optional().describe("MUST use field name 'time_range' (with underscore). Relative time range in seconds from now."), start_time: z.number().int().positive().optional().describe("MUST use field name 'start_time' (with underscore). Absolute start timestamp in seconds."), end_time: z.number().int().positive().optional().describe("MUST use field name 'end_time' (with underscore). Absolute end timestamp in seconds."), granularity: z.number().int().nonnegative().optional().describe("MUST use field name 'granularity'. Time resolution in seconds. 0 for auto."), havings: z.array(z.object({ calculate_op: z.enum([ "COUNT", "CONCURRENCY", "SUM", "AVG", "COUNT_DISTINCT", "MAX", "MIN", "P001", "P01", "P05", "P10", "P20", "P25", "P50", "P75", "P80", "P90", "P95", "P99", "P999", "RATE_AVG", "RATE_SUM", "RATE_MAX" ]).describe(`MUST use field name 'calculate_op'. Available operations: - NO COLUMN ALLOWED: COUNT, CONCURRENCY - REQUIRE COLUMN: SUM, AVG, COUNT_DISTINCT, MAX, MIN, P001, P01, P05, P10, P20, P25, P50, P75, P80, P90, P95, P99, P999, RATE_AVG, RATE_SUM, RATE_MAX`), column: z.string().min(1).trim().optional().describe("MUST use field name 'column'. NEVER use with COUNT/CONCURRENCY. REQUIRED for all other operations."), op: z.enum(["=", "!=", ">", ">=", "<", "<="]).describe("MUST use field name 'op'. Available comparison operators: \"=\", \"!=\", \">\", \">=\", \"<\", \"<=\""), value: z.number().describe("MUST use field name 'value'. Numeric threshold value to compare against.") })).optional().describe("MUST use field name 'havings'. Post-calculation filters with same column rules as calculations.") },
• src/tools/index.ts:25-108 (registration)

  Registers the run_query tool (created via createRunQueryTool) along with others on the MCP server, including pre-handler validation for required environment and dataset.
  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/tools/run-query.ts:11-66 (helper)

  Helper function to execute the actual API query, simplify/process results, add summaries and metadata, and format as tool response.
  async function executeQuery( api: HoneycombAPI, params: z.infer<typeof QueryToolSchema>, hasHeatmap: boolean ) { // Execute the query const result = await api.runAnalysisQuery(params.environment, params.dataset, params); try { // Simplify the response to reduce context window usage const simplifiedResponse = { results: result.data?.results || [], // Only include series data if heatmap calculation is present (it's usually large) ...(hasHeatmap ? { series: result.data?.series || [] } : {}), // Include a query URL if available query_url: result.links?.query_url || null, // Add summary statistics for numeric columns summary: summarizeResults(result.data?.results || [], params), // Add query metadata for context metadata: { environment: params.environment, dataset: params.dataset, executedAt: new Date().toISOString(), resultCount: result.data?.results?.length || 0 } }; return { content: [ { type: "text", text: JSON.stringify(simplifiedResponse, null, 2), }, ], }; } catch (processingError) { // Handle result processing errors separately to still return partial results console.error("Error processing query results:", processingError); return { content: [ { type: "text", text: JSON.stringify({ results: result.data?.results || [], query_url: result.links?.query_url || null, error: `Error processing results: ${processingError instanceof Error ? processingError.message : String(processingError)}` }, null, 2), }, ], }; } }