# Raindrop书签AI管理

`书签管理` `MCP` `AI助手` `Raindrop.io` `自然语言`

# Raindrop.io MCP 服务器

[![smithery badge](https://smithery.ai/badge/@adeze/raindrop-mcp)](https://smithery.ai/server/@adeze/raindrop-mcp)
[![npm version](https://badge.fury.io/js/%40adeze%2Fraindrop-mcp.svg)](https://www.npmjs.com/package/@adeze/raindrop-mcp)
[![Claude Desktop MCPB](https://img.shields.io/badge/Claude%20Desktop-MCPB-5B61FF?logo=claude&logoColor=white)](https://github.com/adeze/raindrop-mcp/releases)

通过简单的 MCP 服务器将 Raindrop.io 连接到你的 AI 助手，用自然语言整理、搜索和管理书签。

## 功能介绍

- 创建、更新和删除收藏夹与书签
- 按标签、域名、类型、日期等条件搜索书签
- 管理标签（列出、重命名、合并、删除）
- 读取书签高亮内容
- 批量编辑收藏夹中的书签
- 检查失效链接和重复项，管理回收站

## 工具列表

- **diagnostics** - 服务器诊断信息及库健康指标
- **collection_list** - 以扁平列表形式列出所有收藏夹
- **get_collection_tree** - 带完整面包屑路径的层级收藏夹视图
- **collection_manage** - 创建、更新或删除收藏夹
- **bookmark_search** - 支持过滤器、标签和分页的高级搜索
- **bookmark_manage** - 创建、更新或删除书签
- **get_raindrop** - 通过 ID 获取单个书签
- **list_raindrops** - 分页列出收藏夹中的书签
- **get_suggestions** - 针对 URL 或书签提供 AI 驱动的整理建议（标签/收藏夹）
- **suggest_tags** - 利用 AI 辅助分析从书签元数据中推荐相关标签
- **bulk_edit_raindrops** - 批量更新、移动或删除指定收藏夹中的书签
- **tag_manage** - 重命名、合并或删除标签
- **highlight_manage** - 创建、更新或删除高亮内容
- **library_audit** - 扫描库中的失效链接、重复项和未打标签的条目
- **empty_trash** - 永久清空回收站（需确认）
- **cleanup_collections** - 删除空收藏夹（需确认）
- **remove_duplicates** - 通过安全确认流程查找并删除重复书签

## 安装

### 快速开始（一行命令）

| 工具               | 一行命令                                                           |
| :----------------- | :----------------------------------------------------------------- |
| **Gemini CLI**     | `gemini extensions install https://github.com/adeze/raindrop-mcp`  |
| **Codex CLI**      | `codex mcp add raindrop -- npx -y @adeze/raindrop-mcp`             |
| **Claude Code**    | `claude mcp add raindrop -- npx -y @adeze/raindrop-mcp`            |
| **GitHub Copilot** | `gh copilot config mcp add raindrop -- npx -y @adeze/raindrop-mcp` |
| **Vercel Skills**  | `npx skills add adeze/raindrop-mcp`                                |

> **注意**：通过 `npx` 添加 MCP 服务器的工具，需要在 shell 或工具的环境配置中设置 `RAINDROP_ACCESS_TOKEN` 环境变量。

### Vercel Skills（npx skills）

本项目兼容 [Vercel Skills](https://github.com/vercel/skills) 系统，所有必要的清单文件均已包含：

- `manifest.json`：用于服务器定义的标准 MCP 清单。
- `SKILL.md`：供 Agent 发现使用的标准化技能描述。
- `mcp.json`：MCP 客户端和注册表的根配置。

将此服务器添加到本地技能目录：

```bash
npx skills add adeze/raindrop-mcp --global
```

若要将其贡献到 [Vercel Skills Registry](https://github.com/vercel/skills/tree/main/registry)，请提交 Pull Request，将此仓库 URL 添加到注册表中。

### Claude Desktop（MCPB）

从 GitHub Release 下载最新的 raindrop-mcp.mcpb，并添加到 Claude Desktop：

- 发布页：https://github.com/adeze/raindrop-mcp/releases

在 Claude Desktop 中添加该包并设置以下环境变量：

- RAINDROP_ACCESS_TOKEN（来自 Raindrop.io 集成设置）

### NPX（命令行）

将 API Token 设置为环境变量后运行：

```bash
export RAINDROP_ACCESS_TOKEN=YOUR_RAINDROP_ACCESS_TOKEN
npx @adeze/raindrop-mcp
```

### 手动配置 MCP（mcp.json）

在 MCP 客户端配置中添加以下内容：

```json
{
  "servers": {
    "raindrop": {
      "type": "stdio",
      "command": "npx",
      "args": ["@adeze/raindrop-mcp@latest"],
      "env": {
        "RAINDROP_ACCESS_TOKEN": "YOUR_RAINDROP_ACCESS_TOKEN"
      }
    }
  }
}
```

## 前提条件

- 一个 Raindrop.io 账号
- Raindrop.io API 访问令牌：https://app.raindrop.io/settings/integrations

## 支持

- 问题反馈：https://github.com/adeze/raindrop-mcp/issues

## 发布流程

本仓库使用 `semantic-release` 作为唯一支持的发布方式。

### 发布机制

- 发布由推送到 `master` 分支触发，通过 `.github/workflows/ci.yml` 执行。
- `semantic-release` 分析约定式提交信息，计算下一个版本号，更新 `CHANGELOG.md`，在 GitHub 上创建标签/发布，并发布到 npm。
- 发布准备期间，`.releaserc.json` 会同步 `manifest.json`、`mcp.json` 和 `gemini-extension.json`，然后构建 `raindrop-mcp.mcpb`，使 GitHub Release 包含该包。

### 预发布演习

- 在正式发布前，通过 **Run workflow** 运行 `.github/workflows/release-dry-run.yml`。
- 该流程会验证语义版本计算、注册表鉴权和发布管道行为，但不会实际发布。

### 所需密钥

- `GITHUB_TOKEN` 由 GitHub Actions 提供，用于发布自动化。

### npm 可信发布

- npm 发布通过 GitHub Actions OIDC 可信发布配置。
- 标准 CI 发布路径无需 `NPM_TOKEN`。

### 合并前本地验证

```bash
bun run lint
bun run type-check
bun run test
bun run build
```

### 提交信息示例

- `fix: handle empty tag merge payload`
- `feat: add collection path filter`
- `feat!: remove deprecated search parameter`

正常发布请勿手动修改版本号、推送发布标签或手动执行 npm publish。

## 📋 近期更新（v2.4.x）

### 智能整理与层级管理

- **AI 建议**：新增 `get_suggestions` 工具，通过 Raindrop API 和 MCP Sampling 提供整理建议。
- **收藏夹树**：`get_collection_tree` 工具提供带完整面包屑路径的层级视图。
- **批量移动**：为 `bulk_edit_raindrops` 新增 `move` 操作，提升库整理效率。
- **分页支持**：为 `list_raindrops` 和 `bookmark_search` 统一实现分页，适配大型书签库。

### 安全性与质量

- **确认逻辑**：破坏性操作（`empty_trash`、`cleanup_collections`）现在需要明确确认。
- **命名规范化**：所有工具统一使用 snake_case 命名约定。
- **CI/CD 流水线**：增强 GitHub Actions，支持自动代码检查、类型检测和跨传输测试。
- **代码质量**：建立 ESLint 和 Prettier 配置，保障可维护的开发体验。

## 📋 历史更新（v2.3.3）

### 高级清理与库审计

## 📋 历史更新（v2.3.2）

### MCP 资源链接实现

- 遵循最新 MCP SDK 最佳实践的现代 `resource` 内容
- 高效数据访问：工具返回轻量链接而非完整数据
- 更佳性能：客户端仅在需要时获取完整书签/收藏夹数据
- 与动态资源系统无缝集成（`mcp://raindrop/{id}`）

### SDK 与 API 更新

- 升级至本仓库最新支持的 MCP SDK
- 改进描述的现代工具注册方式
- 修复 API 端点和路径参数
- 所有核心工具完全可用

### 工具优化

- 书签/收藏夹列表响应更节省资源
- 通过 `mcp://collection/{id}` 和 `mcp://raindrop/{id}` 动态访问资源
- 更轻量的列表数据提升客户端体验
- 完全符合官方 SDK 模式的 MCP 规范

### 服务层改进

- 通过提取公共 helper 减少代码量
- 统一的错误处理和响应处理
- 泛型处理器增强类型安全性
- 集中化的端点构建

### 测试改进

- 更强的 MCP 工具执行端到端覆盖
- 扩展针对真实客户端流程的集成测试

### MCP 2.0 准备（批量操作）

- 为 MCP 2.0 批量操作工作流和工具奠定基础

### OAuth（即将推出）

- 基于 OAuth 的认证流程，无需手动配置 Token

### 说明

对近期几个版本给大家带来的不便深感抱歉，感谢你们的耐心等待和反馈。

## 许可证

本项目基于 MIT 许可证授权，详见 [LICENSE](LICENSE) 文件。