HackerNews MCP Server

Instructions

Implementation Reference

• src/tools/search-posts.ts:35-60 (handler)

  The main handler function that executes the 'search-posts' tool. It validates the input using SearchPostsInputSchema, calls the HackerNews API via hnApi.search(), processes the results, and handles validation and API errors appropriately.
  export async function searchPostsTool(input: unknown): Promise<CallToolResult> { try { // Validate input const params = validateInput(SearchPostsInputSchema, input); // Call HackerNews API const results = await hnApi.search({ query: params.query, tags: params.tags, numericFilters: params.numericFilters, page: params.page, hitsPerPage: params.hitsPerPage, }); // Return success result return createSuccessResult(results); } catch (error) { // Handle validation errors if (error instanceof ZodError) { return handleValidationError(error); } // Handle API errors return handleAPIError(error, "searching posts"); } }
• src/utils/validators.ts:13-24 (schema)

  Zod schema for validating the input parameters of the 'search-posts' tool, including query, tags, numericFilters, page, and hitsPerPage with appropriate constraints.
  export const SearchPostsInputSchema = z.object({ query: z.string().min(1, "query must contain at least 1 character"), tags: z.array(z.string()).optional(), numericFilters: z.array(z.string()).optional(), page: z.number().int().nonnegative("page must be non-negative").default(0), hitsPerPage: z .number() .int() .min(1, "hitsPerPage must be at least 1") .max(1000, "hitsPerPage must not exceed 1000") .default(20), });
• src/index.ts:45-55 (registration)

  Registration of the 'search-posts' tool metadata in the MCP server's listTools handler, making it discoverable to clients.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ searchPostsToolMetadata, getFrontPageTool, getLatestPostsTool, getItemTool, getUserTool, ], }; });
• src/index.ts:66-68 (registration)

  Dispatch registration in the MCP server's callTool handler switch statement, routing 'search-posts' calls to the searchPostsTool function.
  case "search-posts": return await searchPostsTool(args);
• src/tools/search-posts.ts:65-130 (schema)

  MCP tool metadata including the name 'search-posts', detailed description, and JSON schema for input validation, used for tool registration.
  export const searchPostsToolMetadata = { name: "search-posts", description: `Search HackerNews for stories, comments, and other content by keyword. Supports: - Keyword search across titles, text, and authors - Tag filtering (story, comment, poll, show_hn, ask_hn, front_page, author_USERNAME) - Numeric filters for points, comments, and dates - Pagination with customizable results per page - Advanced filtering with OR logic and multiple conditions Basic Examples: - Search for AI stories: { "query": "AI", "tags": ["story"] } - Find popular posts: { "query": "Python", "numericFilters": ["points>=100"] } - Filter by author: { "query": "startup", "tags": ["author_pg"] } - Date range: { "query": "startup", "numericFilters": ["created_at_i>1640000000"] } Advanced Filtering Examples: - High engagement posts: { "query": "programming", "numericFilters": ["points>=100", "num_comments>=50"] } - OR logic for tags: { "query": "web", "tags": ["(story,poll)"] } - returns stories OR polls - Author with filters: { "query": "", "tags": ["author_pg", "story"], "numericFilters": ["points>=50"] } - Multiple conditions: { "query": "AI", "tags": ["story"], "numericFilters": ["points>=200", "num_comments>=100"] } Numeric Filter Operators: < (less than), <= (less than or equal), = (equal), >= (greater than or equal), > (greater than) Numeric Filter Fields: points, num_comments, created_at_i (Unix timestamp) Tag Syntax: - Single tag: ["story"] - only stories - Multiple tags (AND): ["story", "show_hn"] - stories that are also show_hn - OR logic: ["(story,poll)"] - stories OR polls - Author filter: ["author_USERNAME"] - posts by specific author Returns paginated results with hits, total count, and page information.`, inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query text (minimum 1 character)", }, tags: { type: "array", items: { type: "string" }, description: "Optional filter tags (e.g., ['story'], ['comment'], ['(story,poll)'] for OR logic, ['author_pg'] for author filter)", }, numericFilters: { type: "array", items: { type: "string" }, description: "Optional numeric filters (e.g., ['points>=100'], ['num_comments>=50'], ['created_at_i>1640000000']). Multiple filters use AND logic.", }, page: { type: "number", description: "Page number (0-indexed, default: 0)", default: 0, }, hitsPerPage: { type: "number", description: "Results per page (1-1000, default: 20)", default: 20, }, }, required: ["query"], }, };