{"id":29360052,"url":"https://github.com/traves-theberge/hackernews-mcp-typescript","last_synced_at":"2026-05-17T17:01:28.962Z","repository":{"id":303116563,"uuid":"1014445061","full_name":"Traves-Theberge/Hackernews-MCP-Typescript","owner":"Traves-Theberge","description":"HackerNews MCP Server - A comprehensive Model Context Protocol (MCP) server that provides seamless integration with the HackerNews API","archived":false,"fork":false,"pushed_at":"2025-07-05T19:09:44.000Z","size":115,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-05T20:27:23.054Z","etag":null,"topics":["hacker-news","hackernews","hackernews-api","mcp","mcp-server","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Traves-Theberge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-05T18:33:15.000Z","updated_at":"2025-07-05T20:19:16.000Z","dependencies_parsed_at":"2025-07-05T20:37:31.415Z","dependency_job_id":null,"html_url":"https://github.com/Traves-Theberge/Hackernews-MCP-Typescript","commit_stats":null,"previous_names":["traves-theberge/hackernews-mcp-typescript"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Traves-Theberge/Hackernews-MCP-Typescript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Traves-Theberge%2FHackernews-MCP-Typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Traves-Theberge%2FHackernews-MCP-Typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Traves-Theberge%2FHackernews-MCP-Typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Traves-Theberge%2FHackernews-MCP-Typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Traves-Theberge","download_url":"https://codeload.github.com/Traves-Theberge/Hackernews-MCP-Typescript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Traves-Theberge%2FHackernews-MCP-Typescript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278548013,"owners_count":26004818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacker-news","hackernews","hackernews-api","mcp","mcp-server","typescript"],"created_at":"2025-07-09T07:09:32.208Z","updated_at":"2025-10-06T02:22:11.843Z","avatar_url":"https://github.com/Traves-Theberge.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HackerNews MCP Server\n\nA comprehensive Model Context Protocol (MCP) server that provides seamless integration with the HackerNews API, enabling AI assistants to access, analyze, and understand HackerNews content through standardized MCP interfaces.\n\n## 🚀 Quick Start\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Start the server\nnpm start\n```\n\nThen restart your MCP-compatible client (like Cursor) to connect to the server.\n\n## ✨ Features\n\n### 🔧 Tools (5 Interactive Commands)\n\n1. **`search_posts`** - Search and filter HackerNews posts\n   - Filter by keywords, author, score, and date range\n   - Example: *\"Find stories about 'AI' with score \u003e 100\"*\n\n2. **`get_post`** - Get comprehensive post details\n   - Includes metadata, comment trees, and engagement metrics\n   - Example: *\"Get full details of story 44473319 with comments\"*\n\n3. **`search_user`** - Analyze user profiles and activity\n   - User statistics, top stories, and contribution patterns\n   - Example: *\"Analyze user 'pg' and show their activity\"*\n\n4. **`search_trending`** - Find current trending topics\n   - Keyword frequency analysis from top stories\n   - Example: *\"What topics are trending on HackerNews today?\"*\n\n5. **`search_comments`** - Analyze comment engagement\n   - Comment statistics, top commenters, and discussion patterns\n        - Example: *\"Analyze the comments on story 44473319\"*\n\n## 🛠️ Installation \u0026 Setup\n\n### Prerequisites\n- Node.js 18+ \n- npm or yarn\n\n### Installation Steps\n\n1. **Clone and install:**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd hackernews-mcp-server\n   npm install\n   ```\n\n2. **Build the project:**\n   ```bash\n   npm run build\n   ```\n\n3. **Configure MCP client (Cursor):**\n   - The `.cursor/mcp.json` file is already configured\n   - Restart Cursor to load the MCP server\n\n4. **Start using:**\n   ```bash\n   npm start\n   ```\n\n## 🎮 Real Usage Examples (Tested \u0026 Working)\n\n### 🔍 Search Posts - Find Stories by Topic\n\n```bash\n# What we tested:\nsearch_posts with query=\"AI\", minScore=50, limit=10\n\n# Results we got:\n- \"'Positive review only': Researchers hide AI prompts in papers\" (100 points, 52 comments)\n- \"Cops in [Spain] think everyone using a Google Pixel must be a drug dealer\" (65 points, 50 comments)\n```\n\n**Use cases:**\n- Find high-engagement stories on specific topics\n- Filter by author, score thresholds, or date ranges\n- Research trending discussions in your field\n\n### 📄 Get Post Details - Deep Story Analysis\n\n```bash\n# What we tested:\nget_post for story ID 44473319 (AI prompts story)\n\n# What we learned:\n- Full story metadata (age: 3.2 hours, domain: asia.nikkei.com)\n- Complete comment tree (57 comments from 38 authors)\n- Engagement metrics and discussion quality\n```\n\n**Use cases:**\n- Analyze specific stories that interest you\n- Get complete comment discussions\n- Understand community reaction to news\n\n### 👤 Search Users - Profile Analysis\n\n```bash\n# What we tested:\nsearch_user for \"zczc\" (Google Pixel story author)\n\n# What we discovered:\n- 8.6 years on HN, 876 karma, steady contributor\n- Research-oriented: provides primary sources\n- Cross-domain expertise: tech, policy, programming\n- Quality over quantity approach\n```\n\n**Use cases:**\n- Research authors of interesting posts\n- Find domain experts and thought leaders\n- Understand user contribution patterns\n\n### 📈 Search Trending - Topic Analysis\n\n```bash\n# What we tested:\nsearch_trending analyzing 49 current top stories\n\n# Current trends we found:\n- \"software\", \"game\", \"first\" (6.1% each)\n- \"systems\", \"local\", \"google\" (4.1% each)\n- Space tech: \"satellite\", \"geostationary\"\n- Focus on local-first software and gaming\n```\n\n**Use cases:**\n- Track what the tech community is discussing\n- Identify emerging technology trends\n- Monitor shifts in community interests\n\n### 💬 Search Comments - Discussion Analysis\n\n```bash\n# What we tested:\nsearch_comments on the Google Pixel Spain story\n\n# What we found:\n- 56 comments from 38 unique authors\n- Active discussion (multiple users with 4+ comments)\n- International perspectives on privacy/surveillance\n- Quality moderation (5 deleted, 1 flagged)\n```\n\n**Use cases:**\n- Analyze community sentiment on topics\n- Find the most engaged discussants\n- Understand discussion quality and patterns\n\n## 🏗️ Architecture\n\n### Smart Caching System\n- **Three-tier caching**: Items, users, and story lists\n- **Configurable TTL**: Default 5 minutes, adjustable\n- **LRU eviction**: Automatic cleanup when cache is full\n- **Performance**: Reduces API calls by ~80%\n\n### API Client Features\n- **Comprehensive coverage**: All HackerNews API endpoints\n- **Batch operations**: Efficient multiple item loading\n- **Error handling**: Robust retry and timeout logic\n- **Rate limiting**: Respectful API usage\n\n### Enhanced Data\n- **Story metadata**: Age, domain, comment count calculations\n- **User statistics**: Average scores, top stories, activity patterns\n- **Comment analysis**: Engagement metrics, discussion trees\n- **Trending analysis**: Keyword frequency, topic extraction\n\n## 🔧 Configuration\n\nEnvironment variables (optional):\n\n```env\n# Server Configuration\nSERVER_NAME=hackernews-mcp-server\nSERVER_VERSION=1.0.0\n\n# API Configuration\nHACKERNEWS_API_BASE_URL=https://hacker-news.firebaseio.com/v0\nHACKERNEWS_API_TIMEOUT=10000\n\n# Cache Configuration\nCACHE_TTL_SECONDS=300\nCACHE_MAX_SIZE=1000\n\n# Logging\nLOG_LEVEL=info\n```\n\n## 🧪 Development\n\n```bash\n# Development mode with hot reload\nnpm run dev\n\n# Run tests\nnpm test\n\n# Lint code\nnpm run lint\nnpm run lint:fix\n\n# Type checking\nnpm run build\n```\n\n## 📊 MCP Tools \u0026 Capabilities\n\nWhat you can actually do with our tested tools:\n\n| MCP Tool | What It Does | Real Example From Our Testing |\n|----------|--------------|-------------------------------|\n| `search_posts` | Find stories by criteria | Found 2 AI stories with 100+ and 65 points |\n| `get_post` | Get full story details | Analyzed AI prompts story with 57 comments |\n| `search_user` | Profile analysis | Profiled \"zczc\" - 8.6yr veteran, quality contributor |\n| `search_trending` | Topic analysis | Found \"software\", \"game\", \"systems\" trending |\n| `search_comments` | Discussion analysis | Analyzed 56 comments, 38 authors on Pixel story |\n\n**Resource Access Patterns:**\n- `hackernews://stories/top` → Current top stories\n- `hackernews://user/username` → User profiles  \n- `hackernews://item/12345` → Individual posts\n- `hackernews://comments/12345` → Comment trees\n\n## 🤝 Real-World Use Cases (Based on Our Testing)\n\n### 📰 Content Research \u0026 Analysis\n- **Find breaking tech stories**: Like our AI prompts in papers discovery (100 points, active discussion)\n- **Track controversial topics**: Privacy issues like the Google Pixel profiling story\n- **Analyze discussion quality**: 57 comments from 38 authors shows real engagement\n- **Monitor emerging trends**: Space tech, local-first software, gaming developments\n\n### 👥 Community Intelligence\n- **Identify quality contributors**: Found \"zczc\" as research-oriented, cross-domain expert\n- **Understand user patterns**: 8.6 years, steady karma growth, source verification habits\n- **Find domain experts**: Users with consistent high-quality contributions\n- **Track thought leaders**: Active users in specific technology areas\n\n### 📈 Trend \u0026 Sentiment Analysis\n- **Current tech focus**: \"software\", \"systems\", \"game\" trending at 6.1% each\n- **Emerging technologies**: Satellite/space tech discussions increasing\n- **Community sentiment**: International privacy concerns, academic integrity debates\n- **Discussion patterns**: Quality moderation, international perspectives\n\n### 🔍 Research Applications\n- **Academic research**: Study tech community discussions and sentiment\n- **Market research**: Understand developer and tech community interests\n- **Competitive intelligence**: Monitor discussions about technologies and companies\n- **Content strategy**: Find topics that generate high engagement\n\n## 🚀 Performance\n\n- **Caching**: 80% reduction in API calls\n- **Batch operations**: 3x faster multi-item loading\n- **Smart filtering**: Client-side search reduces server load\n- **Concurrent requests**: Parallel processing for efficiency\n\n## 🔒 Privacy \u0026 Ethics\n\n- **Public data only**: No private information access\n- **Respectful usage**: Rate limiting and caching\n- **No data storage**: Temporary caching only\n- **Transparent**: Open source implementation\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **Server won't start**\n   ```bash\n   # Check Node.js version\n   node --version  # Should be 18+\n   \n   # Rebuild the project\n   npm run build\n   ```\n\n2. **MCP connection issues**\n   - Restart your MCP client (Cursor)\n   - Check `.cursor/mcp.json` configuration\n   - Verify server is running with `npm start`\n\n3. **API errors**\n   - Check network connectivity\n   - Verify HackerNews API is accessible\n   - Check cache configuration\n\n### Debug Mode\n\n```bash\n# Enable debug logging\nLOG_LEVEL=debug npm start\n\n# Check cache statistics\n# Use the hackernews://cache/stats resource\n```\n\n## 📈 Roadmap\n\n- [ ] Real-time WebSocket updates\n- [ ] Advanced sentiment analysis\n- [ ] User network analysis\n- [ ] Export functionality\n- [ ] Custom filtering rules\n- [ ] Performance dashboard\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit changes (`git commit -m 'Add amazing feature'`)\n4. Push to branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n\n---\n\n## 🎉 **Ready to Explore HackerNews Like Never Before?**\n\n### 🚀 **Quick Start Command**\n```bash\nnpm run build \u0026\u0026 npm start\n```\n\n### 💬 **Start Your First Conversation**\nAsk your AI assistant:\n- *\"What are the top AI stories on HackerNews right now?\"*\n- *\"Find trending topics in the tech community today\"*\n- *\"Analyze the most discussed story this week\"*\n\n---\n\n## 🙏 **Acknowledgments \u0026 Credits**\n\n### 🧡 **Special Thanks to HackerNews**\n\u003e *\"The best technology discussions happen here\"*\n\nWe're incredibly grateful to **HackerNews** and **Y Combinator** for:\n\n🌟 **Creating the world's best tech community**  \n📡 **Providing free, real-time API access**  \n🔥 **Fostering incredible discussions that inspire innovation**  \n🚀 **Building a platform where the future of tech is discussed daily**\n\n### ⚡ **Powered By**\n- 🔗 **[HackerNews API](https://github.com/HackerNews/API)** - The data that drives everything\n- 🛠️ **[Model Context Protocol](https://modelcontextprotocol.io)** - The standard that makes it possible\n- 💝 **Open Source Community** - The spirit that keeps us building\n\n---\n\n## 📜 **License \u0026 Usage**\n\n### 🆓 **This MCP Server**\n**MIT License** - Use it, modify it, share it! See [LICENSE](LICENSE) file.  \n**Created by**: Traves Theberge \u003cTraves.Theberge@gmail.com\u003e\n\n### 📊 **HackerNews API**\n**Free for non-commercial use** - Respect the community that creates the content.  \n**Commercial usage**: Check [Y Combinator's terms](https://github.com/HackerNews/API)\n\n---\n\n## 🌟 **Join the Community**\n\n**Found a bug?** Open an issue!  \n**Have an idea?** Start a discussion!  \n**Want to contribute?** PRs welcome!  \n\n### 🔗 **Connect**\n- 📧 **Email**: Traves.Theberge@gmail.com\n- 🐙 **GitHub**: [This Repository](.)\n- 🗨️ **Discussions**: Share your HackerNews insights!\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### 🧡 **Keep Hacking, Keep Exploring!** 🧡\n\n*Built with ❤️ for the HackerNews community*\n\n**[⭐ Star this repo](.) • [🍴 Fork it](.) • [📝 Contribute](.)**\n\n\u003c/div\u003e \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftraves-theberge%2Fhackernews-mcp-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftraves-theberge%2Fhackernews-mcp-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftraves-theberge%2Fhackernews-mcp-typescript/lists"}