Ptt MCP Server

PTT Board MCP Server

這是一個 MCP (Model Context Protocol) 伺服器，專門用於擷取多個 PTT 看板的文章和推文資料，並提供摘要功能。支援包括 Stock、Baseball、Gossiping、HatePolitics、Tech_Job、Movie、NBA 等熱門看板。

🚀 快速開始

在 Claude Desktop 中使用

1. 編輯 Claude Desktop 的配置文件：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

1. 添加 MCP 伺服器配置：

{
  "mcpServers": {
    "ptt-board": {
      "command": "node",
      "args": ["/path/to/your/ptt-mcp-server/index.js"]
    }
  }
}

1. 重啟 Claude Desktop

快速指令範例

• "幫我列出 PTT Baseball 版最新 20 篇文章"
• "分析 NBA 版最近的熱門討論"
• "找出 Stock 版推文數超過 30 的熱門文章"
• "在 Stock 版搜尋包含 '台積電' 的所有文章"

功能特色

• 列出多個 PTT 看板的文章列表
• 支援 19 個熱門看板 (Stock, Baseball, NBA, Tech_Job 等)
• 取得文章詳細內容包含所有推文
• 智能摘要文章內容和推文觀點
• 支援推文情緒分析和熱門度計算
• 動態看板名稱驗證和錯誤處理 (即時檢查看板是否存在)
• 推文數過濾 (支援最小值、最大值、範圍過濾)
• 搜尋功能 (同標題文章、關鍵字搜尋、標題搜尋、作者搜尋)
• 標題關鍵字過濾
• 日期過濾 (預設僅今日文章，支援日期範圍查詢)

安裝步驟

1. 克隆或下載專案檔案
2. 安裝依賴套件：

npm install

1. 編譯 TypeScript（如果需要）：

npm run build

1. 啟動伺服器：

npm start

可用工具

1. list_posts

列出指定 PTT 看板的文章列表

參數：

• board (必需): 看板名稱，例如 "Stock", "Baseball", "NBA"
• limit (可選): 限制返回文章數量，預設 50，最大 200
• minPushCount (可選): 最小推文數過濾，例如 10 表示只返回推文數 >= 10 的文章
• maxPushCount (可選): 最大推文數過濾，例如 50 表示只返回推文數 = 20)：

{
  "board": "Stock",
  "limit": 20,
  "minPushCount": 20
}

