{
  "markdown": "# ZoteroBridge\n\n<p align=\"right\">\n  <b>🇨🇳 简体中文</b> | <a href=\"README-en.md\">🇬🇧 English</a>\n</p>\n\n<p align=\"center\">\n  <b>连接 Zotero SQLite 数据库的模型上下文协议 (MCP) 服务器</b>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/zotero-bridge\"><img src=\"https://img.shields.io/npm/v/zotero-bridge\" alt=\"npm version\"></a>\n  <a href=\"https://www.zotero.org/\"><img src=\"https://img.shields.io/badge/Zotero-7.0+-red\" alt=\"Zotero\"></a>\n  <a href=\"https://nodejs.org/\"><img src=\"https://img.shields.io/badge/Node.js-18+-green\" alt=\"Node.js\"></a>\n  <a href=\"https://www.typescriptlang.org/\"><img src=\"https://img.shields.io/badge/TypeScript-5.0+-blue\" alt=\"TypeScript\"></a>\n  <a href=\"https://modelcontextprotocol.io/\"><img src=\"https://img.shields.io/badge/MCP-1.0-purple\" alt=\"MCP\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-MIT-yellow\" alt=\"License\"></a>\n</p>\n\n## 概述\n\nZoteroBridge 是一个模型上下文协议 (MCP) 服务器，可直接连接到 Zotero 的 SQLite 数据库 (`zotero.sqlite`)，让 AI 助手（如 Claude、ChatGPT、GitHub Copilot 等）能够与您的 Zotero 文献库进行交互。\n\n### 主要特性\n\n- 🗂️ **文件夹管理** - 创建、重命名、移动和删除 Zotero 文件夹（集合）\n- 🏷️ **标签管理** - 为文献添加、删除和查询标签\n- 📖 **条目操作** - 搜索条目、获取详情、管理文件夹关系\n- 📝 **内容管理** - 读取/设置摘要，添加笔记\n- 📄 **PDF 处理** - 提取全文、生成摘要、全文搜索、获取标注\n- 🔍 **标识符搜索** - 通过 DOI、ISBN、PMID、arXiv、URL 查找文献\n- 🔗 **相关条目** - 查找手动关联、共享标签/作者的相似文献\n- 🛠️ **库维护** - 查找重复项、验证附件、清理孤立记录、合并条目\n\n---\n\n## 更新日志\n### v1.1.5 (2026-02-01)\n\n🗑️ **回收站识别功能**\n- ✅ 所有查询函数现在正确排除 `deletedItems` 表中的条目\n- ✅ `getItemDetails` 新增 `isDeleted` 和 `dateDeleted` 字段\n- ✅ `findItemByDOI/ISBN/Identifier` 自动跳过回收站中的条目\n- ✅ 新增 `isItemDeleted()` 方法检查条目是否在回收站\n- ✅ 新增 `getDeletedItems()` 方法获取回收站内容\n- ✅ 新增 `getDeletedItemsCount()` 方法获取回收站条目数量\n- ✅ 附件查询也排除已删除的附件\n### v1.1.3 (2026-02-01)\n\n🔧 **修复**\n- ✅ 修复了集合（文件夹）创建功能 - 添加了必需的 `clientDateModified` 字段\n- ✅ 修复了集合重命名功能 - 正确更新 `clientDateModified` 时间戳\n- ✅ 修复了集合移动功能 - 确保父子关系正确建立\n- ✅ 所有集合操作现在完全符合 Zotero 官方数据库规范\n\n现在可以正常使用：\n- 创建新集合（顶级文件夹）\n- 创建子集合（支持多层嵌套）\n- 重命名集合\n- 移动集合到其他父集合\n- 获取子集合列表\n\n### v1.1.2\n\n- 改进数据库连接稳定性\n- 优化错误处理机制\n\n### v1.1.0\n\n- 将 42 个工具整合为 13 个基于动作的工具\n- 简化接口同时保持全部功能\n\n---\n\n## 快速开始\n\n### 前置要求\n\n- Node.js 18.0 或更高版本\n- Zotero 7.0 或更高版本\n- 支持 MCP 的 AI 客户端（如 Claude Desktop、Cursor、VS Code Copilot）\n\n### 安装方式\n\n\n#### 从源码构建\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Combjellyshen/ZoteroBridge.git\ncd ZoteroBridge\n\n# 安装依赖\nnpm install\n\n# 构建项目\nnpm run build\n```\n\n### 配置 AI 客户端\n\n#### Claude Desktop\n\n添加到 Claude Desktop 配置文件：\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`  \n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"zotero-bridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"zotero-bridge\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n如果从源码构建：\n\n```json\n{\n  \"mcpServers\": {\n    \"zotero-bridge\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/ZoteroBridge/dist/index.js\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n#### Cursor IDE\n\n在项目根目录创建 `.cursor/mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"zotero-bridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"zotero-bridge\"]\n    }\n  }\n}\n```\n\n#### VS Code Copilot\n\n1. 打开 VS Code 设置 (`Ctrl+,`)\n2. 搜索 `github.copilot.chat.mcpServers`\n3. 点击 \"在 settings.json 中编辑\"\n4. 添加以下配置：\n\n```json\n\"github.copilot.chat.mcpServers\": {\n  \"zotero-bridge\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"zotero-bridge\"]\n  }\n}\n```\n\n#### 自定义数据库路径\n\n如果您的 Zotero 数据库不在默认位置：\n\n```json\n{\n  \"mcpServers\": {\n    \"zotero-bridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"zotero-bridge\", \"--db\", \"D:/MyZotero/zotero.sqlite\"]\n    }\n  }\n}\n```\n\n---\n\n## 可用工具（13 个工具）\n\n\n### manage_collection - 文件夹管理\n\n管理 Zotero 文件夹（集合）的所有操作。\n\n| 动作 | 描述 |\n|------|------|\n| `list` | 列出所有文件夹 |\n| `get` | 获取文件夹详情 |\n| `create` | 创建新文件夹 |\n| `rename` | 重命名文件夹 |\n| `move` | 移动文件夹到新父级 |\n| `delete` | 删除文件夹 |\n| `get_subcollections` | 获取子文件夹 |\n| `add_item` | 将条目添加到文件夹 |\n| `remove_item` | 从文件夹移除条目 |\n| `get_items` | 获取文件夹中的所有条目 |\n\n### manage_tags - 标签管理\n\n管理标签的所有操作。\n\n| 动作 | 描述 |\n|------|------|\n| `list` | 列出所有标签 |\n| `get_item_tags` | 获取条目的所有标签 |\n| `add` | 为条目添加标签 |\n| `remove` | 从条目移除标签 |\n| `create` | 创建新标签 |\n\n### search_items - 搜索条目\n\n按标题搜索 Zotero 条目。\n\n### get_item_details - 获取条目详情\n\n通过 ID 或 Key 获取条目的详细信息。\n\n### manage_item_content - 内容管理\n\n管理条目的摘要和笔记。\n\n| 动作 | 描述 |\n|------|------|\n| `get_abstract` | 获取条目摘要 |\n| `set_abstract` | 设置条目摘要 |\n| `get_notes` | 获取条目笔记 |\n| `add_note` | 为条目添加笔记 |\n\n### manage_pdf - PDF 操作\n\nPDF 文件的各种操作。\n\n| 动作 | 描述 |\n|------|------|\n| `extract_text` | 从 PDF 提取全文 |\n| `get_summary` | 获取 PDF 摘要信息 |\n| `list` | 获取条目的 PDF 附件列表 |\n| `search` | 在 PDF 中搜索文本 |\n| `generate_abstract` | 从 PDF 内容生成摘要 |\n\n### find_by_identifier - 标识符搜索\n\n通过各种标识符查找文献，支持自动检测。\n\n| 类型 | 描述 |\n|------|------|\n| `doi` | 通过 DOI 查找 |\n| `isbn` | 通过 ISBN 查找 |\n| `pmid` | 通过 PubMed ID 查找 |\n| `arxiv` | 通过 arXiv ID 查找 |\n| `url` | 通过 URL 查找 |\n| `auto` | 自动检测标识符类型 |\n\n### get_annotations - 获取标注\n\n获取 PDF 标注（高亮、笔记等），支持按类型、颜色筛选或搜索。\n\n### search_fulltext - 全文搜索\n\n在 Zotero 全文索引中搜索或获取附件的全文内容。\n\n### find_related_items - 查找相关条目\n\n通过多种方式查找相关文献。\n\n| 方法 | 描述 |\n|------|------|\n| `manual` | 获取手动关联的条目 |\n| `tags` | 通过共享标签查找 |\n| `creators` | 通过共享作者查找 |\n| `collection` | 在同一文件夹中查找 |\n| `all` | 使用所有方法查找 |\n\n### get_database_info - 数据库信息\n\n获取 Zotero 数据库信息（路径、存储位置、统计数据）。\n\n### raw_query - 原始 SQL 查询\n\n执行原始 SQL 查询（仅支持 SELECT，只读）。\n\n### library_maintenance - 库维护 🆕\n\n维护和清理 Zotero 库的工具。\n\n| 动作 | 描述 |\n|------|------|\n| `find_duplicates` | 查找重复条目（按标题、DOI 或 ISBN） |\n| `validate_attachments` | 验证附件文件是否存在 |\n| `get_valid_attachment` | 获取条目的有效附件 |\n| `find_with_valid_pdf` | 查找有有效 PDF 的条目 |\n| `cleanup_orphans` | 清理孤立的附件记录（支持 dry-run） |\n| `merge_items` | 合并重复条目 |\n\n---\n\n## 使用示例\n\n### 与 Claude/Copilot 配合使用\n\n```\n# 搜索文献\n搜索标题中包含\"深度学习\"的条目\n\n# 获取详情\n获取 itemID 为 1234 的条目详细信息\n\n# 管理文件夹\n创建一个名为\"机器学习论文\"的新文件夹\n将条目 1234 添加到文件夹 5678\n\n# PDF 操作\n提取附件 ID 为 100 的 PDF 全文\n在这个 PDF 中搜索\"neural network\"\n\n# 通过 DOI 查找\n查找 DOI 为 10.1126/science.aaa2397 的文献\n\n# 获取标注\n获取条目 1234 的所有高亮标注\n\n# 库维护\n查找我的库中的重复条目\n检查条目 1234 的附件是否有效\n```\n\n---\n\n## 项目结构\n\n```\nZoteroBridge/\n├── src/\n│   ├── index.ts      # MCP 服务器入口\n│   ├── database.ts   # Zotero SQLite 数据库操作\n│   ├── pdf.ts        # PDF 处理模块\n│   └── tools.ts      # MCP 工具定义（13 个整合工具）\n├── dist/             # 编译输出\n├── test/             # 测试文件\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n---\n\n## 开发指南\n\n### 开发模式\n\n```bash\n# 监听文件变化并自动编译\nnpm run dev\n```\n\n### 构建\n\n```bash\nnpm run build\n```\n\n### 命令行参数\n\n```bash\n# 显示帮助\nzotero-bridge --help\n\n# 指定数据库路径\nzotero-bridge --db /path/to/zotero.sqlite\n\n# 只读模式\nzotero-bridge --readonly\n```\n\n---\n\n## 注意事项\n\n1. **关闭 Zotero**：使用写入功能时，请关闭 Zotero 客户端以避免数据库锁定\n2. **备份数据**：在进行修改前备份 `zotero.sqlite`\n3. **只读模式**：仅读取数据时使用 `--readonly` 参数更安全\n4. **附件验证**：使用 `library_maintenance` 的 `validate_attachments` 检查文件是否存在\n\n---\n\n## 更新日志\n### v1.1.4 (2026-02-01)\n\n🔧 **重要修复 - 数据库兼容性**\n- ✅ 修复重复项查询不一致问题 - `findItemByDOI/ISBN` 现在始终返回最新修改的条目\n- ✅ 修复 `itemTags.type` 字段 - 该字段为 NOT NULL，必须提供值\n- ✅ 动态获取 `note`/`attachment` 的 itemTypeID，不再硬编码\n- ✅ 所有查询现在排除 `deletedItems` 表中的已删除条目\n\n🚀 **新功能**\n- ✨ 添加事务支持 (`beginTransaction/commitTransaction/rollbackTransaction`)\n- ✨ `mergeItems` 现在使用事务保证数据一致性\n- ✨ `mergeItems` 新增附件转移功能\n- ✨ 重复项查询现在返回 `_duplicateWarning` 警告信息\n\n🛡️ **安全性改进**\n- 所有写操作前检查 Zotero 进程状态\n- 自动创建数据库备份\n- 批量操作使用事务保护\n### v1.1.2 (2025-02-01)\n- 更新所有依赖到最新版本\n- 修复 Zod 4.x 兼容性问题\n- 修复 pdf-parse 2.x ESM 导入问题\n\n### v1.1.1 (2025-02-01)\n- 将 42 个工具整合为 13 个基于动作的工具\n- 新增 `library_maintenance` 工具（重复检测、附件验证、孤立清理、条目合并）\n\n### v1.1.0\n- 初始整合版本\n\n---\n\n## 📄 许可证\n\n本项目采用 [MIT 许可证](LICENSE)。\n\n---\n\n## 🙏 致谢\n\n- [Zotero](https://www.zotero.org/) - 开源文献管理工具\n- [Model Context Protocol](https://modelcontextprotocol.io/) - AI 工具集成协议\n- [cookjohn/zotero-mcp](https://github.com/cookjohn/zotero-mcp) - 项目参考\n\n---\n\n## 📬 联系方式\n\n- 作者：Combjellyshen\n- GitHub：[https://github.com/Combjellyshen/ZoteroBridge](https://github.com/Combjellyshen/ZoteroBridge)\n- npm：[https://www.npmjs.com/package/zotero-bridge](https://www.npmjs.com/package/zotero-bridge)\n\n欢迎提交 Issue 或 Pull Request！\n",
  "bytes": 7828,
  "sha": "9c16b73d604d2c947cd2c1f1e28833060f58f7e78e340cd404ffa09f062dbd7d",
  "repo_slug": "combjellyshen/zoterobridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_combjellyshen_zotero_bridge_3861eaf1/readme"
}