Readwise MCP 服务器
用于访问和与您的 Readwise 库交互的模型上下文协议 (MCP) 服务器。
特征
访问 Readwise 图书馆中的精彩内容
使用自然语言查询搜索亮点
从图书馆获取书籍和文件
与 Claude 和其他 MCP 兼容助手无缝集成
增强的亮点分析提示功能
传输感知日志系统
强大的错误处理和验证
MCP 协议符合正确的 request_id 处理
用于监控的健康检查端点
改进了设置向导，带有 API 密钥验证
Related MCP server: Reader MCP Server
项目结构
该存储库分为以下主要目录：
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/ ：用于开发和测试的实用脚本
安装
# Install from npm
npm install -g readwise-mcp
# Or clone the repository and install dependencies
git clone https://github.com/your-username/readwise-mcp.git
cd readwise-mcp
npm install
npm run build设置
在使用服务器之前，您需要配置您的 Readwise API 密钥：
# Run the setup wizard
npm run setup
# Or start with the API key directly
readwise-mcp --api-key YOUR_API_KEY您可以从https://readwise.io/access_token获取 API 密钥。
用法
命令行界面
# Start with stdio transport (default, for Claude Desktop)
readwise-mcp
# Start with SSE transport (for web-based integrations)
readwise-mcp --transport sse --port 3000
# Enable debug logging
readwise-mcp --debugAPI
import { ReadwiseMCPServer } from 'readwise-mcp';
const server = new ReadwiseMCPServer(
'YOUR_API_KEY',
3000, // port
logger,
'sse' // transport
);
await server.start();使用 MCP Inspector 进行测试
该项目内置了使用 MCP 检查器进行测试的支持。您可以使用 TypeScript 脚本或 Shell 脚本来运行检查器。
自动化测试
运行验证所有工具和提示的自动测试套件：
# Run automated inspector tests
npm run test-inspector
# Run in CI mode (exits with status code)
npm run test-inspector:ci测试套件验证：
服务器启动和连接
工具可用性和响应
提示功能
错误处理
响应格式合规性
每个测试都提供详细的输出和通过/失败案例的摘要。
手动测试
使用 Shell 脚本
# Test with stdio transport (default)
./scripts/inspector.sh
# Test with SSE transport
./scripts/inspector.sh -t sse -p 3001
# Enable debug mode
./scripts/inspector.sh -d
# Full options
./scripts/inspector.sh --transport sse --port 3001 --debug使用 TypeScript 脚本
# Test with stdio transport (default)
npm run inspector
# Test with SSE transport
npm run inspector -- -t sse -p 3001
# Enable debug mode
npm run inspector -- -d
# Full options
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这将运行一个测试脚本：
创建 Readwise API 的模拟实现
使用此模拟 API 设置 MCP 服务器
使用样本数据测试各种端点
无需真实 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 错误条件的特定错误消息
所有工具和提示的错误格式一致
传输感知日志记录不会干扰协议
发展
# Build the project
npm run build
# Run tests
npm test
# Start in development mode with auto-reload
npm run dev:watch
# Lint code
npm run lint执照
麻省理工学院