list_boards

Instructions

Implementation Reference

• src/tools/list-boards.ts:14-218 (handler)

  The createListBoardsTool function defines and exports the list_boards tool implementation, including the handler logic that fetches boards via Honeycomb API, handles validation, pagination, sorting, search, caching, and formats the response as JSON.

  export function createListBoardsTool(api: HoneycombAPI) {
    return {
      name: "list_boards",
      description: "Lists available boards (dashboards) for a specific environment with pagination, sorting, and search support. Returns board IDs, names, descriptions, creation times, and last update times.",
      schema: ListBoardsSchema.shape,
      /**
       * Handler for the list_boards tool
       * 
       * @param params - The parameters for the tool
       * @param params.environment - The Honeycomb environment
       * @param params.page - Optional page number for pagination
       * @param params.limit - Optional limit of items per page
       * @param params.sort_by - Optional field to sort by
       * @param params.sort_order - Optional sort direction (asc/desc)
       * @param params.search - Optional search term
       * @param params.search_fields - Optional fields to search in
       * @returns List of boards with relevant metadata, potentially paginated
       */
      handler: async (params: z.infer<typeof ListBoardsSchema>) => {
        const { environment, page, limit, sort_by, sort_order, search, search_fields } = params;
        
        // Validate input parameters
        if (!environment) {
          return handleToolError(new Error("environment parameter is required"), "list_boards");
        }
  
        try {
          // Fetch boards from the API
          const boards = await api.getBoards(environment);
          
          // Safety check - ensure boards is an array
          if (!Array.isArray(boards)) {
            return {
              content: [
                {
                  type: "text",
                  text: JSON.stringify([], null, 2),
                },
              ],
              metadata: {
                count: 0,
                environment
              }
            };
          }
          
          // Create a simplified response, with additional error handling
          const simplifiedBoards = boards.map(board => {
            // Create a copy with defaults for missing fields
            return {
              id: board.id || 'unknown-id',
              name: board.name || 'Unnamed Board',
              description: board.description || '',
              created_at: board.created_at || new Date().toISOString(),
              updated_at: board.updated_at || new Date().toISOString(),
            };
          });
          
          // If no pagination or filtering is requested, return all boards
          if (!page && !limit && !search && !sort_by) {
            return {
              content: [
                {
                  type: "text",
                  text: JSON.stringify(simplifiedBoards, null, 2),
                },
              ],
              metadata: {
                count: simplifiedBoards.length,
                environment
              }
            };
          }
          
          // Otherwise, use the cache manager to handle pagination, sorting, and filtering
          const cache = getCache();
          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, 
            'board', 
            undefined, 
            cacheOptions
          );
          
          // If the collection isn't in cache yet, apply the filtering manually
          if (!result) {
            // Basic implementation for non-cached data
            let filteredBoards = [...simplifiedBoards];
            
            // Apply search if requested
            if (search) {
              const searchFields = Array.isArray(search_fields) 
                ? search_fields 
                : search_fields 
                  ? [search_fields] 
                  : ['name', 'description'];
                  
              const searchTerm = search.toLowerCase();
              
              filteredBoards = filteredBoards.filter(board => {
                return searchFields.some(field => {
                  const value = board[field as keyof typeof board];
                  return typeof value === 'string' && value.toLowerCase().includes(searchTerm);
                });
              });
            }
            
            // Apply sorting if requested
            if (sort_by) {
              const field = sort_by;
              const order = sort_order || 'asc';
              
              filteredBoards.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);
                }
                
                return order === 'asc' 
                  ? (aValue > bValue ? 1 : -1) 
                  : (bValue > aValue ? 1 : -1);
              });
            }
            
            // Apply pagination
            const itemLimit = limit || 10;
            const currentPage = page || 1;
            const total = filteredBoards.length;
            const pages = Math.ceil(total / itemLimit);
            const offset = (currentPage - 1) * itemLimit;
            
            // Return formatted response
            const paginatedResponse: PaginatedResponse<typeof simplifiedBoards[0]> = {
              data: filteredBoards.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 simplifiedBoards;
          
          const paginatedResponse: PaginatedResponse<typeof simplifiedBoards[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_boards");
        }
      }
    };
  }

• src/types/schema.ts:348-351 (schema)

  Zod schema defining input parameters for the list_boards tool: environment (required) merged with PaginationSchema for optional pagination, sorting, and search options.

  export const ListBoardsSchema = z.object({
    environment: z.string().min(1).trim().describe("The Honeycomb environment"),
  }).merge(PaginationSchema).describe("Parameters for listing Honeycomb boards. Returns a paginated list of boards with metadata.");

• src/tools/index.ts:6-36 (registration)

  Imports the createListBoardsTool function and includes it in the tools array passed to registerTools, which registers all tools with the MCP server by calling server.tool() for each.

  import { createListBoardsTool } from "./list-boards.js";
  import { createGetBoardTool } from "./get-board.js";
  import { createListMarkersTool } from "./list-markers.js";
  import { createListRecipientsTool } from "./list-recipients.js";
  import { createListSLOsTool } from "./list-slos.js";
  import { createGetSLOTool } from "./get-slo.js";
  import { createListTriggersTool } from "./list-triggers.js";
  import { createGetTriggerTool } from "./get-trigger.js";
  import { createTraceDeepLinkTool } from "./get-trace-link.js";
  import { createInstrumentationGuidanceTool } from "./instrumentation-guidance.js";
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  import { z } from "zod";
  
  /**
   * Register all tools with the MCP server
   * 
   * @param server - The MCP server instance
   * @param api - The Honeycomb API client
   */
  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),