hacker-news-mcp

<div align="center"> # 🚀 黑客新闻 MCP 服务器 **将实时黑客新闻数据和讨论轻松融入您的 LLM、代理或应用程序工作流的最佳方式。** [](https://fastmcp.readthedocs.io/) [](https://github.com/HackerNews/API) [](LICENSE) <!-- 可选添加 GIF 或截图 --> <!--  --> </div> --- > **立即将黑客新闻转化为可编程的对话式知识库，供您的 AI 代理和应用程序使用！** --- ## ✨ 为什么使用此工具？ - **即插即用**：立即连接 LLMs、代理或聊天机器人到实时的黑客新闻数据和讨论。 - **灵活**：用作本地工具、云 API 或容器化微服务。 - **自然语言友好**：用户可以通过标题、关键词或自然语言引用故事（“人们对量子计算怎么看？”）。 - **丰富的提示**：内置的摘要、趋势话题、用户分析等提示模板。 - **生产就绪**：强大的错误处理、健康检查和云部署支持开箱即用。 --- ## 🌟 功能 - ⚡ **多种传输模式**：STDIO/MCP 和 SSE/MCP，适用于灵活的 LLM/代理集成 - 🌐 **REST/OpenAPI 端点**：直接 HTTP 访问，自动生成文档 - 📰 **完整的黑客新闻覆盖**：访问故事、评论、用户、趋势话题等 - 🛡️ **强大的错误处理**：清晰的响应模型和状态码 - 🧩 **简单的配置**：环境变量配置 API 密钥、主机和日志记录 - 🐳 **容器就绪**：Docker 和 Docker Compose，实现无痛部署 - ❤️ **健康监测**：内置健康检查端点 - 🔒 **CORS 支持**：安全的、可配置的跨域资源共享 --- ## 📚 API 端点 所有端点默认情况下均可在 `http://localhost:8000`（或您配置的主机/端口）访问。 ### 🔎 REST API 端点 #### **故事** - `GET /api/stories/top?limit=30` — 获取热门故事 - `GET /api/stories/best?limit=30` — 获取最佳故事 - `GET /api/stories/new?limit=30` — 获取最新故事 - `GET /api/stories/ask?limit=30` — 获取 Ask HN 故事 - `GET /api/stories/show?limit=30` — 获取 Show HN 故事 - `GET /api/stories/search?query=您的查询&limit=5` — 按标题或关键词搜索故事 - `GET /api/stories/by-date?days_ago=1&limit=30` — 获取 N 天前的故事 #### **故事详情** - `GET /api/item/{item_id}` — 按 ID 获取黑客新闻项目 - `GET /api/story/by-title?title=您的标题` — 按标题/关键词获取故事（及评论） - `GET /api/story/{story_id}/comments?comment_limit=10` — 获取故事及其顶部评论 #### **内容检索** - `GET /api/story/{story_id}/content?format=markdown` — 从故事的 URL 获取实际内容 - `GET /api/story/content-by-title?title=您的标题&format=markdown` — 按故事标题获取内容 - `format` 参数接受 `markdown`（默认）或 `json` #### **用户** - `GET /api/user/{username}` — 按用户名获取黑客新闻用户 #### **系统与更新** - `GET /api/maxitem` — 获取当前最大的项目 ID - `GET /api/updates` — 获取最新的项目和配置文件更改 - `GET /health` — 健康检查端点 - `GET /sse-info` — 关于 SSE 端点的信息 #### **SSE 与 MCP** - `GET /sse` — 服务器发送事件（SSE）端点，用于 MCP 协议 #### **OpenAPI 与文档** - `GET /docs` — Swagger UI（交互式 API 文档） - `GET /openapi.json` — OpenAPI 模式（用于工具集成） ### 🗣️ 自然语言与基于标题的查询 您可以使用自然语言或关键词搜索和检索故事，而不仅仅是数字 ID！ - **示例：** - `GET /api/stories/search?query=量子计算` — 查找关于量子计算的故事 - `GET /api/story/by-title?title=React 框架` — 获取关于 React 框架的最新故事和评论 - **自然语言友好：** - “告诉我昨天关于量子计算的故事” - “人们对新 React 框架怎么看？” 这些查询通过 `/api/stories/search` 和 `/api/story/by-title` 端点处理。 ### 🧑‍💻 示例用法 **按标题/关键词搜索故事：** ```bash curl "http://localhost:8000/api/stories/search?query=AI+伦理&limit=3" ``` **按标题获取故事及其评论：** ```bash curl "http://localhost:8000/api/story/by-title?title=OpenAI+GPT-4" ``` **从故事 URL 获取实际内容（作为 Markdown）：** ```bash curl "http://localhost:8000/api/story/12345/content?format=markdown" ``` **按故事标题获取内容：** ```bash curl "http://localhost:8000/api/story/content-by-title?title=量子计算&format=markdown" ``` **健康检查：** ```bash curl "http://localhost:8000/health" ``` **获取热门故事：** ```bash curl "http://localhost:8000/api/stories/top?limit=5" ``` 请参阅 `/docs` 以获取完整的交互式文档，并实时尝试端点。 --- ## 👤 适用人群 - **LLM/AI 代理开发者**：为您的代理添加现实世界的最新新闻和讨论。 - **聊天机器人构建者**：用热门故事和社区洞察力为您的机器人提供支持。 - **研究人员与数据科学家**：分析黑客新闻趋势、用户活动和话题情感。 - **生产力黑客**：构建自定义仪表板、通知机器人或研究工具。 - **任何希望使黑客新闻可编程的人！** > ℹ️ **提示：** 您不需要知道故事 ID — 只需自然地询问即可！ --- ## ⚡ 快速开始 > 🛠️ **几秒钟安装，随处运行！** ### 1. 安装 ```bash # 克隆仓库 git clone https://github.com/yourusername/hacker-news-mcp.git cd hacker-news-mcp # 安装依赖 pip install -r requirements.txt ``` ### 2. 运行服务器 ```bash # 使用 SSE 传输（默认，适用于 web/remote） python run.py --transport sse --host 127.0.0.1 --port 8000 # 使用 STDIO 传输（用于直接 LLM/代理集成） python run.py --transport stdio # 可选：使用自定义日志级别运行 env LOG_LEVEL=debug python run.py --transport sse ``` ### 3. 🚢 Docker 部署 ```bash # 使用 Docker 构建和运行 docker build -t hacker-news-mcp . docker run -p 8000:8000 hacker-news-mcp # 或使用 Docker Compose docker-compose up -d ``` --- ## 🛠️ MCP 配置 > 💡 **提示：** 适用于 Claude Desktop、Windsurf、Cursor IDE 以及任何支持 MCP 的 LLM/代理！ ### 🎛️ Claude Desktop 示例 **STDIO（本地）：** ```json { "mcpServers": { "hackerNews": { "command": "python", "args": ["/path/to/hacker-news-mcp/run.py", "--transport", "stdio"], "env": { "LOG_LEVEL": "info" } } } } ``` ### 🖥️ Windsurf/Cursor IDE 示例 **STDIO（本地）：** ```json { "mcpServers": { "hackerNews": { "command": "python", "args": ["/path/to/hacker-news-mcp/run.py", "--transport", "stdio"], "env": { "LOG_LEVEL": "info" } } } } ``` **SSE（远程）：** ```json { "mcpServers": { "hackerNews": { "url": "https://your-deployed-server.com/sse", "transport": "sse" } } } ``` --- ## 🧰 工具、资源与提示 ### 🛠️ 可用工具 - 🔎 **基本数据检索** - `get_item(id)`：按 ID 获取黑客新闻项目 - `get_user(id)`：按 ID 获取黑客新闻用户 - `get_max_item_id()`：获取当前最大的项目 ID - 🏆 **故事列表** - `get_top_stories(limit)`：获取热门故事 - `get_best_stories(limit)`：获取最佳故事 - `get_new_stories(limit)`：获取最新故事 - `get_ask_stories(limit)`：获取 Ask HN 故事 - `get_show_stories(limit)`：获取 Show HN 故事 - `get_job_stories(limit)`：获取工作故事 - 📝 **内容检索** - `get_story_content(story_id, format)`：从故事的 URL 获取实际内容 - `get_story_content_by_title(title, format)`：按故事标题获取内容 - 格式选项：`"markdown"`（默认）或 `"json"` - 💬 **高级故事检索** - `get_story_with_comments(story_id, comment_limit)`：获取故事及其评论 - `find_stories_by_title(query, limit)`：按标题或关键词查找故事 - `get_story_by_title(title)`：按标题或关键词查找并检索故事及其评论 - 🔄 **其他工具** - `get_updates()`：获取最新的项目和配置文件更改 - `search_by_date(days_ago, limit)`：搜索大约 N 天前的故事 ### 📦 资源 - 🧑‍💻 **项目资源** - `hn://item/{id}`：按 ID 获取项目 - `hn://user/{id}`：按 ID 获取用户 - 📋 **故事列表资源** - `hn://top/{limit}`：获取热门故事 - `hn://best/{limit}`：获取最佳故事 - `hn://new/{limit}`：获取最新故事 - `hn://ask/{limit}`：获取 Ask HN 故事 - `hn://show/{limit}`：获取 Show HN 故事 - `hn://jobs/{limit}`：获取工作故事 ### 🧠 提示模板 > 💡 **自然语言友好：** 用户可以通过标题、关键词或直接提问以自然语言方式引用故事！ - 🧠 **智能路由器** - `hn_router(query)`：分析任何 HN 相关查询，并路由到最佳工具和方法 - 📝 **故事分析** - `hn_story_summary_by_id(story_id)`：按 ID 总结黑客新闻故事 - `hn_story_summary_by_title(title)`：按标题/关键词总结故事 - `hn_story_comment_analysis(title|id)`：分析故事的评论 - 📰 **内容检索与分析** - `hn_story_content_by_id(story_id)`：获取并分析故事的全文内容 - `hn_story_content_by_title(title)`：获取并分析按标题/关键词获取的内容 - `hn_content_filter(story_id, filter_type)`：提取特定类型的内容（技术、代码、意见等） - 🔎 **高级搜索与比较** - `hn_advanced_search(query, days, min_score, min_comments)`：查找匹配特定标准的故事 - `hn_compare_stories(story_ids)`：比较多个故事以识别相似性和差异 - `hn_multi_source_analysis(query, sources_count)`：分析多个来源的同一个话题 - 📈 **趋势分析** - `hn_trending_topics()`：列出当前趋势话题 - `hn_trend_analysis(days, story_type, topic)`：分析趋势随时间的变化，可选聚焦于特定话题 - 👤 **用户分析** - `hn_user_profile_analysis(username)`：分析用户的活动和兴趣 #### 🗣️ 用户请求示例 - “总结那个关于量子计算的 HN 故事” - “今天黑客新闻的热门话题是什么？” - “告诉我关于 HN 用户 ‘dang’ 的信息” - “给我提供对 AI 法规的详细分析” > ⚡ **不需要 ID！** 只需自然地询问即可！ ### 💬 高级提示示例 #### 智能路由器 ``` “你能告诉我黑客新闻上关于量子计算的讨论吗？” ``` 路由器分析您的查询，识别意图，并建议使用可用的工具（例如，搜索量子计算故事、内容分析、比较观点）。#### 多源分析 ``` “比较黑客新闻上的不同观点区块链” “What are the various opinions about the new MacBook Pro？” ``` 检索同一个话题的多个来源，提取它们的内容，并提供对不同观点的全面分析、一致/不一致的领域，并合成见解。 #### 内容过滤 ``` “显示 HN 故事 12345 的技术部分” “提取那篇关于 Rust 的文章中的代码示例” ``` 检索故事的内容，并根据特定需求过滤（技术细节、代码示例、意见、适合初学者解释等）。 #### 高级搜索 ``` “查找关于量子计算的热门故事并有很多讨论” “What are the highest-rated AI stories from the past month？” ``` 执行高级搜索并过滤按评分、评论数量和时间范围，然后分析结果。 #### 趋势分析``` “过去一个月 AI 在 HN 上讨论发生了什么变化？” “What topics are gaining traction compared to last week？” ``` 比较当前故事与历史数据以识别新兴话题、变化的兴趣和社区参与模式。 #### 故事比较``` “比较 HN 故事 12345 和 67890” “What are the differences between those two quantum computing articles？” ``` 比较多个故事以识别相似性、差异和它们之间的关系。 --- ## API 文档 运行 SSE 传输时，OpenAPI 文档位于： - Swagger UI：`http://localhost:8000/docs` - ReDoc：`http://localhost:8000/redoc` - OpenAPI JSON：`http://localhost:8000/openapi.json` ## 配置 ### 环境变量 - `HN_API_KEY`: 黑客新闻的 API 密钥（如果未来需要） - `LOG_LEVEL`: 日志级别（debug, info, warning, error, critical） - `FASTMCP_TOOL_ATTEMPT_PARSE_JSON_ARGS`: 设置为 1 以启用 JSON 参数解析 ## 云部署 ### Google Cloud Run 部署 1. **构建和推送 Docker 镜像` ```bash # 构建 Docker 镜像 docker build -t gcr.io/your-project-id/hacker-news-mcp . # 推送到 Google 容器注册表 docker push gcr.io/your-project-id/hacker-news-mcp` 2. **部署到 Cloud Run` ```bash gcloud run deploy hacker-news-mcp \ --image gcr.io/your-project-id/hacker-news-mcp \ --platform managed \ --region us-central1 --allow-unauthenticated --memory 512Mi --set-env-vars="LOG_LEVEL=info"` ``` 3. **配置 MCP 使用者与 Cloud Run URL` ```json { "name": "黑客新闻", - `url`: "https://hacker-news-mcp-abcdef123-uc.a.run.app/sse", - `transport`: "sse" } ``` ### AWS Lambda 部署 1. **打包应用程序` ```bash # 创建部署包 zip -r deployment.zip . -x "*.git*" -x "*.git*" -x "*.pytest_cache*" -x "__pycache__/*" ``` 2. **创建 Lambda 函数并配置 API Gateway** - 在 AWS 控制台中创建 Lambda 函数 - 上传 `deployment.zip` 包 - 配置 API Gateway 触发器 - 设置环境变量（如果需要） 3. **使用 API Gateway URL 配置 MCP 使用者** 使用 API Gateway URL 在您的 MCP 配置中： ```json { "name": "黑客新闻", "url": "https://abcdef123.execute-api.us-east-1.amazonaws.com/prod/sse", "transport": "sse" } ``` ## 集成示例 ### Python 客户端 ```python import asyncio from fastmcp import Client from fastmcp.client.transports import SSETransport import json async def main(): # 连接到服务器 client = Client(SSETransport("http://localhost:8000/sse")) async with client: # 列出可用工具 tools = await client.list_tools() print(f"可用工具：{len(tools)}") # 获取热门故事 top_stories = await client.call_tool("get_top_stories", {"limit": 5}) story_ids = json.loads(top_stories[0].text) print(f"热门故事：{story_ids}") # 获取特定故事 if story_ids: story_result = await client.call_tool("get_item", {"id": story_ids[0]}) story_data = json.loads(story_result[0].text) print(f"故事：{story_data.get('title')}") if __name__ == "__main__": asyncio.run(main()) ``` ### STDIO 集成 对于支持 STDIO 的 LLM 代理： ```bash # 以 STDIO 模式运行服务器 python run.py --transport stdio ``` ## 测试 ### 运行测试 ```bash # 运行所有测试 python -m pytest tests/ # 运行特定测试文件 python -m pytest tests/test_server.py ``` ### 使用测试客户端进行手动测试 ```bash # 在一个终端启动服务器 python run.py --transport sse # 在另一个终端运行测试客户端 python test_client.py ``` ## 故障排除 ### 常见问题 1. **连接被拒绝** - 确保服务器正在运行且端口正确 - 检查防火墙设置 2. **不支持的传输** - 验证您是否正在使用支持的传输（“stdio”或“sse”） 3. **JSON 解析错误** - 对于较旧的 LLM，设置 `FASTMCP_TOOL_ATTEMPT_PARSE_JSON_ARGS=1` 4. **缺少依赖项** - 运行 `pip install -r requirements.txt` 以确保所有依赖项都已安装 ## 贡献 1. 分叉仓库 2. 创建功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交更改 (`git commit -m 'Add some amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 打开拉取请求 ## 许可 该项目根据 GNU Affero 通用公共许可证 v3.0（AGPLv3）许可 - 有关详细信息，请参阅 LICENSE 文件。 AGPLv3 是 copyleft 许可证，要求任何分发您的代码或派生作品的人必须以相同条款提供源代码，并且还将此要求扩展到通过网络与软件交互的用户。 **商业使用警告** 如果您想使用或部署此代码作为向他人提供的盈利服务的组成部分，即使您不要求支付代码本身的费用，但您正在使用我的代码来促进您的服务 - 您需要联系我以获得许可（这意味着您，Smithery/Glama 或任何类似服务）- 只有在支付适当的许可费后才会授予。否认，您可能不直接收费于使用代码本身，而且您可能正在提供基础设施，但您正在使用我的代码来促进您的服务。那就是内在依赖，必须许可。**开源软件的使用不应该限制软件的民主化，它应该使软件更加开放，只对那些能负担得起的人开放。** 对于其他人，无论您是企业还是个人，我希望它对您有用。享受。 ## 致谢 - [黑客新闻 API](https://github.com/HackerNews/API) - [FastMCP](https://fastmcp.readthedocs.io/) - [FastAPI](https://fastapi.tiangolo.com/)