search-by-time-range

Find HackerNews posts from specific time periods using Unix timestamps to filter results by date range.

Instructions

Search for posts within a specific time range (Unix timestamps)

Input Schema

TableJSON Schema

Name	Required	Description
`endTime`	Yes	End time in Unix timestamp (seconds)
`hitsPerPage`	No	Number of results per page (default: 20)
`page`	No	Page number for pagination (default: 0)
`query`	No	Search query text (optional)
`startTime`	Yes	Start time in Unix timestamp (seconds)
`tags`	No	Filter tags (e.g., "story", "comment")

Implementation Reference

src/index.ts:496-511 (handler)

The handler function that implements the core logic for the 'search-by-time-range' tool. It constructs URLSearchParams with numericFilters for the time range using created_at_i field, calls fetchHN on the /search_by_date endpoint, and returns both text and structured content.

async ({ query, tags, startTime, endTime, page, hitsPerPage }) => {
  const params = new URLSearchParams();
  if (query) params.append('query', query);
  if (tags) params.append('tags', tags);
  params.append('numericFilters', `created_at_i>${startTime},created_at_i<${endTime}`);
  if (page !== undefined) params.append('page', page.toString());
  if (hitsPerPage !== undefined) params.append('hitsPerPage', hitsPerPage.toString());
  
  const endpoint = `/search_by_date?${params.toString()}`;
  const result = await fetchHN(endpoint);
  
  return {
    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    structuredContent: result
  };
}

src/index.ts:478-495 (schema)

The input and output schemas for the tool, defined with Zod. Input includes startTime and endTime as required Unix timestamps, optional query, tags, and pagination.

  title: 'Search Posts by Time Range',
  description: 'Search for posts within a specific time range (Unix timestamps)',
  inputSchema: {
    query: z.string().optional().describe('Search query text (optional)'),
    tags: z.string().optional().describe('Filter tags (e.g., "story", "comment")'),
    startTime: z.number().describe('Start time in Unix timestamp (seconds)'),
    endTime: z.number().describe('End time in Unix timestamp (seconds)'),
    page: z.number().optional().describe('Page number for pagination (default: 0)'),
    hitsPerPage: z.number().optional().describe('Number of results per page (default: 20)')
  },
  outputSchema: {
    hits: z.array(z.any()),
    nbHits: z.number(),
    nbPages: z.number(),
    page: z.number(),
    hitsPerPage: z.number()
  }
},

src/index.ts:475-512 (registration)

The server.registerTool call that registers the 'search-by-time-range' tool with its schema and handler function.

server.registerTool(
  'search-by-time-range',
  {
    title: 'Search Posts by Time Range',
    description: 'Search for posts within a specific time range (Unix timestamps)',
    inputSchema: {
      query: z.string().optional().describe('Search query text (optional)'),
      tags: z.string().optional().describe('Filter tags (e.g., "story", "comment")'),
      startTime: z.number().describe('Start time in Unix timestamp (seconds)'),
      endTime: z.number().describe('End time in Unix timestamp (seconds)'),
      page: z.number().optional().describe('Page number for pagination (default: 0)'),
      hitsPerPage: z.number().optional().describe('Number of results per page (default: 20)')
    },
    outputSchema: {
      hits: z.array(z.any()),
      nbHits: z.number(),
      nbPages: z.number(),
      page: z.number(),
      hitsPerPage: z.number()
    }
  },
  async ({ query, tags, startTime, endTime, page, hitsPerPage }) => {
    const params = new URLSearchParams();
    if (query) params.append('query', query);
    if (tags) params.append('tags', tags);
    params.append('numericFilters', `created_at_i>${startTime},created_at_i<${endTime}`);
    if (page !== undefined) params.append('page', page.toString());
    if (hitsPerPage !== undefined) params.append('hitsPerPage', hitsPerPage.toString());
    
    const endpoint = `/search_by_date?${params.toString()}`;
    const result = await fetchHN(endpoint);
    
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
      structuredContent: result
    };
  }
);

src/index.ts:11-17 (helper)

Shared helper utility function used by the tool handler to perform HTTP fetches to the HackerNews Algolia API endpoints.

async function fetchHN(endpoint: string): Promise<any> {
  const response = await fetch(`${HN_API_BASE}${endpoint}`);
  if (!response.ok) {
    throw new Error(`HN API error: ${response.status} ${response.statusText}`);
  }
  return await response.json();
}

HackerNews MCP Server