Hacker News MCP Server

Instructions

Implementation Reference

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

  Main handler logic for the 'getStory' tool: fetches story data using hnApi.getItem, formats it with formatStory, constructs a textual response.

  case "getStory": {
    const { id } = args as { id: number };
    const item = await hnApi.getItem(id);
    if (!item || item.type !== "story") {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Story with ID ${id} not found`
      );
    }
    const story = formatStory(item);
    const text =
      `Story ID: ${story.id}\n` +
      `Title: ${story.title}\n` +
      `URL: ${story.url || "(text post)"}\n` +
      `Points: ${story.score} | Author: ${story.by} | Comments: ${story.descendants}\n` +
      (story.text ? `\nContent:\n${story.text}\n` : "");
  
    return {
      content: [{ type: "text", text: text.trim() }],
    };
  }

• src/index.ts:69-79 (registration)

  Tool registration in ListTools handler, defining name, description, and input schema for 'getStory'.

  {
    name: "getStory",
    description: "Get a single story by ID",
    inputSchema: {
      type: "object",
      properties: {
        id: { type: "number", description: "The ID of the story" },
      },
      required: ["id"],
    },
  },

• src/api/hn.ts:12-15 (helper)

  hnApi.getItem method: fetches a single Hacker News item by ID from the official Firebase API.

  async getItem(id: number): Promise<any> {
    const response = await fetch(`${API_BASE_URL}/item/${id}.json`);
    return response.json();
  }

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

  formatStory function: transforms raw HN item data into a structured Story object used in the handler.

  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/index.ts:72-78 (schema)

  Input schema definition for the 'getStory' tool, specifying the required 'id' parameter.

  inputSchema: {
    type: "object",
    properties: {
      id: { type: "number", description: "The ID of the story" },
    },
    required: ["id"],
  },