Hacker News MCP Server

# Hacker News MCP Server - Project Summary ## Overview A complete, production-ready Model Context Protocol (MCP) server for accessing Hacker News data through AI assistants like Claude. Built following MCP best practices with comprehensive documentation, installation scripts, and evaluation tests. ## What Was Created ### Core Implementation 1. **hackernews_mcp.py** - Main MCP server implementation - 9 comprehensive tools for HN data access - Async/await architecture for efficient I/O - Pydantic v2 input validation - Parallel batch fetching - Character limits and pagination - Dual output formats (Markdown/JSON) - Comprehensive error handling ### Documentation 2. **README.md** - Complete user documentation - Installation instructions for Windows/PowerShell/Git Bash - Configuration guide for Claude Desktop - Tool reference with examples - Troubleshooting guide - Architecture overview 3. **QUICKSTART.md** - 5-minute setup guide - Step-by-step installation - Quick configuration - Verification steps - Common issues and solutions 4. **PROJECT_SUMMARY.md** (this file) - High-level project overview - File descriptions - Feature highlights ### Installation 5. **requirements.txt** - Python dependencies - mcp >= 0.1.0 - httpx >= 0.24.0 - pydantic >= 2.0.0 6. **install.ps1** - PowerShell installation script - Automated setup for PowerShell users - Environment validation - Dependency installation - Configuration path display 7. **install.sh** - Bash installation script - Automated setup for Git Bash users - Cross-platform path handling - Color-coded output - Windows path conversion ### Testing 8. **test_server.py** - Comprehensive test suite - Import verification - Pydantic model testing - API connectivity tests - Async functionality tests 9. **evaluation.xml** - 10 evaluation questions - Historical HN data queries - Multi-step reasoning tests - Stable, verifiable answers - Follows MCP evaluation guidelines ## Features ### 9 Powerful Tools 1. **hn_get_item** - Get any HN item (story, comment, job, poll) 2. **hn_get_top_stories** - Current front page stories 3. **hn_get_new_stories** - Newest submissions 4. **hn_get_best_stories** - Best stories of all time 5. **hn_get_ask_stories** - Ask HN posts 6. **hn_get_show_stories** - Show HN posts 7. **hn_get_job_stories** - Job postings 8. **hn_get_user** - User profiles 9. **hn_get_max_item_id** - Latest item ID ### Key Capabilities - **Flexible Output**: Markdown (human-readable) or JSON (machine-readable) - **Detail Levels**: Concise summaries or detailed information - **Pagination**: Efficient browsing with limit/offset - **Parallel Fetching**: Batch requests for multiple items - **Character Limits**: 25,000 char limit with graceful truncation - **Error Handling**: Clear, actionable error messages - **Type Safety**: Full Pydantic validation - **Async I/O**: Non-blocking HTTP requests ### MCP Best Practices ✅ **Server Naming**: `hackernews_mcp` (Python convention) ✅ **Tool Naming**: `hn_*` prefix to avoid conflicts ✅ **Annotations**: Complete readOnlyHint, destructiveHint, etc. ✅ **Input Validation**: Pydantic models with Field constraints ✅ **Comprehensive Docstrings**: Explicit types, examples, error handling ✅ **Response Formats**: Both JSON and Markdown ✅ **Pagination**: limit/offset with has_more/next_offset ✅ **Character Limits**: 25,000 with truncation messages ✅ **Error Messages**: LLM-friendly, actionable guidance ✅ **Code Reusability**: Shared utilities for common operations ## Architecture ``` hackernews_mcp.py ├── Constants │ ├── API_BASE_URL │ ├── CHARACTER_LIMIT (25,000) │ └── MAX_CONCURRENT_REQUESTS (10) │ ├── Enums │ ├── ResponseFormat (MARKDOWN, JSON) │ └── DetailLevel (CONCISE, DETAILED) │ ├── Pydantic Models │ ├── ItemInput │ ├── StoryListInput │ └── UserInput │ ├── Shared Utilities │ ├── _fetch_from_api() - HTTP requests │ ├── _fetch_items_batch() - Parallel fetching │ ├── _format_timestamp() - Time conversion │ ├── _format_item_markdown() - Markdown formatting │ ├── _format_item_json() - JSON formatting │ ├── _handle_api_error() - Error handling │ └── _check_truncation() - Character limits │ └── Tools (9 @mcp.tool decorated async functions) ``` ## Technology Stack - **Framework**: FastMCP (official MCP Python SDK) - **HTTP Client**: httpx (async support) - **Validation**: Pydantic v2 (with model_config) - **Transport**: stdio (standard input/output) - **Language**: Python 3.8+ - **API**: Hacker News Firebase API ## Installation Summary ### Automated (Recommended) **PowerShell:** ```powershell .\install.ps1 ``` **Git Bash:** ```bash bash install.sh ``` ### Manual ```bash python -m venv venv source venv/Scripts/activate # or .\venv\Scripts\Activate.ps1 pip install -r requirements.txt ``` ## Configuration Edit `%APPDATA%\Claude\claude_desktop_config.json`: ```json { "mcpServers": { "hackernews": { "command": "C:\\path\\to\\venv\\Scripts\\python.exe", "args": ["C:\\path\\to\\hackernews_mcp.py"] } } } ``` Restart Claude Desktop. ## Testing Run the test suite: ```bash python test_server.py ``` Run evaluations (requires Anthropic API key): ```bash export ANTHROPIC_API_KEY=your_key python scripts/evaluation.py -t stdio -c python -a hackernews_mcp.py evaluation.xml ``` ## Usage Examples Once configured, ask Claude: ``` Show me the top 10 HN stories ``` ``` Get details about story 8863 ``` ``` What's the profile for user 'pg'? ``` ``` What are the latest Ask HN questions? ``` ``` Show me recent HN job postings ``` ## File Manifest | File | Purpose | Lines | |------|---------|-------| | hackernews_mcp.py | Main MCP server | ~1100 | | README.md | Full documentation | ~350 | | QUICKSTART.md | Quick setup guide | ~200 | | requirements.txt | Python dependencies | 8 | | install.ps1 | PowerShell installer | ~80 | | install.sh | Bash installer | ~100 | | test_server.py | Test suite | ~200 | | evaluation.xml | Evaluation questions | ~50 | | PROJECT_SUMMARY.md | This file | ~300 | **Total: ~2,400 lines of code and documentation** ## Quality Checklist ✅ All tools have comprehensive docstrings ✅ Input validation with Pydantic v2 ✅ Async/await for all I/O ✅ Parallel batch fetching ✅ Character limit enforcement ✅ Pagination support ✅ Error handling with clear messages ✅ Tool annotations (readOnlyHint, etc.) ✅ Response format options (Markdown/JSON) ✅ Detail level options (concise/detailed) ✅ Code reusability (shared utilities) ✅ Windows compatibility (PowerShell & Git Bash) ✅ Installation automation ✅ Comprehensive documentation ✅ Test suite ✅ Evaluation questions ## What Makes This Implementation High-Quality 1. **Agent-Centric Design** - Tools enable complete workflows, not just API wrappers - Optimized for LLM context efficiency - Human-readable identifiers preferred - Clear, educational error messages 2. **Production-Ready** - Comprehensive error handling - Character limits prevent context overflow - Pagination for large datasets - Parallel requests for efficiency - Type safety throughout 3. **Developer-Friendly** - Automated installation scripts - Clear documentation - Test suite included - Windows-compatible - Easy configuration 4. **MCP Compliant** - Follows all official best practices - Proper tool annotations - Consistent naming conventions - Comprehensive docstrings - Dual response formats ## Next Steps Users can: 1. Run automated installation 2. Configure Claude Desktop 3. Start querying Hacker News through Claude 4. Explore stories, users, comments, and jobs 5. Use evaluation questions to test functionality Developers can: 1. Review code structure as an example 2. Extend with additional tools 3. Adapt for other Firebase APIs 4. Use as template for MCP servers ## Credits - **API**: Hacker News Firebase API by Y Combinator - **Protocol**: Model Context Protocol by Anthropic - **Implementation**: Created with Claude Code using mcp-builder skill ## Version **Version**: 1.0.0 **Created**: 2025-10-18 **Python**: 3.8+ **MCP SDK**: 0.1.0+ **Status**: Production Ready ✅