hny-mcp

Instructions

Implementation Reference

• src/tools/list-markers.ts:14-201 (handler)

  The createListMarkersTool function that constructs the MCP tool object for 'list_markers', including the core handler logic that fetches markers from the Honeycomb API, processes them (simplification, pagination, sorting, filtering, caching), and formats the response.
  export function createListMarkersTool(api: HoneycombAPI) { return { name: "list_markers", description: "Lists available markers (deployment events) for a specific dataset or environment with pagination, sorting, and search support. Returns IDs, messages, types, URLs, creation times, start times, and end times.", schema: ListMarkersSchema.shape, /** * Handler for the list_markers 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 markers with relevant metadata, potentially paginated */ handler: async (params: z.infer<typeof ListMarkersSchema>) => { 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_markers"); } try { // Fetch markers from the API const markers = await api.getMarkers(environment); // Create a simplified response const simplifiedMarkers = markers.map(marker => ({ id: marker.id, message: marker.message, type: marker.type, url: marker.url || '', created_at: marker.created_at, start_time: marker.start_time, end_time: marker.end_time || '', })); // If no pagination or filtering is requested, return all markers if (!page && !limit && !search && !sort_by) { return { content: [ { type: "text", text: JSON.stringify(simplifiedMarkers, null, 2), }, ], metadata: { count: simplifiedMarkers.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 || ['message', 'type'], term: search, caseInsensitive: true } }) }; // Access the collection with pagination and filtering const result = cache.accessCollection( environment, 'marker', undefined, cacheOptions ); // If the collection isn't in cache yet, apply the filtering manually if (!result) { // Basic implementation for non-cached data let filteredMarkers = [...simplifiedMarkers]; // Apply search if requested if (search) { const searchFields = Array.isArray(search_fields) ? search_fields : search_fields ? [search_fields] : ['message', 'type']; const searchTerm = search.toLowerCase(); filteredMarkers = filteredMarkers.filter(marker => { return searchFields.some(field => { const value = marker[field as keyof typeof marker]; return typeof value === 'string' && value.toLowerCase().includes(searchTerm); }); }); } // Apply sorting if requested if (sort_by) { const field = sort_by; const order = sort_order || 'asc'; filteredMarkers.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 = filteredMarkers.length; const pages = Math.ceil(total / itemLimit); const offset = (currentPage - 1) * itemLimit; // Return formatted response const paginatedResponse: PaginatedResponse<typeof simplifiedMarkers[0]> = { data: filteredMarkers.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 simplifiedMarkers; const paginatedResponse: PaginatedResponse<typeof simplifiedMarkers[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_markers"); } } }; }
• src/types/schema.ts:370-373 (schema)

  Zod schema for the list_markers tool input parameters: requires 'environment', optionally merges PaginationSchema for page, limit, sort_by, sort_order, search, search_fields.
  export const ListMarkersSchema = z.object({ environment: z.string().min(1).trim().describe("The Honeycomb environment"), }).merge(PaginationSchema).describe("Parameters for listing Honeycomb markers. Markers represent significant events like deployments or incidents.");
• src/tools/index.ts:40-40 (registration)

  Call to createListMarkersTool(api) which instantiates the tool and adds it to the array passed to the MCP server registration loop.
  createListMarkersTool(api),
• src/tools/index.ts:8-8 (registration)

  Import statement for the list_markers tool creator from "./list-markers.js".
  import { createListMarkersTool } from "./list-markers.js";