AI导哈

Hacker News 数据服务

提供实时Hacker News数据和讨论的可编程接口，适用于LLM、AI代理和应用工作流。

  • by rawveg
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 rawveg/hacker-news-mcp

使用说明

🚀 黑客新闻MCP服务器

将实时黑客新闻数据和讨论带入LLM、代理或应用程序工作流的最简单方法。

立即将Hacker News变成您的AI代理和应用程序的可编程、对话式知识库！

✨ 为什么使用这个？

  • 即插即用：立即将LLM、代理或聊天机器人连接到实时黑客新闻数据和讨论。
  • 灵活的：用作本地工具、云API或容器化微服务。
  • 自然语言友好用户可以通过标题、关键字或自然语言（“人们对量子计算有什么看法？”）来引用故事。
  • 丰富提示：内置提示模板，用于摘要、趋势主题、用户分析等。
  • 生产就绪：强大的错误处理、健康检查和开箱即用的云部署支持。

🌟 特性

  • ⚡ 多种运输方式：STDIO/MCP和SSE/MCP用于灵活的LLM/代理集成
  • 🌐 REST/OpenAPI端点：使用自动生成的文档进行直接HTTP访问
  • 📰 完整的黑客新闻报道：访问故事、评论、用户、热门话题等
  • 🛡️ 稳健的错误处理：清晰的响应模型和状态代码
  • 🧩 易于配置：API键、主机和日志记录的环境变量
  • 🐳 集装箱准备就绪：Docker和Docker Compose用于无痛部署
  • ❤️ 健康监测：内置健康检查端点
  • 🔒 CORS支持：用于web集成的安全和可配置的来源

📚 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 --获取询问HN故事
  • GET /api/stories/show?limit=30 --获取显示HN故事
  • GET /api/stories/search?query=YOUR_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=YOUR_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=YOUR_TITLE&format=markdown --按故事标题获取内容
    • format 参数接受 markdown （默认）或 json

用户

  • GET /api/user/{username} --通过用户名获取Hacker News用户

系统和更新

  • GET /api/maxitem --获取当前最大的商品ID
  • GET /api/updates --获取最新项目和配置文件更改
  • GET /health --健康检查端点
  • GET /sse-info --关于SSE端点的信息

SSE 和 MCP

  • GET /sse --MCP协议的服务器发送事件（SSE）端点

OpenAPI和文档

  • GET /docs -Swagger UI（交互式API文档）
  • GET /openapi.json --OpenAPI模式（用于工具集成）

🗣️ 基于自然语言和标题的查询

您可以使用自然语言或关键字搜索和检索故事，而不仅仅是数字ID！

  • 例子：

    • GET /api/stories/search?query=quantum computing --查找有关量子计算的故事
    • GET /api/story/by-title?title=React framework --获取有关React框架的最新故事和评论

  • 自然语言友好：

    • “告诉我昨天关于量子计算的故事”
    • “关于新的React框架的讨论是什么样的？”

这些查询通过以下方式处理 /api/stories/search 和 /api/story/by-title 端点。

🧑‍💻 示例用法

按标题/关键字搜索故事：

curl "http://localhost:8000/api/stories/search?query=AI+ethics&limit=3"

按标题获取故事及其评论：

curl "http://localhost:8000/api/story/by-title?title=OpenAI+GPT-4"

从故事URL（Markdown）获取实际内容：

curl "http://localhost:8000/api/story/12345/content?format=markdown"

按故事标题获取内容：

curl "http://localhost:8000/api/story/content-by-title?title=quantum+computing&format=markdown"

健康检查：

curl "http://localhost:8000/health"

获取头条新闻：

curl "http://localhost:8000/api/stories/top?limit=5"

看 /docs 获取完整的交互式文档，并尝试端点直播。

