Hackernews MCP

🚀 📰 Hacker News MCP Server

这是一个模型上下文协议（MCP）服务器，它提供了一系列工具，用于获取和与Hacker News的内容进行交互。借助这个服务器，AI助手能够访问Hacker News的实时数据，包括热门故事、故事详情、评论以及搜索功能。

🚀 快速开始

本服务器可以让AI助手轻松获取Hacker News的各类信息，你可以按照以下步骤进行操作。

✨ 主要特性

🛠️ 可用工具

• get_top_stories - 获取Hacker News的最新热门故事

  • 可配置获取故事的数量（1 - 100个故事）
  • 可选择是否包含故事的文本内容
  • 返回故事的元数据，包括标题、URL、得分、作者和评论数量

• get_story_details - 获取特定故事的详细信息

  • 获取完整的故事元数据
  • 可选择包含具有线程结构的评论
  • 可选择从链接文章中提取Markdown内容

• get_story_comments - 获取故事的热门评论

  • 可配置最低得分过滤
  • 可调整评论线程深度（1 - 10级）
  • 限制返回的评论数量（1 - 100条）
  • 以具有线程结构的可读文本形式呈现

• search_stories - 按关键词搜索近期故事

  • 在故事标题、内容和URL中进行搜索
  • 可配置时间范围（1 - 168小时）
  • 限制搜索结果数量（1 - 50个故事）

📦 安装指南

1. 克隆仓库

git clone https://github.com/yourusername/hackernews-mcp.git
cd hackernews-mcp

2. 安装依赖

npm install

3. 构建服务器

npm run build

💻 使用示例

与Claude Desktop配合使用

将服务器添加到Claude Desktop的配置文件中： macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hackernews-mcp": {
      "command": "node",
      "args": ["/path/to/hackernews-mcp/build/index.js"]
    }
  }
}

与其他MCP客户端配合使用

服务器通过标准输入输出进行通信，可以与任何兼容MCP的客户端一起使用：

node build/index.js

示例用法

连接成功后，你可以向AI助手提出以下问题：

• "今天Hacker News上的热门故事有哪些？"
• "获取Hacker News故事12345678的详细信息"
• "给我看看那个热门AI故事的评论"
• "搜索近期关于TypeScript的故事"

📚 详细文档

开发

构建项目

npm run build

开发模式下的监听模式

npm run watch

代码检查和格式化

npm run lint
npm run format

运行MCP检查器

用于调试和测试：

npm run inspector

这将启动MCP检查器，提供一个Web界面来测试服务器的工具并检查通信情况。

代码质量与贡献

• 代码质量：本项目使用ESLint和Prettier来强制执行代码质量和风格。所有代码都在CI（GitHub Actions）中进行检查，必须通过代码检查和格式化才能合并。
• 类型安全：所有工具处理程序都使用显式类型保护进行运行时参数验证，并使用强大的TypeScript类型。
• CI/CD：每次推送和拉取请求都会通过GitHub Actions运行完整的构建、检查和（未来）测试套件。
• 贡献方式：
  1. 分叉仓库
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add amazing feature')
  4. 在推送之前运行 npm run lint 和 npm run format
  5. 推送到分支 (git push origin feature/amazing-feature)
  6. 打开拉取请求

API文档

get_top_stories

{
  count?: number;        // 故事数量 (1-100, 默认: 30)
  include_text?: boolean; // 是否包含故事文本内容 (默认: false)
}

get_story_details

{
  story_id: number;           // 必需: HN故事ID
  include_comments?: boolean; // 是否包含评论 (默认: false)
  include_markdown?: boolean; // 是否提取文章为Markdown格式 (默认: false)
}

get_story_comments

{
  story_id: number;    // 必需: HN故事ID
  min_score?: number;  // 最低评论得分 (默认: 1)
  max_depth?: number;  // 最大评论线程深度 (1-10, 默认: 3)
  limit?: number;      // 最大返回评论数量 (1-100, 默认: 20)
}

search_stories

{
  query: string;              // 必需: 搜索关键词
  limit?: number;             // 最大搜索结果数量 (1-50, 默认: 20)
  time_range_hours?: number;  // 搜索时间范围 (1-168小时, 默认: 24)
}

架构

服务器使用以下技术构建：

• TypeScript 确保类型安全，提升开发体验
• @modelcontextprotocol/sdk 实现MCP协议
• axios 用于向Hacker News API发送HTTP请求
• jsdom 和 turndown 用于将HTML转换为Markdown
• private-ip 保障安全（阻止对私有IP的访问）

关键组件

• src/index.ts - 包含工具处理程序的主服务器实现
• src/fetcher.ts - 用于获取和转换网页内容的实用类
• build/ - 编译后的JavaScript输出（自动生成）

安全

• 阻止对私有IP地址的请求，防止本地网络访问
• 通过Hacker News API的自然限制进行速率限制
• 对所有工具参数进行输入验证
• 进行错误处理和优雅降级

🔧 技术细节

服务器的核心是基于TypeScript构建，利用了@modelcontextprotocol/sdk来实现MCP协议，确保与各类兼容客户端的通信。通过axios库向Hacker News API发送HTTP请求，获取所需的数据。同时，使用jsdom和turndown将HTML内容转换为Markdown格式，方便处理和展示。在安全方面，使用private-ip库阻止对私有IP地址的请求，避免本地网络被非法访问。对于工具参数，进行了严格的输入验证，确保服务器的稳定性和安全性。

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

🙏 致谢

• Hacker News 提供了出色的API
• Model Context Protocol 提供了标准规范
• 开源社区提供了优秀的工具和库

📞 支持

如果遇到任何问题或有疑问：

1. 查看 Issues 页面
2. 使用MCP检查器进行调试：npm run inspector
3. 创建一个包含详细问题信息的新问题

Made with ❤️ for the MCP community