MCP Hacker News

Instructions

Implementation Reference

• src/tools.ts:84-126 (handler)

  The execute handler function for getBestStories tool. Fetches best story IDs from HN API, retrieves story details using helper functions, formats the data including relative time and HN links, and returns a JSON-formatted text content response.

  execute: async (args: any) => {
    const limit = Math.min(args.limit || 10, 50);
    const bestIds = await fetchFromAPI<number[]>("/beststories");
  
    if (!bestIds) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({ error: "Failed to fetch best stories" }),
          },
        ],
      };
    }
  
    const stories = await fetchMultipleItems(bestIds, limit);
    const formattedStories = stories.map((story) => ({
      id: story.id,
      title: story.title,
      url: story.url,
      score: story.score,
      author: story.by,
      comments: story.descendants || 0,
      time: story.time ? formatTime(story.time) : "unknown",
      hnUrl: `https://news.ycombinator.com/item?id=${story.id}`,
    }));
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              message: `Best ${limit} stories from Hacker News`,
              stories: formattedStories,
            },
            null,
            2
          ),
        },
      ],
    };
  },

• src/tools.ts:74-83 (schema)

  Input schema defining the optional 'limit' parameter for the number of best stories to retrieve (default 10, max 50).

  inputSchema: {
    type: "object",
    properties: {
      limit: {
        type: "number",
        description: "Number of stories to return (default: 10, max: 50)",
        default: 10,
      },
    },
  },

• src/tools.ts:71-127 (registration)

  The full tool definition object for 'getBestStories' included in the exported 'tools' array, which is imported and served by index.ts for MCP tools/list and tools/call methods.

  {
    name: "getBestStories",
    description: "Get best stories from Hacker News (algorithmically ranked)",
    inputSchema: {
      type: "object",
      properties: {
        limit: {
          type: "number",
          description: "Number of stories to return (default: 10, max: 50)",
          default: 10,
        },
      },
    },
    execute: async (args: any) => {
      const limit = Math.min(args.limit || 10, 50);
      const bestIds = await fetchFromAPI<number[]>("/beststories");
  
      if (!bestIds) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({ error: "Failed to fetch best stories" }),
            },
          ],
        };
      }
  
      const stories = await fetchMultipleItems(bestIds, limit);
      const formattedStories = stories.map((story) => ({
        id: story.id,
        title: story.title,
        url: story.url,
        score: story.score,
        author: story.by,
        comments: story.descendants || 0,
        time: story.time ? formatTime(story.time) : "unknown",
        hnUrl: `https://news.ycombinator.com/item?id=${story.id}`,
      }));
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                message: `Best ${limit} stories from Hacker News`,
                stories: formattedStories,
              },
              null,
              2
            ),
          },
        ],
      };
    },
  },

• src/fetch-actions.ts:30-44 (helper)

  Helper function used to fetch multiple story items in parallel from HN API, filtering out deleted/dead items. Called with bestIds and limit.

  export async function fetchMultipleItems(
    ids: number[],
    maxItems = 30
  ): Promise<HackerNewsItem[]> {
    const limitedIds = ids.slice(0, maxItems);
    const promises = limitedIds.map((id) =>
      fetchFromAPI<HackerNewsItem>(`/item/${id}`)
    );
    const results = await Promise.all(promises);
  
    return results.filter(
      (item): item is HackerNewsItem =>
        item !== null && !item.deleted && !item.dead
    );
  }

• src/helpers.ts:23-35 (helper)

  Helper function to format Unix timestamps to human-readable relative time strings (e.g., '2h ago'), used for story time fields.

  export function formatTime(timestamp: number): string {
    const date = new Date(timestamp * 1000);
    const now = new Date();
    const diff = now.getTime() - date.getTime();
  
    const minutes = Math.floor(diff / (1000 * 60));
    const hours = Math.floor(diff / (1000 * 60 * 60));
    const days = Math.floor(diff / (1000 * 60 * 60 * 24));
  
    if (minutes < 60) return `${minutes}m ago`;
    if (hours < 24) return `${hours}h ago`;
    return `${days}d ago`;
  }