hny-mcp

Instructions

Implementation Reference

• src/tools/list-columns.ts:47-228 (handler)

  The main handler function for the 'list_columns' tool. It validates input, fetches columns from Honeycomb API using getVisibleColumns, simplifies the column data, applies pagination/sorting/filtering either via cache or manually, and returns a formatted JSON response with content and metadata.
  handler: async (params: z.infer<typeof ListColumnsSchema>) => { const { environment, dataset, page, limit, sort_by, sort_order, search, search_fields } = params; // Validate input parameters if (!environment) { return handleToolError(new Error("environment parameter is required"), "list_columns"); } if (!dataset) { return handleToolError(new Error("dataset parameter is required"), "list_columns"); } try { // Fetch columns from the API const columns = await api.getVisibleColumns(environment, dataset); // Simplify the response to reduce context window usage const simplifiedColumns: SimplifiedColumn[] = columns.map(column => ({ name: column.key_name, type: column.type, description: column.description || '', hidden: column.hidden || false, last_written: column.last_written || null, created_at: column.created_at, })); // If no pagination or filtering is requested, return all columns if (!page && !limit && !search && !sort_by) { return { content: [ { type: "text", text: JSON.stringify(simplifiedColumns, null, 2), }, ], metadata: { count: simplifiedColumns.length, dataset, environment } }; } // Otherwise, use the cache manager to handle pagination, sorting, and filtering const cache = getCache(); const cacheKey = `${dataset}:columns`; // First, ensure the columns are in the cache // This is different from other resources that are automatically cached by API calls cache.set(environment, 'column', simplifiedColumns, cacheKey); const cacheOptions = { page: page || 1, limit: limit || 10, // Configure sorting if requested ...(sort_by && { sort: { field: sort_by, order: sort_order || 'asc' } }), // Configure search if requested ...(search && { search: { field: search_fields || ['name', 'description'], term: search, caseInsensitive: true } }) }; // Access the collection with pagination and filtering const result = cache.accessCollection( environment, 'column', cacheKey, cacheOptions ); // If the collection isn't in cache yet, apply the filtering manually if (!result) { // Basic implementation for non-cached data let filteredColumns = [...simplifiedColumns]; // Apply search if requested if (search) { const searchFields = Array.isArray(search_fields) ? search_fields : search_fields ? [search_fields] : ['name', 'description']; const searchTerm = search.toLowerCase(); filteredColumns = filteredColumns.filter(column => { return searchFields.some(field => { const value = column[field as keyof typeof column]; return typeof value === 'string' && value.toLowerCase().includes(searchTerm); }); }); } // Apply sorting if requested if (sort_by) { const field = sort_by; const order = sort_order || 'asc'; filteredColumns.sort((a, b) => { const aValue = a[field as keyof typeof a]; const bValue = b[field as keyof typeof b]; if (typeof aValue === 'string' && typeof bValue === 'string') { return order === 'asc' ? aValue.localeCompare(bValue) : bValue.localeCompare(aValue); } // Null-safe comparison for nullable values if (aValue === null || aValue === undefined) return order === 'asc' ? -1 : 1; if (bValue === null || bValue === undefined) return order === 'asc' ? 1 : -1; return order === 'asc' ? (aValue > bValue ? 1 : -1) : (bValue > aValue ? 1 : -1); }); } // Apply pagination const itemLimit = limit || 10; const currentPage = page || 1; const total = filteredColumns.length; const pages = Math.ceil(total / itemLimit); const offset = (currentPage - 1) * itemLimit; // Return formatted response const paginatedResponse: PaginatedResponse<typeof simplifiedColumns[0]> = { data: filteredColumns.slice(offset, offset + itemLimit), metadata: { total, page: currentPage, pages, limit: itemLimit } }; return { content: [ { type: "text", text: JSON.stringify(paginatedResponse, null, 2), }, ], }; } // Format the cached result and type-cast the unknown data const typedData = result.data as typeof simplifiedColumns; // Format the cached result const paginatedResponse: PaginatedResponse<typeof simplifiedColumns[0]> = { data: typedData, metadata: { total: result.total, page: result.page || 1, pages: result.pages || 1, limit: limit || 10 } }; return { content: [ { type: "text", text: JSON.stringify(paginatedResponse, null, 2), }, ], }; } catch (error) { return handleToolError(error, "list_columns"); } }
• src/types/schema.ts:44-48 (schema)

  Zod schema defining the input parameters for the list_columns tool, merging base dataset fields with pagination, sorting, and search options.
  export const ListColumnsSchema = z.object({ environment: z.string().min(1).trim().describe("The Honeycomb environment"), dataset: z.string().min(1).trim().describe("The dataset to fetch columns from"), }).merge(PaginationSchema).describe("Parameters for listing columns in a Honeycomb dataset. Returns column names, types, and additional metadata.");
• src/tools/index.ts:25-108 (registration)

  Registration of the list_columns tool (imported and created at lines 3 and 29) into the MCP server via the registerTools function, which adds it to the tools array and calls server.tool() for each.
  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/list-columns.ts:11-18 (helper)

  TypeScript interface defining the simplified column structure used in the tool's response to reduce token usage.
  interface SimplifiedColumn { name: string; type: string; description: string; hidden: boolean; last_written?: string | null; created_at: string; }
• src/types/schema.ts:6-16 (schema)

  Shared Zod schema for pagination, sorting, and search options, merged into ListColumnsSchema.
  export const PaginationSchema = z.object({ page: z.number().positive().int().optional().describe("Page number (1-based)"), limit: z.number().positive().int().optional().describe("Number of items per page"), sort_by: z.string().optional().describe("Field to sort by"), sort_order: z.enum(['asc', 'desc']).optional().describe("Sort direction"), search: z.string().trim().optional().describe("Search term to filter results"), search_fields: z.union([ z.string(), z.array(z.string().min(1)) ]).optional().describe("Fields to search in (string or array of strings)"), });