冷門文章過濾 (推文數 提示: 您可以嘗試任何 PTT 看板名稱，系統會自動驗證並告知是否存在。

更多使用範例

進階指令範例

• "列出所有支援的 PTT 看板"
• "摘要 Tech_Job 版關於台積電的最新文章"
• "列出 Gossiping 版最新 50 篇文章"
• "列出 Baseball 版推文數在 10-50 之間的文章"
• "找 NBA 版推文數較少的冷門討論 (推文數 = 18.0.0
• 架構: 模組化 ES6+ 設計，配備完整測試套件
• 主要依賴:

- @modelcontextprotocol/sdk: MCP 核心 SDK - cheerio: HTML 解析 - node-fetch: HTTP 請求

• 開發工具:

- Jest: 測試框架 (51 個測試) - TypeScript 配置檔案支援

注意事項

1. 爬蟲禮貌: 伺服器已內建適當的延遲和請求限制，請勿過度頻繁使用
2. PTT 政策: 遵守 PTT 的使用條款和 robots.txt 規範
3. 資料準確性: 爬取的資料可能因 PTT 版面變更而需要調整
4. 年齡限制: 自動處理 PTT 的年齡確認機制 (over18=1)
5. 看板驗證: 動態檢查看板是否存在，支援所有公開的 PTT 看板，結果會被緩存以提升效能

故障排除

常見錯誤

1. 無法取得頁面: 檢查網路連線和 PTT 是否正常運作
2. 無效的看板名稱: 使用 list_popular_boards 查看支援的看板
3. 解析失敗: PTT 版面可能有變更，需要更新選擇器
4. 編碼問題: 確保系統支援 UTF-8 編碼

除錯模式

npm run dev

開發

測試

npm test  # 執行 51 個測試案例

模組化架構

src/
├── utils/           # 工具函數 (DateUtils, PTTUtils)
├── parsers/         # 網頁爬取邏輯 (PTTScraper)
├── tools/           # MCP 工具實作
└── ptt-mcp-server.js # 主服務器協調

修改爬蟲邏輯

• 工具邏輯: 在 src/tools/ 各個工具檔案中
• 爬取邏輯: 在 src/parsers/ptt-scraper.js 中
• 工具函數: 在 src/utils/ 中

新增看板

系統自動支援所有公開 PTT 看板，無需手動添加。

新增功能

1. 在 src/tools/ 建立新工具類別
2. 在 src/ptt-mcp-server.js 註冊新工具
3. 撰寫相對應的測試檔案

更新日誌

v3.0.0 (2025-05-30)

• 🏗️ 重大重構: 模組化架構設計
• ✅ 完整測試: 51 個測試案例，確保程式碼品質
• 📦 分離關注點: 工具、解析器、工具函數獨立模組
• 🧪 測試驅動: Jest 測試框架，涵蓋所有功能
• 🎯 易於維護: 每個功能獨立檔案，便於開發和除錯
• 🔄 API 優化: get_recent_posts 重命名為 list_posts，更加直觀
• 📚 向下相容: 保持所有現有功能和行為

v2.4.0 (2025-05-28)

• 🌐 動態看板驗證系統 - 支援所有公開 PTT 看板
• ⚡ 智能緩存機制 (有效看板緩存 1 小時，無效看板 10 分鐘)
• 🛡️ 網路錯誤時自動降級到預設看板清單
• 🔄 即時檢查看板是否存在，不再限制於預定義清單

v2.3.0 (2025-05-28)

• 🔍 新增搜尋功能 (search_thread_posts, search_posts)
• 🔎 支援同標題文章搜尋 (搜尋同標題文章)
• 🎯 支援多種搜尋類型 (關鍵字、標題、作者)
• 🏷️ 新增標題關鍵字過濾到 get_recent_posts
• 🔗 完整的 PTT 搜尋 URL 編碼支援
• 📄 支援搜尋結果分頁處理

v2.2.0 (2025-05-28)

• 🔍 新增推文數過濾功能 (minPushCount, maxPushCount)
• 🔥 支援熱門文章過濾 (高推文數)
• ❄️ 支援冷門文章過濾 (低推文數)
• 📊 支援範圍過濾 (推文數區間)
• ✅ 完整的參數驗證和錯誤處理
• 📝 更新文檔和使用範例

v2.1.0 (2025-05-28)

• 🔥 重構為 get_recent_posts - 移除不可靠的 24 小時過濾
• ⚡ 改為簡單可靠的"最新 X 篇文章"模式
• 🛡️ 新增文章數量限制驗證 (最大 200 篇)
• 🚫 過濾已刪除文章
• 📈 動態調整翻頁數量以提升效率

v2.0.0 (2025-05-28)

• 🚀 支援多個 PTT 看板 (19 個熱門看板)
• 🔧 重構 get_stock_posts_24h 為 get_board_posts_24h
• ✅ 新增 list_popular_boards 工具
• 🛡️ 新增看板名稱驗證
• 🐛 修復日期解析邏輯 (24 小時窗口問題)
• 📝 更新完整文檔

v1.0.0

• 初始版本，僅支援 Stock 版

授權

MIT License

貢獻

歡迎提交 Pull Request 或開 Issue 來改善這個專案！

免責聲明

本工具僅供學習和研究目的使用。使用者需自行承擔使用本工具的風險，並遵守相關法律法規和網站使用條款。