HackerNews MCP Server

Instructions

Implementation Reference

• src/tools/get-user.ts:45-69 (handler)

  The getUserHandler function that executes the tool: validates input with Zod schema, fetches user profile via HNAPIClient, checks existence, validates output, handles errors, and returns MCP CallToolResult.

  export async function getUserHandler(input: unknown): Promise<CallToolResult> {
  	try {
  		// Validate input
  		const validatedParams = GetUserInputSchema.parse(input);
  
  		// Create API client
  		const client = new HNAPIClient();
  
  		// Call users API to get profile
  		const result = await client.getUser(validatedParams.username);
  
  		// Check if user exists
  		const notFoundError = checkItemExists(result, "User", validatedParams.username);
  		if (notFoundError) {
  			return notFoundError;
  		}
  
  		// Validate output
  		const validatedResult = GetUserOutputSchema.parse(result);
  
  		return createSuccessResult(validatedResult);
  	} catch (error) {
  		return handleAPIError(error, "get-user");
  	}
  }

• src/tools/get-user.ts:16-22 (schema)

  Zod schema for validating the input parameter 'username' of the get-user tool.

  export const GetUserInputSchema = z.object({
  	username: z
  		.string()
  		.min(1, "username must not be empty")
  		.regex(/^[a-zA-Z0-9_]+$/, "username must be alphanumeric with underscores only")
  		.describe("HackerNews username"),
  });

• src/tools/get-user.ts:27-32 (schema)

  Zod schema for validating the output user profile data returned by the HackerNews API.

  export const GetUserOutputSchema = z.object({
  	username: z.string(),
  	karma: z.number().int().nonnegative(),
  	about: z.string().nullable().optional(),
  	created: z.number().int().positive().optional(),
  });

• src/tools/get-user.ts:74-111 (registration)

  The getUserTool metadata object defining the tool's name, detailed description, and input schema for MCP server registration.

  export const getUserTool = {
  	name: "get-user",
  	description: `Retrieve public profile information for a HackerNews user.
  
  Returns user profile including karma, bio, and account creation date. Use this to:
  - Check user reputation (karma score)
  - Read user bio and about information
  - See when account was created
  - Verify user existence before searching their content
  
  Features:
  - Username (case-sensitive)
  - Karma score (total upvotes received)
  - About/bio text (may contain HTML)
  - Account creation date (Unix timestamp)
  
  Examples:
  - Get famous user: { "username": "pg" }
  - Check moderator: { "username": "dang" }
  - Verify author: { "username": "tptacek" }
  
  Username validation:
  - Alphanumeric characters and underscores only
  - Case-sensitive
  - Must exist on HackerNews
  
  Returns error if user doesn't exist or username format is invalid.`,
  	inputSchema: {
  		type: "object",
  		properties: {
  			username: {
  				type: "string",
  				description: "HackerNews username (alphanumeric + underscores, e.g., 'pg')",
  			},
  		},
  		required: ["username"],
  	},
  };

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

  Registration of the get-user tool in the MCP server's listTools handler, including getUserTool in the returned tools array.

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

• src/index.ts:78-80 (registration)

  Dispatch registration in the MCP server's callTool handler switch statement, routing 'get-user' calls to getUserHandler.

  case "get-user":
  	return await getUserHandler(args);