readwise-mcp

🚀 Readwise MCP 服务器

Readwise MCP 服务器是一个模型上下文协议（MCP）服务器，它能让你轻松访问和交互自己的 Readwise 图书馆，为你提供便捷的信息获取和处理体验。

✨ 主要特性

• 可访问 Readwise 中的高亮内容。
• 支持使用自然语言查询搜索高亮内容。
• 能够获取 Readwise 中的书籍信息。
• 可以获取 Readwise 中的文档资料。
• 能搜索并处理来自 Readwise 的高亮内容，支持摘要、分析、关联查找和问题生成。

📦 安装指南

1. 克隆仓库

   git clone https://github.com/your-repository.git
   cd your-repository
   

2. 安装依赖项

   npm install
   

3. 构建项目

   npm run build
   

📚 详细文档

配置设置

1. 运行设置向导

   npm run setup
   

2. 配置 API 密钥
   • 打开 config.js 文件。
   • 在其中添加您的 Readwise API 密钥。
   • 保存文件。

使用说明

💻 使用示例

基础用法

CLI 使用示例

# 获取高亮内容
npm run get-highlights -- [--page=1 --limit=10]

# 搜索高亮内容
npm run search-highlights -- [--query="您的搜索词" --exact]

高级用法

API 示例代码

const { MCPClient } = require('@readwise/mcp-client');

// 初始化客户端
const client = new MCPClient('your-api-key');

// 获取高亮内容
async function getHighlights() {
    try {
        const response = await client.getHighlights({
            page: 1,
            limit: 10
        });
        console.log(response.data);
    } catch (error) {
        console.error('获取高亮内容失败:', error.message);
    }
}

// 搜索高亮内容
async function searchHighlights() {
    try {
        const response = await client.searchHighlights({
            query: '您的搜索词',
            exact: true
        });
        console.log(response.data);
    } catch (error) {
        console.error('搜索高亮失败:', error.message);
    }
}

测试方法

1. 运行自动化测试

   npm test
   

2. 手动测试工具
   • 使用 get_highlights 工具获取高亮内容。
   • 使用 search_highlights 工具搜索高亮内容。
3. 使用 Mock 测试环境

   npm run test-mock
   

可用工具

• 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 错误情况提供具体错误消息。
• 在所有工具和提示中保持一致的错误格式。
• 运输感知日志记录，不干扰协议流程。

开发信息

# 构建项目
npm run build

# 执行测试
npm test

# 开发模式启动（自动重载）
npm run dev:watch

# 代码检查
npm run lint

🔧 技术细节

项目结构

# 主代码目录
src/

# 测试脚本目录
test-scripts/

# 文档目录
docs/

# 示例配置文件目录
examples/

📄 许可证

本项目采用 MIT 许可证。