HackerNews MCP Server

Instructions

Implementation Reference

• src/tools/get-item.ts:50-74 (handler)

  The primary handler function that executes the 'get-item' tool logic: validates input, fetches the HackerNews item by ID using HNAPIClient (including full nested comment tree), checks existence, validates output, and returns success or error result.

  export async function getItemHandler(input: unknown): Promise<CallToolResult> {
  	try {
  		// Validate input
  		const validatedParams = GetItemInputSchema.parse(input);
  
  		// Create API client
  		const client = new HNAPIClient();
  
  		// Call items API to get item with nested children
  		const result = await client.getItem(validatedParams.itemId);
  
  		// Check if item exists
  		const notFoundError = checkItemExists(result, "Item", validatedParams.itemId);
  		if (notFoundError) {
  			return notFoundError;
  		}
  
  		// Validate output
  		const validatedResult = GetItemOutputSchema.parse(result);
  
  		return createSuccessResult(validatedResult);
  	} catch (error) {
  		return handleAPIError(error, "get-item");
  	}
  }

• src/tools/get-item.ts:16-37 (schema)

  Zod schemas defining input (GetItemInputSchema: itemId string) and output (GetItemOutputSchema: full item fields including nested children) for validation in the get-item tool.

  export const GetItemInputSchema = z.object({
  	itemId: z.string().min(1, "itemId must not be empty").describe("HackerNews item ID"),
  });
  
  /**
   * Output schema for get-item tool (ItemResult with nested children)
   */
  export const GetItemOutputSchema = z.object({
  	id: z.string(),
  	created_at: z.string().datetime(),
  	created_at_i: z.number().int().positive(),
  	type: z.enum(["story", "comment", "poll", "pollopt"]),
  	author: z.string(),
  	title: z.string().nullable(),
  	url: z.string().url().nullable(),
  	text: z.string().nullable(),
  	points: z.number().int().nonnegative().nullable(),
  	parent_id: z.number().int().positive().nullable(),
  	story_id: z.number().int().positive(),
  	options: z.array(z.number().int()),
  	children: z.array(z.any()), // Recursive type, validated at runtime
  });

• src/tools/get-item.ts:79-112 (registration)

  Tool metadata (getItemTool) for MCP registration: name, detailed description, and JSON schema for input validation.

  export const getItemTool = {
  	name: "get-item",
  	description: `Retrieve detailed information about a specific HackerNews item by ID.
  
  Returns complete item details including the full nested comment tree. Use this to:
  - View a story with all comments
  - Read a specific comment with its replies
  - Explore discussion threads in depth
  - Get complete metadata for any item
  
  Features:
  - Full nested comment tree (all levels)
  - Complete item metadata (title, url, text, points, author, etc.)
  - Works for stories, comments, polls, and poll options
  - Includes creation time and item type
  
  Examples:
  - Get story with comments: { "itemId": "38456789" }
  - Get specific comment: { "itemId": "38456790" }
  - Get poll: { "itemId": "126809" }
  
  Note: Large comment threads (>500 comments) may take 2-3 seconds to load due to nested fetching.
  Returns error if item doesn't exist or has been deleted.`,
  	inputSchema: {
  		type: "object",
  		properties: {
  			itemId: {
  				type: "string",
  				description: "HackerNews item ID (e.g., '38456789')",
  			},
  		},
  		required: ["itemId"],
  	},
  };

• src/index.ts:45-55 (registration)

  Registration of getItemTool in the server's ListToolsRequestHandler response, making it discoverable by MCP clients.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
  	return {
  		tools: [
  			searchPostsToolMetadata,
  			getFrontPageTool,
  			getLatestPostsTool,
  			getItemTool,
  			getUserTool,
  		],
  	};
  });

• src/index.ts:75-76 (registration)

  Dispatch registration in the central CallToolRequestHandler switch statement, routing 'get-item' calls to getItemHandler.

  case "get-item":
  	return await getItemHandler(args);