Readwise MCP Server

这是一个用于访问和与您的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密钥。

使用

命令行接口

# 使用stdio传输启动（默认，适用于Claude桌面版）
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脚本来运行检查器。

自动化测试

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

# 运行自动化检查器测试
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：启用调试模式

示例检查器命令

测试特定工具：

./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

# 代码检查
npm run lint

许可证

MIT