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 平台的完整演进。 🚀