HackerNews MCP Server

Instructions

Implementation Reference

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

  The main execution logic for the get-user tool. Validates input, calls HN API to fetch user profile, validates output, and handles errors including not found.
  /** * Get user handler * * @param input - Input parameters (username) * @returns Tool result with user profile information */ 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:13-38 (schema)

  Zod schemas used for input validation and output parsing in the handler, defining the expected structure and constraints for username input and user profile output.
  /** * Input schema for 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"), }); /** * Output schema for get-user tool (HNUser) */ export const GetUserOutputSchema = z.object({ username: z.string(), karma: z.number().int().nonnegative(), about: z.string().nullable().optional(), created: z.number().int().positive().optional(), }); /** * Type for validated input */ export type GetUserInput = z.infer<typeof GetUserInputSchema>;
• src/tools/get-user.ts:71-111 (registration)

  Tool metadata exported for registration with MCP server, including name, detailed description, and JSON schema for input.
  /** * Tool metadata for MCP 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)

  Registers the get-user tool (via getUserTool) in the server's list of available tools.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ searchPostsToolMetadata, getFrontPageTool, getLatestPostsTool, getItemTool, getUserTool, ], }; });
• src/index.ts:78-80 (registration)

  Routes incoming 'get-user' tool calls to the getUserHandler function in the main request handler.
  case "get-user": return await getUserHandler(args);