Readwise MCP Enhanced

🚀 Readwise MCP 增強版

Readwise MCP 增強版是一個全面的模型上下文協議（MCP）服務器，它將 Readwise Reader 的文檔管理與 完整的 Readwise 高亮功能 相統一。該項目可與 Claude Desktop、Continue 以及任何兼容 MCP 的 AI 工具配合使用。它採用 TypeScript 構建，具備先進的文本處理能力、智能內容控制功能以及上下文優化響應機制。

🚀 快速開始

Readwise MCP 增強版是首個統一的 MCP，它整合了以下功能：

• 完整的 Readwise Reader API：可實現文檔的保存、管理和搜索。
• 完整的 Readwise 高亮 API：能訪問所有高亮內容、書籍和每日複習資料。
• 人工智能驅動的文本處理：具備智能分詞和內容提取功能。
• 上下文優化：在保持完整功能的同時，將令牌使用量減少 94%。
• 智能內容控制：通過高級過濾和分頁功能，防止上下文爆炸。

它相當於官方的 Readwise MCP，但效率更高且功能更完整，可與所有 MCP 客戶端兼容。

✨ 主要特性

📚 增強型閱讀器管理

• 智能內容提取：支持分頁、關鍵詞過濾和長度限制。
• 人工智能驅動的文本處理：自動分詞功能可修復合併的單詞。
• 性能控制：針對高成本操作提供內置警告和指導。
• 靈活過濾：可根據位置、類別、標籤、日期和自定義標準進行過濾。

🎯 完整的高亮生態系統

• 每日複習：採用間隔重複學習系統。
• 高級搜索：支持特定字段查詢，並進行相關性評分。
• 書籍管理：提供完整的元數據，包括高亮計數和過濾功能。
• 導出與備份：支持批量高亮分析和增量同步。
• 手動創建：可添加帶有完整元數據的高亮內容。

⚡ 卓越的生產性能

• 上下文優化：將令牌使用量減少 94%（從 25,600 個令牌降至 1,600 個令牌）。
• 雙 API 架構：無縫集成 v2（高亮）和 v3（閱讀器）API。
• 無限制結果：沒有人為限制，每個項目僅提供高效數據。
• 符合 MCP 協議：具備適當的日誌記錄、錯誤處理和速率限制。

📦 安裝指南

選項 1：NPX - 無需安裝！（推薦）

無需安裝！任何 MCP 客戶端都可以使用 npx 自動下載並運行該軟件包。

選項 2：全局 NPM 安裝

npm install -g readwise-mcp-enhanced

選項 3：從源代碼安裝

git clone https://github.com/arnaldo-delisio/readwise-mcp-enhanced.git
cd readwise-mcp-enhanced
npm install
npm run build

💻 使用示例

基礎用法

智能內容提取示例

// 對大型文檔進行分頁處理
readwise_list_documents({
  withFullContent: true,
  contentMaxLength: 5000,
  contentStartOffset: 0,
  contentFilterKeywords: ["machine learning", "AI"]
})

綜合搜索示例

// 在文檔和高亮內容中進行搜索
readwise_search_highlights({
  textQuery: "productivity habits",
  fieldQueries: [
    { field: "document_author", searchTerm: "James Clear" }
  ],
  limit: 10
})

每日學習工作流示例

// 獲取每日複習的間隔重複內容
readwise_get_daily_review()

// 搜索相關高亮內容以進行深入學習
readwise_search_highlights({
  textQuery: "from daily review topics",
  limit: 20
})

高級用法

高級使用場景可參考文檔中各個工具的詳細配置和使用說明，根據具體需求靈活調整參數，以實現更強大的功能，如在搜索時結合更多的字段查詢條件、在保存文檔時設置更詳細的元數據等。

📚 詳細文檔

📖 可用工具（共 13 個）

📚 閱讀器工具（6 個） - 增強版

• readwise_save_document：可保存帶有完整元數據控制的文檔。

{
  "url": "https://example.com/article",
  "tags": ["ai", "productivity"],
  "location": "later",
  "category": "article"
}

• readwise_list_documents：⭐ 具備智能內容控制的增強版

{
  "withFullContent": true,
  "contentMaxLength": 10000,
  "contentStartOffset": 0,
  "contentFilterKeywords": ["AI", "machine learning"],
  "limit": 10
}

智能內容參數： - contentMaxLength：限制每個文檔的內容長度（默認值：50,000 個字符）。 - contentStartOffset：從特定位置開始提取內容（用於分頁）。 - contentFilterKeywords：僅提取包含關鍵詞的部分。 - 針對高成本操作提供性能警告。

• readwise_update_document：可更新文檔的元數據（標題、作者、摘要、位置等）。
• readwise_delete_document：可從閱讀器庫中刪除文檔。
• readwise_list_tags：可獲取所有文檔標籤。
• readwise_topic_search：⭐ 具備人工智能驅動的文本處理功能的增強版
  • 基於正則表達式在標題、摘要、筆記、標籤中進行搜索。
  • 自動分詞以實現更好的匹配效果。
  • 在內容中分佈式查找關鍵詞。

🎯 高亮工具（7 個） - 新增

• readwise_list_highlights：可列出帶有高級過濾功能的高亮內容。

{
  "book_id": 12345,
  "highlighted_at__gt": "2024-01-01T00:00:00Z",
  "page_size": 100
}

• readwise_get_daily_review：可獲取間隔重複的高亮內容。

