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/: 用于开发和测试的实用程序脚本

安装

# 从 npm 安装
npm install -g readwise-mcp

# 或克隆存储库并安装依赖项
git clone https://github.com/your-username/readwise-mcp.git
cd readwise-mcp
npm install
npm run build

设置

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

# 运行设置向导
npm run setup

# 或直接使用 API 密钥启动
readwise-mcp --api-key YOUR_API_KEY

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

用法

CLI

# 使用 stdio 传输启动（默认，用于 Claude Desktop）
readwise-mcp

# 使用 SSE 传输启动（用于基于 Web 的集成）
readwise-mcp --transport sse --port 3000

# 启用调试日志记录
readwise-mcp --debug

API

import { ReadwiseMCPServer } from 'readwise-mcp';

const server = new ReadwiseMCPServer(
  'YOUR_API_KEY',
  3000, // 端口
  logger,
  'sse' // 传输
);

await server.start();

使用 MCP Inspector 进行测试

该项目包括对使用 MCP Inspector 进行测试的内置支持。 你可以使用 TypeScript 脚本或 shell 脚本来运行 inspector。

自动化测试

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

# 运行自动化 inspector 测试
npm run test-inspector

# 在 CI 模式下运行（以状态代码退出）
npm run test-inspector:ci

测试套件验证：

• 服务器启动和连接
• 工具可用性和响应
• 提示功能
• 错误处理
• 响应格式合规性

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

手动测试

使用 Shell 脚本

# 使用 stdio 传输进行测试（默认）
./scripts/inspector.sh

# 使用 SSE 传输进行测试
./scripts/inspector.sh -t sse -p 3001

# 启用调试模式
./scripts/inspector.sh -d

# 完整选项
./scripts/inspector.sh --transport sse --port 3001 --debug

使用 TypeScript 脚本

# 使用 stdio 传输进行测试（默认）
npm run inspector

# 使用 SSE 传输进行测试
npm run inspector -- -t sse -p 3001

# 启用调试模式
npm run inspector -- -d

# 完整选项
npm run inspector -- --transport sse --port 3001 --debug

可用选项

• -t, --transport <type>: 传输类型（stdio 或 sse），默认值：stdio
• -p, --port <number>: SSE 传输的端口号，默认值：3001
• -d, --debug: 启用调试模式

Inspector 命令示例

测试特定工具：

./scripts/inspector.sh
> tool get-highlights --parameters '{"page": 1, "page_size": 10}'

测试提示：

./scripts/inspector.sh
> prompt search-highlights --parameters '{"query": "python"}'

列出可用的工具和提示：

./scripts/inspector.sh
> list tools
> list prompts

在没有 Readwise API 密钥的情况下进行测试

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

npm run test-mock

这将运行一个测试脚本，该脚本：

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 错误条件的特定错误消息
• 所有工具和提示之间的一致错误格式
• 不会干扰协议的传输感知日志记录

开发

# 构建项目
npm run build

# 运行测试
npm test

# 在开发模式下启动，带有自动重新加载
npm run dev:watch

# Lint 代码
npm run lint

许可证

MIT