Hacker News MCP Server

Implementation Reference

• src/index.ts:207-257 (handler)

  The handler function for the 'get_top_stories' tool, which retrieves top Hacker News stories by fetching top story IDs and details for a configurable number of stories.

  private async getTopStories(args: { count?: number; include_text?: boolean }) {
    const count = Math.min(args?.count || 30, 100);
    const includeText = args?.include_text || false;
  
    try {
      // Get top story IDs
      const response = await this.axiosInstance.get<number[]>('/topstories.json');
      const storyIds = response.data.slice(0, count);
  
      // Fetch story details
      const stories = await Promise.all(
        storyIds.map(async (id) => {
          const story = await fetchItem(this.axiosInstance, id);
          if (story && story.type === 'story') {
            return {
              id: story.id,
              title: story.title,
              url: story.url,
              by: story.by,
              score: story.score,
              time:
                typeof story.time === 'number'
                  ? new Date(story.time * 1000).toISOString()
                  : story.time
                    ? new Date(Date.parse(story.time)).toISOString()
                    : undefined,
              descendants: story.descendants,
              ...(includeText && story.text ? { text: story.text } : {}),
            };
          }
          return null;
        }),
      );
  
      const validStories = stories.filter(Boolean);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(validStories, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to fetch top stories: ${error instanceof Error ? error.message : 'Unknown error'}`,
      );
    }
  }

• src/index.ts:64-83 (schema)

  The input schema definition for the 'get_top_stories' tool, specifying parameters for count and include_text.

    name: 'get_top_stories',
    description: 'Get the latest top stories from Hacker News',
    inputSchema: {
      type: 'object',
      properties: {
        count: {
          type: 'number',
          description: 'Number of stories to fetch (1-100)',
          minimum: 1,
          maximum: 100,
          default: 30,
        },
        include_text: {
          type: 'boolean',
          description: 'Whether to include story text content',
          default: false,
        },
      },
    },
  },

• src/index.ts:176-177 (registration)

  Registration of the tool handler in the switch statement for CallToolRequestSchema.

  case 'get_top_stories':
    return await this.getTopStories(request.params.arguments ?? {});

• src/utils.ts:21-29 (helper)

  Helper function `fetchItem` used by the handler to fetch individual story details from the Hacker News API.

  export async function fetchItem(axiosInstance: AxiosInstance, id: number): Promise<Story | null> {
    try {
      const response = await axiosInstance.get<Story>(`/item/${id}.json`);
      return response.data;
    } catch (error) {
      console.error(`Error fetching item ${id}:`, error);
      return null;
    }
  }

• src/utils.ts:11-16 (helper)

  Helper function to create the Axios instance configured for the Hacker News API base URL.

  export function createAxiosInstance(): AxiosInstance {
    return axios.create({
      baseURL: 'https://hacker-news.firebaseio.com/v0',
      timeout: 10000,
    });
  }