MCP Hacker News

Instructions

Implementation Reference

• src/tools.ts:141-183 (handler)

  Handler function that fetches the latest story IDs from Hacker News /newstories endpoint, retrieves up to 'limit' story details using fetchMultipleItems, formats the data including time with formatTime, and returns a structured JSON response.

  execute: async (args: any) => {
    const limit = Math.min(args.limit || 10, 50);
    const newIds = await fetchFromAPI<number[]>("/newstories");
  
    if (!newIds) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({ error: "Failed to fetch new stories" }),
          },
        ],
      };
    }
  
    const stories = await fetchMultipleItems(newIds, 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: `Latest ${limit} stories from Hacker News`,
              stories: formattedStories,
            },
            null,
            2
          ),
        },
      ],
    };
  },

• src/tools.ts:131-140 (schema)

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

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

• src/tools.ts:128-184 (registration)

  Registration of the 'getNewStories' tool as an object in the exported 'tools' array, which is imported and used by the MCP server in src/index.ts for tools/list and tools/call methods.

  {
    name: "getNewStories",
    description: "Get newest stories from Hacker News",
    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 newIds = await fetchFromAPI<number[]>("/newstories");
  
      if (!newIds) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({ error: "Failed to fetch new stories" }),
            },
          ],
        };
      }
  
      const stories = await fetchMultipleItems(newIds, 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: `Latest ${limit} stories from Hacker News`,
                stories: formattedStories,
              },
              null,
              2
            ),
          },
        ],
      };
    },
  },

• src/fetch-actions.ts:9-27 (helper)

  Core helper function to fetch data from Hacker News API endpoints (used for /newstories), with caching via getCached/setCache.

  export async function fetchFromAPI<T>(endpoint: string): Promise<T | null> {
    const cacheKey = endpoint;
    const cached = getCached<T>(cacheKey);
    if (cached) return cached;
  
    try {
      const response = await fetch(
        `https://hacker-news.firebaseio.com/v0${endpoint}.json`
      );
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
  
      const data = await response.json();
      setCache(cacheKey, data);
      return data;
    } catch (error) {
      console.error(`Error fetching ${endpoint}:`, error);
      return null;
    }
  }

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

  Helper to fetch multiple story items in parallel from their IDs, filtering non-null and non-deleted/dead items (used after fetching new story IDs).

  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
    );
  }