👤 这是给谁的？

  • LLM/AI代理开发人员：为您的代理添加真实世界的最新新闻和讨论。
  • 聊天机器人建设者：用趋势故事和社区见解为您的机器人提供动力。
  • 研究人员和数据科学家：分析黑客新闻趋势、用户活动和话题情绪。
  • 生产力黑客：构建自定义仪表板、通知机器人或研究工具。
  • 任何想让黑客新闻可编程的人！

ℹ️ 提示： 你不需要知道故事ID——只需按标题、主题或关键字询问故事即可！

⚡ 快速开始

🛠️ 几秒钟内安装，随时随地运行！

1.安装

# Clone the repository
git clone https://github.com/yourusername/hacker-news-mcp.git
cd hacker-news-mcp

# Install dependencies
pip install -r requirements.txt

2.运行服务器

# Run with SSE transport (default, good for web/remote)
python run.py --transport sse --host 127.0.0.1 --port 8000

# Run with STDIO transport (for direct LLM/agent integration)
python run.py --transport stdio

# Optional: Run with custom log level
env LOG_LEVEL=debug python run.py --transport sse

3.🚢 Docker部署

# Build and run with Docker
docker build -t hacker-news-mcp .
docker run -p 8000:8000 hacker-news-mcp

# Or use Docker Compose
docker-compose up -d

🛠️ MCP配置

💡 提示： 适用于Claude Desktop、Windsurf、Cursor IDE以及任何支持MCP的LLM/代理！

🎛️ Claude桌面示例

STDIO（本地）：

{
  "mcpServers": {
    "hackerNews": {
      "command": "python",
      "args": ["/path/to/hacker-news-mcp/run.py", "--transport", "stdio"],
      "env": { "LOG_LEVEL": "info" }
    }
  }
}

🖥️ Windsurf/Cursor IDE示例

STDIO（本地）：

{
  "mcpServers": {
    "hackerNews": {
      "command": "python",
      "args": ["/path/to/hacker-news-mcp/run.py", "--transport", "stdio"],
      "env": { "LOG_LEVEL": "info" }
    }
  }
}

SSE（远程）：

{
  "mcpServers": {
    "hackerNews": {
      "url": "https://your-deployed-server.com/sse",
      "transport": "sse"
    }
  }
}

🧰 工具、资源和提示

🛠️ 可用工具

  • 🔎 基础数据检索
    • get_item(id)：通过ID获取黑客新闻
    • get_user(id)：通过ID获取Hacker News用户
    • get_max_item_id()：获取当前最大的项目ID
  • 🏆 故事列表
    • get_top_stories(limit)：获取头条新闻
    • get_best_stories(limit)：获取最佳故事
    • get_new_stories(limit)：获取最新故事
    • get_ask_stories(limit)：获取提问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}：获取提问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)：从故事的URL获取并分析整篇文章内容
    • 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'的情况”
  • “请详细分析一下关于人工智能监管的讨论”

⚡ 不需要身份证！ 自然地问——这个服务器会将您的请求与正确的提示和工具相匹配。

💬 高级提示示例

智能路由器

"What can you tell me about quantum computing discussions on Hacker News?"

路由器分析您的查询，识别意图，并使用可用工具（例如，搜索量子计算故事、分析内容、比较观点）推荐最佳方法。

多源分析

"Compare different perspectives on blockchain from Hacker News"
"What are the various opinions about the new MacBook Pro?"

检索同一主题的多个来源，提取其内容，对不同观点、共识/分歧领域进行全面分析，并综合见解。

内容过滤

"Show me just the technical parts of HN story 12345"
"Extract the code examples from that article about Rust"

检索故事的内容，并根据特定需求（技术细节、代码示例、意见、适合初学者的解释等）对其进行过滤。

高级搜索

"Find popular stories about quantum computing with lots of discussion"
"What are the highest-rated AI stories from the past month?"

执行高级搜索，按分数、评论数和时间范围进行过滤，然后分析结果。

趋势分析

"How has discussion about AI changed on HN over the last month?"
"What topics are gaining traction compared to last week?"

将当前故事与历史数据进行比较，以确定新兴主题、不断变化的兴趣和社区参与模式。

