HackerNews MCP Server

 [](https://github.com/sam3690/Hackernews_mcp/actions/workflows/ci.yml) [](https://badge.fury.io/js/hn-mcp-server) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://modelcontextprotocol.io) # HackerNews MCP Server A Model Context Protocol (MCP) server that provides programmatic access to Hacker News content via the HN Algolia API. This server enables AI assistants like Claude to search stories, retrieve comments, access user profiles, and explore the HN front page in real-time. ## Features - ✅ **9 MCP Tools** for comprehensive HN access - 🔍 **Search**: Stories by relevance or date, comments with filters - 📰 **Browse**: Front page, latest stories, Ask HN, Show HN posts - 👤 **Details**: Retrieve specific stories with nested comments and user profiles - ⚡ **Rate Limiting**: Respects HN API limits (10,000 req/hr) - 🛡️ **Type-Safe**: Full TypeScript with strict mode - 📊 **Observable**: Structured JSON logging with correlation IDs - 🧪 **Tested**: Unit, integration, and contract tests ## Installation ### NPM (when published) ```bash npm install -g hn-mcp-server ``` ### From Source ```bash git clone https://github.com/YOUR_USERNAME/hn-mcp-server.git cd hn-mcp-server npm install npm run build npm link ``` ## Quick Start (VS Code) The fastest way to get started is with VS Code and GitHub Copilot: 1. **Clone and build:** ```bash git clone <your-repo-url> cd hn-mcp-server npm install npm run build ``` 2. **Open in VS Code:** ```bash code . ``` 3. **Reload VS Code** (Ctrl+Shift+P → "Developer: Reload Window") 4. **Follow the complete setup checklist**: [docs/VSCODE_CHECKLIST.md](docs/VSCODE_CHECKLIST.md) 5. **Open Copilot Chat** and try: ``` @workspace What MCP tools are available? ``` or ``` Show me the top stories from Hacker News ``` **📖 Step-by-step setup guide**: [docs/VSCODE_CHECKLIST.md](docs/VSCODE_CHECKLIST.md) **📖 For detailed VS Code setup instructions, see [docs/VSCODE_SETUP.md](docs/VSCODE_SETUP.md)** **⚠️ Tools not appearing?** See [docs/TROUBLESHOOTING_VSCODE.md](docs/TROUBLESHOOTING_VSCODE.md) **💡 Tip**: MCP support in VS Code is experimental. For the best experience, use **Claude Desktop** (see configuration below). ## Configuration ### VS Code with GitHub Copilot The easiest way to use this server is directly in VS Code with GitHub Copilot: 1. **Build the server:** ```bash npm run build ``` 2. **Configuration is already set up** in `.vscode/mcp.json`: ```json { "hackernews": { "command": "node", "args": ["${workspaceFolder}/dist/index.js"], "env": { "DEBUG": "0" } } } ``` 3. **Reload VS Code** or restart the Copilot extension 4. **Test it** by asking Copilot: - "Show me the top stories from Hacker News" - "Search HN for stories about AI" - "Get the user profile for 'pg'" ### Claude Desktop Add to your Claude Desktop configuration: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **Linux**: `~/.config/claude/claude_desktop_config.json` ```json { "mcpServers": { "hackernews": { "command": "hn-mcp-server" } } } ``` Or if installed from source: ```json { "mcpServers": { "hackernews": { "command": "node", "args": ["/path/to/hn-mcp-server/dist/index.js"] } } } ``` Restart Claude Desktop to activate the server. ## Available Tools ### 1. `search_stories` Search HN stories by relevance with advanced filtering. ```typescript { query: "artificial intelligence", // Search term tags: "story,front_page", // Filter by tags numericFilters: "points>=100", // Minimum points page: 0, // Pagination hitsPerPage: 20 // Results per page } ``` ### 2. `search_by_date` Search stories/comments sorted by date (most recent first). ```typescript { query: "TypeScript", tags: "story", numericFilters: "created_at_i>1640000000", // Unix timestamp page: 0, hitsPerPage: 20 } ``` ### 3. `search_comments` Search comments with optional story/author filtering. ```typescript { query: "React hooks", tags: "author_pg", // Filter by author sortByDate: false, // Sort by relevance page: 0, hitsPerPage: 20 } ``` ### 4. `get_front_page` Retrieve current HN front page stories. ```typescript { page: 0, hitsPerPage: 30 } ``` ### 5. `get_latest_stories` Get most recently submitted stories. ```typescript { page: 0, hitsPerPage: 20 } ``` ### 6. `get_ask_hn` Retrieve Ask HN posts (community questions). ```typescript { page: 0, hitsPerPage: 20 } ``` ### 7. `get_show_hn` Retrieve Show HN posts (project showcases). ```typescript { page: 0, hitsPerPage: 20 } ``` ### 8. `get_story` Get a specific story by ID with full nested comment tree. ```typescript { id: 8863 // Famous "How to Start a Startup" post } ``` ### 9. `get_user` Retrieve user profile by username. ```typescript { username: "pg" // Paul Graham } ``` ## Example Usage in Claude **Search for AI stories:** ``` Show me the top stories about AI from Hacker News ``` **Get front page:** ``` What's currently on the Hacker News front page? ``` **Find user information:** ``` Tell me about the HN user 'pg' ``` **Advanced search:** ``` Find recent stories about TypeScript with at least 50 points ``` ## Development ### Prerequisites - Node.js 20 LTS or higher - npm or yarn ### Setup ```bash git clone https://github.com/YOUR_USERNAME/hn-mcp-server.git cd hn-mcp-server npm install ``` ### Commands ```bash npm run build # Compile TypeScript npm run dev # Watch mode npm test # Run all tests npm run test:watch # Test watch mode npm run lint # Lint code npm run format # Format code npm run check # Lint + type check npm run ci # Full CI workflow ``` ### Project Structure ``` src/ ├── index.ts # Main entry point ├── server.ts # MCP server initialization ├── tools/ # MCP tool implementations (one per file) │ ├── search-stories.ts │ ├── get-story.ts │ └── ... ├── lib/ # Shared utilities │ ├── hn-client.ts # HN API client │ ├── rate-limiter.ts │ ├── logger.ts │ ├── errors.ts │ └── validators.ts └── types/ # TypeScript type definitions ├── hn-api.ts └── mcp.ts ``` ## Rate Limiting The HN Algolia API has a limit of **10,000 requests per hour** per IP address. This server: - Tracks request count automatically - Warns at 90% (9,000 requests) - Throws error at 95% (9,500 requests) - Resets counter every hour ## Logging Structured JSON logging with correlation IDs: ```bash # Enable debug logging DEBUG=1 hn-mcp-server # View logs in Claude Desktop # macOS: ~/Library/Logs/Claude/mcp*.log # Windows: %APPDATA%\Claude\logs\mcp*.log # Linux: ~/.config/claude/logs/mcp*.log ``` ## Error Handling All errors return MCP-formatted responses with: - Clear error messages - Error codes (RATE_LIMIT_EXCEEDED, ITEM_NOT_FOUND, etc.) - Context for debugging - Suggested user actions ## Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Make your changes following the constitution principles 4. Run quality gates (`npm run ci`) 5. Commit (`git commit -m 'Add amazing feature'`) 6. Push (`git push origin feature/amazing-feature`) 7. Open a Pull Request ## License MIT License - see [LICENSE](LICENSE) file for details. ## Links - [HN Algolia API Documentation](https://hn.algolia.com/api) - [Model Context Protocol](https://modelcontextprotocol.io) - [Claude Desktop](https://claude.ai/desktop) ## Support - Issues: [GitHub Issues](https://github.com/YOUR_USERNAME/hn-mcp-server/issues) - Discussions: [GitHub Discussions](https://github.com/YOUR_USERNAME/hn-mcp-server/discussions) --- Built with ❤️ following MCP best practices and constitution principles