MCP Hacker News

Instructions

Implementation Reference

• src/tools.ts:314-356 (handler)

  The execute handler function that implements the core logic of the getJobStories tool: fetches job IDs from HN /jobstories endpoint, retrieves and formats up to 30 job items, and returns formatted JSON response.

  execute: async (args: any) => {
    const limit = Math.min(args.limit || 10, 30);
    const jobIds = await fetchFromAPI<number[]>("/jobstories");
  
    if (!jobIds) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({ error: "Failed to fetch job stories" }),
          },
        ],
      };
    }
  
    const jobs = await fetchMultipleItems(jobIds, limit);
    const formattedJobs = jobs.map((job) => ({
      id: job.id,
      title: job.title,
      url: job.url,
      score: job.score,
      author: job.by,
      time: job.time ? formatTime(job.time) : "unknown",
      hnUrl: `https://news.ycombinator.com/item?id=${job.id}`,
      text: job.text,
    }));
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              message: `Latest ${limit} job postings`,
              jobs: formattedJobs,
            },
            null,
            2
          ),
        },
      ],
    };
  },

• src/tools.ts:304-313 (schema)

  The inputSchema defining the parameters for the getJobStories tool, including the optional 'limit' parameter.

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

• src/index.ts:52-65 (registration)

  Registration in the MCP server: handles 'tools/call' JSON-RPC method by looking up the tool by name from the imported tools array and executing its handler.

  if (json.method === "tools/call") {
    const tool = tools.find((tool) => tool.name === json.params.name);
    if (tool) {
      const toolResponse = await tool.execute(json.params.arguments);
      sendResponse(json.id, toolResponse);
    } else {
      sendResponse(json.id, {
        error: {
          code: -32602,
          message: `MCP error -32602: Tool ${json.params.name} not found`,
        },
      });
    }
  }

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

  Helper function fetchFromAPI used in the handler to fetch the list of job story IDs from 'https://hacker-news.firebaseio.com/v0/jobstories.json' with caching.

  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 function fetchMultipleItems used to parallel-fetch and filter item details for the top job stories.

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