故事比较

"Compare HN stories 12345 and 67890"
"What's the difference between those two quantum computing articles?"

比较多个故事，以确定它们之间的相似性、差异性和关系。

API文档

当使用SSE传输运行时，OpenAPI文档可在以下网址获得：

  • Swagger用户界面： http://localhost:8000/docs
  • 重新记录： http://localhost:8000/redoc
  • OpenAPI JSON： http://localhost:8000/openapi.json

配置

环境变量

  • HN_API_KEY：Hacker News的API密钥（如果将来需要）
  • LOG_LEVEL：日志记录级别（调试、信息、警告、错误、严重）
  • FASTMCP_TOOL_ATTEMPT_PARSE_JSON_ARGS：设置为1以启用工具参数的JSON解析

云部署

谷歌云运行部署

  1. 构建和推送Docker镜像
# Build the Docker image
docker build -t gcr.io/your-project-id/hacker-news-mcp .

# Push to Google Container Registry
docker push gcr.io/your-project-id/hacker-news-mcp
  1. 部署到云端运行
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"
  1. 使用云运行URL配置MCP消费者

部署后，Cloud Run将提供以下URL https://hacker-news-mcp-abcdef123-uc.a.run.app.在MCP配置中使用此URL：

{
  "name": "Hacker News",
  "url": "https://hacker-news-mcp-abcdef123-uc.a.run.app/sse",
  "transport": "sse"
}

AWS Lambda部署

  1. 打包应用程序
# Create a deployment package
zip -r deployment.zip . -x "*.git*" -x "*.pytest_cache*" -x "__pycache__/*"
  1. 使用API网关创建Lambda函数
  • 在AWS控制台中创建Lambda函数
  • 上传deployment.zip包
  • 配置API网关触发器
  • 根据需要设置环境变量
  1. 使用API网关URL配置MCP使用者

在MCP配置中使用API网关URL：

{
  "name": "Hacker News",
  "url": "https://abcdef123.execute-api.us-east-1.amazonaws.com/prod/sse",
  "transport": "sse"
}

集成示例

Python客户端

import asyncio
from fastmcp import Client
from fastmcp.client.transports import SSETransport
import json

async def main():
    # Connect to the server
    client = Client(SSETransport("http://localhost:8000/sse"))
    
    async with client:
        # List available tools
        tools = await client.list_tools()
        print(f"Available tools: {len(tools)}")
        
        # Get top stories
        top_stories = await client.call_tool("get_top_stories", {"limit": 5})
        story_ids = json.loads(top_stories[0].text)
        print(f"Top stories: {story_ids}")
        
        # Get a specific story
        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: {story_data.get('title')}")

if __name__ == "__main__":
    asyncio.run(main())

STDIO集成

对于支持基于STDIO的MCP服务器的LLM代理：

# Run the server in STDIO mode
python run.py --transport stdio

测试

运行测试

# Run all tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_server.py

使用测试客户端进行手动测试

# Start the server in one terminal
python run.py --transport sse

# Run the test client in another terminal
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）获得许可-有关详细信息，请参阅许可证文件。

AGPLv3是一种copyleft许可证，要求任何分发您的代码或衍生作品的人在相同的条款下提供源代码，并将这一要求扩展到通过网络与软件交互的用户。

商业用途警告

如果你想以任何形式使用或部署此代码，作为向他人提供货币化服务的一部分，即使你没有特别要求支付代码费用，你也需要联系我获得许可（这意味着 你 Smithery/Glama或任何类似服务）-只有在支付适当的许可费后才能授予。不，你可能不会对代码本身的使用收费，你可能会提供基础设施，但你会使用 我的 代码以方便 你的 服务。这是一种内在的依赖性 必须 获得许可。 付费墙 开源软件的使用并不是使软件民主化，而是只为那些有能力支付的人开放，这与开源许可的精神背道而驰。

对于其他人，无论你是企业还是个人，我希望这对你有用。享受。

致谢

相关 MCP