Hacker News MCP Server

Instructions

Implementation Reference

• src/index.ts:91-111 (registration)

  Registration of the 'getStories' tool in the ListToolsRequestSchema handler, including name, description, and input schema definition.

  {
    name: "getStories",
    description:
      "Get multiple stories by type (top, new, best, ask, show, job)",
    inputSchema: {
      type: "object",
      properties: {
        type: {
          type: "string",
          enum: ["top", "new", "best", "ask", "show", "job"],
          description: "The type of stories to fetch",
        },
        limit: {
          type: "number",
          description: "The maximum number of stories to fetch",
          default: 30,
        },
      },
      required: ["type"],
    },
  },

• src/index.ts:276-336 (handler)

  The primary handler for the 'getStories' tool in the CallToolRequestSchema switch statement. Fetches story IDs by type from HN API, retrieves items, formats stories, and constructs a response with a numbered list.

  case "getStories": {
    const { type, limit = 30 } = args as {
      type: "top" | "new" | "best" | "ask" | "show" | "job";
      limit?: number;
    };
    try {
      let storyIds: number[] = [];
  
      switch (type) {
        case "top":
          storyIds = await hnApi.getTopStories(limit);
          break;
        case "new":
          storyIds = await hnApi.getNewStories(limit);
          break;
        case "best":
          storyIds = await hnApi.getBestStories(limit);
          break;
        case "ask":
          storyIds = await hnApi.getAskStories(limit);
          break;
        case "show":
          storyIds = await hnApi.getShowStories(limit);
          break;
        case "job":
          storyIds = await hnApi.getJobStories(limit);
          break;
      }
  
      const items = await hnApi.getItems(storyIds);
      const stories = items
        .filter((item) => item && item.type === "story")
        .map(formatStory);
  
      if (stories.length === 0) {
        return {
          content: [{ type: "text", text: "No stories found." }],
        };
      }
  
      const text = stories
        .map(
          (story, index) =>
            `${index + 1}. ${story.title}\n` +
            `   ID: ${story.id}\n` +
            `   URL: ${story.url || "(text post)"}\n` +
            `   Points: ${story.score} | Author: ${story.by} | Comments: ${story.descendants}\n\n`
        )
        .join("");
  
      return {
        content: [{ type: "text", text: text.trim() }],
      };
    } catch (err) {
      const error = err as Error;
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to fetch stories: ${error.message}`
      );
    }
  }

• src/models/story.ts:14-27 (helper)

  Helper function used by the handler to format raw Hacker News story items into a standardized Story object.

  export function formatStory(item: any): Story {
    return {
      id: item.id,
      title: item.title,
      url: item.url,
      text: item.text,
      by: item.by,
      score: item.score || 0,
      time: item.time,
      descendants: item.descendants || 0,
      kids: item.kids || [],
      type: "story",
    };
  }

• src/api/hn.ts:27-76 (helper)

  Helper methods in HackerNewsAPI class to fetch story ID lists for different categories (top, new, best, ask, show, job), used by the getStories handler.

  async getTopStories(limit: number = 30): Promise<number[]> {
    const response = await fetch(`${API_BASE_URL}/topstories.json`);
    const ids = (await response.json()) as number[];
    return ids.slice(0, limit);
  }
  
  /**
   * Fetch new stories
   */
  async getNewStories(limit: number = 30): Promise<number[]> {
    const response = await fetch(`${API_BASE_URL}/newstories.json`);
    const ids = (await response.json()) as number[];
    return ids.slice(0, limit);
  }
  
  /**
   * Fetch best stories
   */
  async getBestStories(limit: number = 30): Promise<number[]> {
    const response = await fetch(`${API_BASE_URL}/beststories.json`);
    const ids = (await response.json()) as number[];
    return ids.slice(0, limit);
  }
  
  /**
   * Fetch ask stories
   */
  async getAskStories(limit: number = 30): Promise<number[]> {
    const response = await fetch(`${API_BASE_URL}/askstories.json`);
    const ids = (await response.json()) as number[];
    return ids.slice(0, limit);
  }
  
  /**
   * Fetch show stories
   */
  async getShowStories(limit: number = 30): Promise<number[]> {
    const response = await fetch(`${API_BASE_URL}/showstories.json`);
    const ids = (await response.json()) as number[];
    return ids.slice(0, limit);
  }
  
  /**
   * Fetch job stories
   */
  async getJobStories(limit: number = 30): Promise<number[]> {
    const response = await fetch(`${API_BASE_URL}/jobstories.json`);
    const ids = (await response.json()) as number[];
    return ids.slice(0, limit);
  }

• src/api/hn.ts:20-22 (helper)

  Helper method to batch fetch multiple HN items by IDs, used in the getStories handler.

  async getItems(ids: number[]): Promise<any[]> {
    return Promise.all(ids.map((id) => this.getItem(id)));
  }