{
  "review_id": 168844911,
  "highlights": [
    {
      "text": "Strategic wisdom quote...",
      "title": "The Art of War",
      "author": "Sun Tzu"
    }
  ]
}

• readwise_search_highlights：⭐ 支持特定字段查詢的高級搜索

{
  "textQuery": "strategy tactics",
  "fieldQueries": [
    {
      "field": "document_title",
      "searchTerm": "Art of War"
    }
  ],
  "limit": 20
}

• readwise_list_books：可獲取帶有高亮元數據的書籍。

{
  "category": "books", 
  "last_highlight_at__gt": "2024-01-01T00:00:00Z"
}

• readwise_get_book_highlights：可獲取特定書籍的所有高亮內容。

{
  "bookId": 53827741
}

• readwise_export_highlights：可進行批量導出以進行分析和備份。

{
  "updatedAfter": "2024-01-01T00:00:00Z",
  "includeDeleted": false
}

• readwise_create_highlight：可手動添加帶有元數據的高亮內容。

{
  "highlights": [
    {
      "text": "Important insight...",
      "title": "Book Title",
      "author": "Author Name",
      "note": "My thoughts on this",
      "category": "books"
    }
  ]
}

🎯 上下文優化

在保持完整功能的同時，實現了 94% 的令牌減少：

優化字段：

• 高亮內容：僅保留 id、text、note、book_id。
• 書籍：僅保留 id、title、author、category、num_highlights。
• 搜索：僅保留 text、book、author、score。

🧠 人工智能驅動的特性

• 智能分詞：自動修復常見的文本提取問題，例如：
  • whatyou → what you
  • fromdissatisfaction → from dissatisfaction
  • timeago → time ago
• 智能內容處理：
  • 對 YouTube 轉錄內容進行基於句子的分塊處理。
  • 在內容中進行分佈式關鍵詞過濾。
  • 進行上下文感知的文本提取，並保證適當的間距。
• 高級搜索算法：
  • 支持多字段搜索，並進行相關性評分。
  • 基於導出的全面搜索，效果等同於官方 MCP。
  • 支持特定字段過濾（標題、作者、文本、筆記、標籤）。

📊 技術架構

雙 API 客戶端系統

// 無縫切換 API
v2 API: 高亮內容、書籍、每日複習、導出
v3 API: 閱讀器文檔、標籤、搜索

上下文高效設計

• 無限制結果：每個項目僅提供最少的數據。
• 針對大語言模型優化的響應：便於高效解析。
• 結構化 JSON：保留完整的推理能力。

可用於生產環境

• 遵循 ES 模塊標準，具備適當的 TypeScript 定義。
• 符合 MCP 協議的日誌記錄和錯誤處理。
• 全面的速率限制和優雅的降級機制。

⚙️ API 覆蓋範圍

Readwise 閱讀器 API（v3）

• ✅ 文檔：保存、列出、更新、刪除
• ✅ 標籤：列出和過濾
• ✅ 內容：具備控制功能的智能提取
• ✅ 搜索：增強型主題搜索

Readwise 高亮 API（v2）

• ✅ 高亮內容：列出、創建、搜索、導出
• ✅ 書籍：列出帶有元數據和過濾功能
• ✅ 每日複習：間隔重複系統
• ✅ 高級搜索：特定字段查詢

🔐 認證與安全

• 單令牌認證：使用一個 Readwise 令牌即可訪問兩個 API。
• 環境變量存儲：通過 READWISE_TOKEN 安全存儲令牌。
• 令牌不暴露：不會通過 MCP 客戶端或工具界面暴露令牌。

📈 速率限制

• 閱讀器 API：默認每分鐘 20 個請求，創建/更新操作每分鐘 50 個請求。
• 高亮 API：遵循標準的 Readwise 速率限制，並自動處理重試。
• 智能處理：429 響應包含 "Retry-After" 頭信息。

🔧 技術細節

雙 API 客戶端系統

該系統實現了 API 的無縫切換，v2 API 負責處理高亮內容、書籍、每日複習和導出功能；v3 API 則用於處理閱讀器文檔、標籤和搜索功能。這種設計使得不同類型的操作能夠分別使用最合適的 API，提高了系統的效率和穩定性。

上下文高效設計

• 無限制結果：系統不會對結果進行人為限制，每個項目僅提供必要的最少數據，確保在處理大量數據時也能保持高效。
• LLM 優化響應：響應格式經過優化，便於大語言模型進行高效解析，減少解析時間和資源消耗。
• 結構化 JSON：使用結構化的 JSON 數據格式，保留了完整的推理能力，方便後續的數據分析和處理。

生產就緒特性

• ES 模塊標準：採用 ES 模塊標準，並提供了適當的 TypeScript 定義，確保代碼的規範性和可維護性。
• MCP 協議合規：具備符合 MCP 協議的日誌記錄和錯誤處理機制，能夠及時發現和處理系統運行過程中的問題。
• 全面速率限制：設置了全面的速率限制，並具備優雅的降級機制，防止系統因過度請求而崩潰。

📄 許可證

本項目採用 MIT 許可證。

🙏 致謝

本項目基於 edricgan/Readwise-Reader-MCP 構建，並進行了顯著增強：

• 增強的閱讀器功能：具備智能內容控制。
• 完整的高亮集成：等同於官方 MCP。
• 人工智能驅動的文本處理：支持分詞功能。
• 上下文優化：提高生產效率。
• 統一架構：無縫整合雙 API。

這代表了從基本文檔管理到全面、可用於生產環境的 Readwise 平臺的完整演進。 🚀