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