229 lines
8.1 KiB
Markdown
229 lines
8.1 KiB
Markdown
|
# Raindrop书签AI管理
|
|||
|
|
|
|||
|
|
`书签管理` `MCP` `AI助手` `Raindrop.io` `自然语言`
|
|||
|
|
|
|||
|
|
# Raindrop.io MCP 服务器
|
|||
|
|
|
|||
|
|
[](https://smithery.ai/server/@adeze/raindrop-mcp)
|
|||
|
|
[](https://www.npmjs.com/package/@adeze/raindrop-mcp)
|
|||
|
|
[](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) 文件。
|