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

安装

# 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 --debug

API

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 错误
- 包括对必需参数的验证

发展

# 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

执照

麻省理工学院

Readwise MCP Server