Readwise MCP 服务器

用于访问和与您的 Readwise 库交互的模型上下文协议 (MCP) 服务器。

特征

• 访问 Readwise 图书馆中的精彩内容

• 使用自然语言查询搜索亮点

• 从图书馆获取书籍和文件

• 与 Claude 和其他 MCP 兼容助手无缝集成

• 增强的亮点分析提示功能

• 传输感知日志系统

• 强大的错误处理和验证

• MCP 协议符合正确的 request_id 处理

• 用于监控的健康检查端点

• 改进了设置向导，带有 API 密钥验证

项目结构

该存储库分为以下主要目录：

• src/ ：Readwise MCP 服务器的主要源代码

• test-scripts/ ：用于验证 MCP 服务器功能的测试脚本和实用程序

  • smart-mcp-test.sh ：stdio 和 SSE 传输的主要测试脚本

  • run-simple-server.sh ：运行简单 MCP 服务器的脚本

  • 请参阅test-scripts/README.md获取完整文档

• examples/ ：示例实现和代码示例

  • examples/mcp-implementations/ ：基本 MCP 服务器实现

  • examples/test-clients/ ：客户端测试脚本

  • 请参阅examples/README.md以获取完整文档

• dist/ ：编译后的 JavaScript 输出（生成）

• scripts/ ：用于开发和测试的实用脚本

安装

设置

在使用服务器之前，您需要配置您的 Readwise API 密钥：

您可以从https://readwise.io/access_token获取 API 密钥。

用法

命令行界面

API

使用 MCP Inspector 进行测试

该项目内置了使用 MCP 检查器进行测试的支持。您可以使用 TypeScript 脚本或 Shell 脚本来运行检查器。

自动化测试

运行验证所有工具和提示的自动测试套件：

测试套件验证：

• 服务器启动和连接

• 工具可用性和响应

• 提示功能

• 错误处理

• 响应格式合规性

每个测试都提供详细的输出和通过/失败案例的摘要。

手动测试

使用 Shell 脚本

使用 TypeScript 脚本

可用选项

• -t, --transport <type> ：传输类型（stdio 或 sse），默认值：stdio

• -p, --port <number> ：SSE 传输的端口号，默认值：3001

• -d, --debug ：启用调试模式

检查器命令示例

测试特定工具：

测试提示：

列出可用的工具和提示：

无需 Readwise API 密钥即可进行测试

如果您没有 Readwise API 密钥或不想使用真实的 API 密钥进行测试，则可以使用模拟测试功能：

这将运行一个测试脚本：

1. 创建 Readwise API 的模拟实现

2. 使用此模拟 API 设置 MCP 服务器

3. 使用样本数据测试各种端点

4. 无需真实 API 密钥即可验证服务器功能

模拟实现包括：

• 样本书籍、精选内容和文档

• 模拟网络延迟以进行实际测试

• 错误处理测试

可用工具

• get_highlights ：从您的 Readwise 图书馆获取亮点

• get_books ：从您的 Readwise 图书馆获取书籍

• get_documents ：从 Readwise 库中获取文档

• search_highlights ：在 Readwise 图书馆中搜索亮点

可用提示

• readwise_highlight ：Readwise 的流程亮点

  • 支持总结、分析、寻找联系和生成问题

  • 包括强大的错误处理和参数验证

  • 以读者友好的方式格式化突出显示

• readwise_search ：搜索并处理 Readwise 中的亮点

  • 提供带有源信息的格式化搜索结果

  • 使用用户友好的消息优雅地处理 API 错误

  • 包括对必需参数的验证

最近的改进

增强的 MCP 协议合规性

• 正确处理所有响应中的 request_id

• 根据 MCP 协议规范验证传入请求

• 遵循 MCP 指南的一致错误响应格式

改进的设置体验

• 带有 API 密钥验证的交互式安装向导

• 安全存储配置

• 用于故障排除的详细错误消息

强大的错误处理

• 针对不同 API 错误条件的特定错误消息

• 所有工具和提示的错误格式一致

• 传输感知日志记录不会干扰协议

发展

执照

麻省理工学院