HackerNews MCP Server

Instructions

Implementation Reference

• src/tools/get-front-page.ts:14-45 (handler)

  The core handler function for the get_front_page tool. Validates input using GetFrontPageInputSchema, queries the HackerNews API search endpoint with tags='(front_page)' to fetch front page items, formats the paginated response including quota info, and returns it via formatToolResponse.
  export async function handleGetFrontPage(args: unknown) { // Validate input const parseResult = GetFrontPageInputSchema.safeParse(args); if (!parseResult.success) { throw new ValidationError("Invalid front page parameters", parseResult.error.errors); } const input: GetFrontPageInput = parseResult.data; // Search with front_page tag const result = await apiClient.search({ tags: "(front_page)", page: input.page, hitsPerPage: input.hitsPerPage, }); // Format response const response = { results: result.hits, pagination: { totalResults: result.nbHits, currentPage: result.page, totalPages: result.nbPages, resultsPerPage: result.hitsPerPage, }, processingTimeMS: result.processingTimeMS, remainingQuota: apiClient.getRemainingQuota(), }; return formatToolResponse(response); }
• src/schemas/index.ts:95-103 (schema)

  Zod schema defining the input for get_front_page tool: optional page (default 0) and hitsPerPage (default 30, max 30). Includes inferred TypeScript type.
  /** * Schema for get_front_page tool input */ export const GetFrontPageInputSchema = z.object({ page: z.number().int().nonnegative().optional().default(0), hitsPerPage: z.number().int().min(1).max(30).optional().default(30), }); export type GetFrontPageInput = z.infer<typeof GetFrontPageInputSchema>;
• src/tools/index.ts:32-37 (registration)

  Registers the get_front_page tool in the MCP tools list, providing name, description, and input JSON schema derived from Zod schema.
  { name: "get_front_page", description: "Retrieve current HackerNews front page posts. Returns the posts currently featured on the HN front page, ordered by rank. Supports pagination to browse through all front page items. Front page typically contains 30 posts per page (matches the HN website).", inputSchema: zodToJsonSchema(GetFrontPageInputSchema), },
• src/index.ts:55-57 (registration)

  In the main MCP server tool call handler, dispatches calls to 'get_front_page' to the specific handleGetFrontPage function.
  case "get_front_page": return await handleGetFrontPage(args);
• src/types/index.ts:109-115 (schema)

  TypeScript interface defining the input shape for get_front_page tool, matching the Zod schema.
  /** * Tool input for get_front_page */ export interface GetFrontPageInput { page?: number; hitsPerPage?: number; }