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