Hacker News MCP Server

# 📰 Hacker News MCP Server [](https://github.com/yourusername/hackernews-mcp/actions) [](LICENSE) <!-- Coming soon --> <!-- [](https://www.npmjs.com/package/ --> A Model Context Protocol (MCP) server that provides tools to fetch and interact with Hacker News content. This server enables AI assistants to access real-time Hacker News data including top stories, story details, comments, and search functionality. <a href="https://glama.ai/mcp/servers/@GeorgeNance/hackernews-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@GeorgeNance/hackernews-mcp/badge" alt="Hacker News Server MCP server" /> </a> ## 🚀 Features ### 🛠️ Available Tools - **`get_top_stories`** - Fetch the latest top stories from Hacker News - Configurable count (1-100 stories) - Optional text content inclusion - Returns story metadata including title, URL, score, author, and comment count - **`get_story_details`** - Get detailed information about a specific story - Fetch complete story metadata - Optional comment inclusion with threaded structure - Optional markdown content extraction from linked articles - **`get_story_comments`** - Retrieve popular comments for a story - Configurable minimum score filtering - Adjustable comment thread depth (1-10 levels) - Limit number of comments returned (1-100) - Formatted as readable text with thread structure - **`search_stories`** - Search recent stories by keywords - Search through story titles, content, and URLs - Configurable time range (1-168 hours) - Limit results (1-50 stories) ## 📋 Prerequisites - Node.js 18+ - npm or yarn - An MCP-compatible client (like Claude Desktop) ## 🔧 Installation ### 1. Clone the repository ```bash git clone https://github.com/yourusername/hackernews-mcp.git cd hackernews-mcp ``` ### 2. Install dependencies ```bash npm install ``` ### 3. Build the server ```bash npm run build ``` ## 🎯 Usage ### With Claude Desktop Add the server to your Claude Desktop configuration: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%/Claude/claude_desktop_config.json` ```json { "mcpServers": { "hackernews-mcp": { "command": "node", "args": ["/path/to/hackernews-mcp/build/index.js"] } } } ``` ### With Other MCP Clients The server communicates via stdio and can be used with any MCP-compatible client: ```bash node build/index.js ``` ## 🔍 Example Usage Once connected, you can ask your AI assistant things like: - "What are the top stories on Hacker News today?" - "Get details about Hacker News story 12345678" - "Show me comments for that viral AI story" - "Search for recent stories about TypeScript" ## 🛠️ Development ### Build the project ```bash npm run build ``` ### Watch mode for development ```bash npm run watch ``` ### Lint and format the code ```bash npm run lint npm run format ``` ### Run the MCP Inspector For debugging and testing: ```bash npm run inspector ``` This will start the MCP Inspector, providing a web interface to test the server's tools and inspect the communication. ## 📦 Code Quality & Contributing - **Code Quality:** This project enforces code quality and style using [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/). All code is checked in CI (GitHub Actions) and must pass linting and formatting before merging. - **Type Safety:** All tool handlers use explicit type guards for runtime argument validation and robust TypeScript types. - **CI/CD:** Every push and pull request runs the full build, lint, and (future) test suite via GitHub Actions. - **How to Contribute:** 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Run `npm run lint` and `npm run format` before pushing 5. Push to the branch (`git push origin feature/amazing-feature`) 6. Open a Pull Request ## 📚 API Reference ### get_top_stories ```typescript { count?: number; // Number of stories (1-100, default: 30) include_text?: boolean; // Include story text content (default: false) } ``` ### get_story_details ```typescript { story_id: number; // Required: HN story ID include_comments?: boolean; // Include comments (default: false) include_markdown?: boolean; // Extract article as markdown (default: false) } ``` ### get_story_comments ```typescript { story_id: number; // Required: HN story ID min_score?: number; // Minimum comment score (default: 1) max_depth?: number; // Max thread depth (1-10, default: 3) limit?: number; // Max comments (1-100, default: 20) } ``` ### search_stories ```typescript { query: string; // Required: Search keywords limit?: number; // Max results (1-50, default: 20) time_range_hours?: number; // Hours to search back (1-168, default: 24) } ``` ## 🏗️ Architecture The server is built with: - **TypeScript** for type safety and developer experience - **@modelcontextprotocol/sdk** for MCP protocol implementation - **axios** for HTTP requests to Hacker News API - **jsdom** and **turndown** for HTML to Markdown conversion - **private-ip** for security (blocks private IP access) ### Key Components - `src/index.ts` - Main server implementation with tool handlers - `src/fetcher.ts` - Utility class for fetching and converting web content - `build/` - Compiled JavaScript output (auto-generated) ## 🔒 Security - Blocks requests to private IP addresses to prevent local network access - Rate limiting through Hacker News API natural limits - Input validation for all tool parameters - Error handling and graceful degradation ## 📜 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🙏 Acknowledgments - [Hacker News](https://news.ycombinator.com/) for providing the excellent API - [Model Context Protocol](https://modelcontextprotocol.io/) for the standard - The open source community for the amazing tools and libraries ## 📞 Support If you encounter any issues or have questions: 1. Check the [Issues](https://github.com/yourusername/hackernews-mcp/issues) page 2. Use the MCP Inspector for debugging: `npm run inspector` 3. Create a new issue with detailed information about your problem --- Made with ❤️ for the MCP community