search_posts

Instructions

Implementation Reference

• src/tools/search-posts.ts:15-68 (handler)

  The core handler function that implements the logic for the 'search_posts' tool. It parses and validates the input arguments, performs additional business logic validations, constructs search parameters, invokes the HackerNews API (with optional date sorting), and formats the paginated response.

  export async function handleSearchPosts(args: unknown) {
    // Validate input
    const parseResult = SearchPostsInputSchema.safeParse(args);
  
    if (!parseResult.success) {
      throw new ValidationError("Invalid search parameters", parseResult.error.errors);
    }
  
    const input: SearchPostsInput = parseResult.data;
  
    // Additional validation
    if (input.minPoints !== undefined && input.maxPoints !== undefined) {
      if (input.minPoints > input.maxPoints) {
        throw new ValidationError("minPoints cannot be greater than maxPoints");
      }
    }
  
    if (input.minComments !== undefined && input.maxComments !== undefined) {
      if (input.minComments > input.maxComments) {
        throw new ValidationError("minComments cannot be greater than maxComments");
      }
    }
  
    if (input.dateAfter && input.dateBefore) {
      const after = new Date(input.dateAfter);
      const before = new Date(input.dateBefore);
      if (after > before) {
        throw new ValidationError("dateAfter cannot be later than dateBefore");
      }
    }
  
    // Build API parameters
    const params = buildSearchParams(input);
  
    // Call appropriate API endpoint
    const result = input.sortByDate
      ? await apiClient.searchByDate(params)
      : await apiClient.search(params);
  
    // Format response with pagination metadata
    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:73-93 (schema)

  Zod schema defining the input structure and validation rules for the search_posts tool, including optional filters for query, tags, author, points, comments, dates, sorting, and pagination.

   * Schema for search_posts tool input
   */
  export const SearchPostsInputSchema = z.object({
    query: z.string().max(1000).optional(),
    tags: z
      .array(z.enum(["story", "comment", "poll", "pollopt", "show_hn", "ask_hn", "front_page"]))
      .optional(),
    author: z.string().min(1).max(15).optional(),
    storyId: z.number().int().positive().optional(),
    minPoints: z.number().int().nonnegative().optional(),
    maxPoints: z.number().int().nonnegative().optional(),
    minComments: z.number().int().nonnegative().optional(),
    maxComments: z.number().int().nonnegative().optional(),
    dateAfter: z.string().datetime().optional(),
    dateBefore: z.string().datetime().optional(),
    sortByDate: z.boolean().optional().default(false),
    page: z.number().int().nonnegative().max(999).optional().default(0),
    hitsPerPage: z.number().int().min(1).max(100).optional().default(20),
  });
  
  export type SearchPostsInput = z.infer<typeof SearchPostsInputSchema>;

• src/tools/index.ts:26-31 (registration)

  Registration of the search_posts tool in the MCP tools list, providing name, description, and JSON schema for input validation in tool discovery.

  {
    name: "search_posts",
    description:
      "Search HackerNews posts by keywords with advanced filtering options. Supports filtering by content type (story, comment, poll, etc.), author, date ranges, points thresholds, and comment counts. Returns paginated results with metadata. Default sort is by relevance, but can sort chronologically with sortByDate=true.",
    inputSchema: zodToJsonSchema(SearchPostsInputSchema),
  },

• src/index.ts:52-54 (registration)

  Dispatch/registration in the main MCP server request handler switch statement that routes 'search_posts' tool calls to the specific handler function.

  case "search_posts":
    return await handleSearchPosts(args);

• src/services/search-service.ts:11-95 (helper)

  Helper function that transforms SearchPostsInput into HN Algolia API search parameters, handling tags, numeric filters for points/comments/dates, and pagination.

  export function buildSearchParams(input: SearchPostsInput): {
    query?: string;
    tags?: string;
    numericFilters?: string;
    page?: number;
    hitsPerPage?: number;
  } {
    const params: {
      query?: string;
      tags?: string;
      numericFilters?: string;
      page?: number;
      hitsPerPage?: number;
    } = {};
  
    // Query string
    if (input.query) {
      params.query = input.query;
    }
  
    // Build tags array
    const tags: string[] = [];
  
    // Add content type tags
    if (input.tags && input.tags.length > 0) {
      tags.push(...input.tags);
    }
  
    // Add author tag
    if (input.author) {
      tags.push(`author_${input.author}`);
    }
  
    // Add story ID tag
    if (input.storyId) {
      tags.push(`story_${input.storyId}`);
    }
  
    if (tags.length > 0) {
      params.tags = formatTags(tags);
    }
  
    // Build numeric filters array
    const numericFilters: string[] = [];
  
    // Points filters
    if (input.minPoints !== undefined) {
      numericFilters.push(`points>=${input.minPoints}`);
    }
    if (input.maxPoints !== undefined) {
      numericFilters.push(`points<=${input.maxPoints}`);
    }
  
    // Comments filters
    if (input.minComments !== undefined) {
      numericFilters.push(`num_comments>=${input.minComments}`);
    }
    if (input.maxComments !== undefined) {
      numericFilters.push(`num_comments<=${input.maxComments}`);
    }
  
    // Date filters
    if (input.dateAfter) {
      const timestamp = dateToUnixTimestamp(input.dateAfter);
      numericFilters.push(`created_at_i>=${timestamp}`);
    }
    if (input.dateBefore) {
      const timestamp = dateToUnixTimestamp(input.dateBefore);
      numericFilters.push(`created_at_i<=${timestamp}`);
    }
  
    if (numericFilters.length > 0) {
      params.numericFilters = formatNumericFilters(numericFilters);
    }
  
    // Pagination
    if (input.page !== undefined) {
      params.page = input.page;
    }
    if (input.hitsPerPage !== undefined) {
      params.hitsPerPage = input.hitsPerPage;
    }
  
    return params;
  }