zotero-agent

# Zotero 代理 > **英文** | [中文](./README-zh.md) **Zotero 代理** 是一款 Zotero 插件，它嵌入了一个 MCP（模型上下文协议）服务器，将您的本地 Zotero 库变成一个 AI 代理可以完全操作的空间 — 而不仅仅是读取。 它提供了 **46 种工具**，涵盖库搜索和检索、元数据丰富、基于标识符的导入（DOI / arXiv / ISBN / PMID）、批量参考文献导入（BibTeX / RIS / CSL-JSON）、预印本→已发表版本升级、DOI 修复、灰色来源 PDF 下载（Sci-Hub / Anna's Archive）、重复检测和合并、批量标签、引用图扩展、注释合成，以及伴侣插件桥梁（jasminum、Linter）— 以及一个逃生口 `run_javascript`，用于超出内置工具的任意进程内自动化。 在实践中，与此服务器对话的 AI 助手（Claude、Codex 等）可以通过自然语言搜索您的库、批量清理元数据和标签、导入和删除重复论文、获取缺失的 PDF、通过引用图扩展主题、以及合成您的注释 — 默认情况下每次写入都进行干燥运行。 ## 如何使用 ### 步骤 1：安装 Zotero 插件 1. 从 [发布页面](https://github.com/psiQAQ/zotero-agent/releases/) 下载最新的 `zotero-agent.xpi`。 2. 通过 `Tools -> [gear icon] -> Install Plugin From File...` 在 Zotero 中安装它。 3. 打开 `Editor -> Settings -> Zotero Agent` 并启用这些权限： 1. 允许远程访问 2. 启用写入操作 3. 运行 JavaScript（eval） > 注意：`Run JavaScript (eval)` 用于在 Zotero 中运行 JavaScript，以便处理超出内置 MCP 工具的任务。只有在需要时才启用它。 ### 步骤 2：配置您的 AI 客户端 从 `Zotero -> Editor -> Settings -> Zotero Agent -> PSK` 获取您的令牌。 #### Codex 应用 前往 `Setting -> MCP Servers -> Add server`，然后使用此配置： | 字段 | 值 | | --- | --- | | MCP 服务器名称 | `zotero-mcp` | | 传输 | `Streamable HTTP` | | URL | `http://127.0.0.1:23120/mcp` | | 头部密钥：`Authorization` | `Bearer <YOUR_PSK>` | | 头部密钥：`Content-Type` | `application/json` | #### Codex CLI 编辑 `%USERPROFILE%/.codex/config.toml` 或 `~/.codex/config.toml`： ```toml [mcp_servers.zotero-mcp] enabled = true url = "http://127.0.0.1:23120/mcp" http_headers = { Authorization = "Bearer <YOUR_PSK>", "Content-Type" = "application/json" } ``` #### Claude 代码 ```powershell $env:ZOTERO_MCP_BEARER_TOKEN = "YOUR TOKEN" claude mcp add --transport http zotero-mcp http://127.0.0.1:23120/mcp ` --scope user ` --header "Authorization: Bearer $env:ZOTERO_MCP_BEARER_TOKEN" ` --header "Content-Type: application/json" ``` > 注意：如果您在此项目中安装它并从此项目目录运行，请不要使用 `--scope user`。 ### 步骤 3（可选）：推荐的伴侣插件 这些插件与 Zotero 代理一起运行 — 它们不包含在内，但安装后，AI 代理可以通过 `run_javascript` 工具驱动它们（Zotero 的特权上下文可以访问任何已安装插件的 API）。安装适合您工作流的插件： | 插件 | 功能 | 它如何与此插件/代理配对 | | --- | --- | --- | | [jasminum 茉莉花](https://github.com/l0o0/jasminum) | 抓取中文数据库元数据（CNKI / 万方 / VIP），用于字段不完整的中文文献。 | 此插件的内置丰富功能针对西方来源（CrossRef / OpenAlex）；jasminum 填补了中文空白。导入中文 PDF 后，代理可以通过 `run_javascript` 触发其抓取/文件名匹配。 | | [zotero-updateifsE 绿青蛙](https://github.com/redleafnew/zotero-updateifsE) | 将影响因子、JCR / CAS 四分位数和其他期刊指标写入项目。 | 在 `import_by_identifier` / `enrich_item_metadata` 填写核心元数据后，代理可以通过 `run_javascript` 按收藏批量更新指标。 | | [zotero-format-metadata](https://github.com/northword/zotero-format-metadata) | 50+ 元数据校验器：标题大小写、日期、页码、LTWA 期刊缩写、中国名称/拼音清理。 | 补充 `enrich_item_metadata`（填写字段）以进行格式规范化 — 代理可以在丰富后运行其校验规则作为清理步骤。 | | [zotero-zotadata](https://github.com/ydeng11/zotero-zotadata) | 多源元数据填充 + 多提供商 PDF 发现（Unpaywall / arXiv / CORE / ...）。 | 当您需要更广泛的 PDF 来源时，这是 `find_missing_pdfs` 的更重替代方案；代理可以通过 `run_javascript` 调用其检索管道。 | **让代理为您安装它们。** 启用 `run_javascript`（eval）后，粘贴类似的提示 — 根据需要修剪列表： > 请通过 `run_javascript` 安装这些 Zotero 伴侣插件。对于每个仓库：`fetch` `https://api.github.com/repos/<repo>/releases/latest`，选择名称以 `.xpi` 结尾的资产，使用 `AddonManager.getInstallForURL(url)` 安装，然后 `install.install()`，并报告每个插件的 id / 版本 / 活动状态。删除我不需要的： > - jasminum (中文元数据：CNKI / 万方 / VIP) — `l0o0/jasminum` > - Green Frog / updateifsE (影响因子和四分位数) — `redleafnew/zotero-updateifsE` > - Linter / format-metadata (格式清理和期刊缩写) — `northword/zotero-format-metadata` > - Zotadata (多源填充 + PDF 发现) — `ydeng11/zotero-zotadata` 一些插件可能需要重启 Zotero 才能完全激活。注意：其中大部分也可以在社区 [Zotero 插件市场](https://github.com/syt2/zotero-addons) 中搜索（例如，`format-metadata` 在那里显示为 **"Linter for Zotero"**）；少数几个（像 `zotadata`）仅在 GitHub 发布。 > 请参阅下面的 **基于开源 - 集成状态和路线图** 部分，了解每个插件当前如何调用以及我们计划推广哪些交互到专用 MCP 工具。 ## 灰色来源 PDF 下载（Sci-Hub / Anna's Archive） 除了 Zotero 内置的开放访问解析器外，插件还可以使用 Sci-Hub / Anna's Archive 作为备用 PDF 下载来源。 **在首选项面板中启用。** 在 `Editor -> Settings -> Zotero Agent` 中，打开 Sci-Hub / Anna's Archive 开关。出现一个预填充了合理默认值的源列表（多个 Sci-Hub 镜像 + Anna's Archive）；您可以添加或删除源，或恢复默认值。源注册为**仅手动**解析器 — 仅在您明确触发下载时使用，从不在后台。所有内容默认关闭。 **下载。** 启用后，Zotero 的原生右键单击 **Find Available PDF** 自动包括这些来源：Zotero 首先尝试免费来源（arXiv / 开放访问），并仅在需要时回落到灰色来源。您也可以通过 MCP 工具 `manage_pdf_resolvers`（启用/禁用和管理源列表）和 `find_missing_pdfs`（审核哪些项目缺少 PDF，然后获取）来驱动它。 **合规性。** Sci-Hub / Anna's Archive 是灰色地带来源。您负责在您的司法管辖区确保合法合规。 ## 开发设置 克隆仓库： ```bash git clone https://github.com/psiQAQ/zotero-agent.git cd zotero-agent ``` 设置插件开发环境： ```bash npm install npm run build ``` 在 Zotero 中加载插件： ```bash # 用于自动重新加载的开发 npm run start # 或手动安装已构建的 .xpi 文件 # .xpi 文件将生成在 "./.scaffold/build/zotero-agent.xpi" npm run build ``` ## MCP 工具 下表基于 `src/modules/streamableMCPServer.ts` 中的实际工具定义。 | 工具名称 | 目的 | | --- | --- | | `get_libraries` | 列出当前客户端中可用的 Zotero 库。 | | `search_library` | 使用标题、年份、全文、项目类型和相关性评分等筛选条件搜索 Zotero 库。 | | `search_libraries` | 按名称搜索库。 | | `search_annotations` | 按查询、颜色、标签或项目范围搜索高亮、笔记和评论。 | | `get_item_details` | 获取特定 Zotero 项目的详细元数据。 | | `get_annotations` | 获取特定项目或注释 ID 的注释和笔记。 | | `get_content` | 从 PDF、附件、笔记和摘要中读取全文内容。 | | `get_collections` | 列出库中的集合，包括需要时递归的树输出。 | | `search_collections` | 按名称搜索集合。 | | `get_collection_details` | 获取特定集合的详细信息。 | | `get_collection_items` | 列出特定集合中的项目。 | | `get_subcollections` | 获取特定集合下的子集合。 | | `create_collection` | 创建一个新集合，可选地在父集合下。 | | `update_collection` | 重命名或移动现有集合。 | | `delete_collection` | 删除集合，可选删除项目。 | | `add_items_to_collection` | 将一个或多个项目添加到集合中。 | | `remove_items_from_collection` | 从集合中删除一个或多个项目，而不删除它们从库中。 | | `search_fulltext` | 跨缓存的全文文档内容搜索并返回匹配段落。 | | `get_item_abstract` | 获取特定项目的摘要或总结。 | | `semantic_search` | 运行基于嵌入的语义搜索，以查找概念相关的內容。 | | `find_similar` | 查找与给定项目语义相似的项目。 | | `semantic_status` | 显示语义搜索服务的狀態和索引统计信息。 | | `fulltext_database` | 访问缓存的全文数据库，支持列表、搜索、获取和统计操作。 | | `write_note` | 创建、更新或追加 Zotero 笔记。 | | `write_tag` | 在 Zotero 项目上添加、删除或替换标签。 | | `write_metadata` | 更新项目元数据，如标题、摘要、DOI、日期或创作者。 | | `write_item` | 创建项目、重新父级附件或导入本地文件作为附件。 | | `run_javascript` | 在 Zotero 进程中执行 JavaScript 以进行高级自动化。 | | `reload_plugin` | 重新加载已安装的 Zotero 插件以进行开发工作流。 | | `install_plugin_from_url` | 从可访问的 URL 或文件路径安装或升级插件 XPI。 | | `import_by_identifier` | 按 DOI、arXiv ID、ISBN 或 PMID 导入项目。 | | `import_bibliography` | 批量导入 BibTeX / RIS / CSL-JSON（自动检测）；按 DOI / 标题相似性幂等去重；默认干燥运行计划。 | | `find_missing_pdfs` | 报告缺少 PDF 的项目或为它们获取开放访问的 PDF。 | | `manage_pdf_resolvers` | 将 Sci-Hub / Anna's Archive 注册到 Zotero 的原生 PDF 解析器首选项（灰色来源默认为自动=false，仅手动）；实际下载通过 `find_missing_pdfs` 进行。 | | `extract_identifier_from_pdf` | 从 PDF 的全文缓存中挖掘 DOI 或 arXiv ID，使用频率投票。只读。 | | `find_doi` | 通过 CrossRef 标题相似性融合（≥0.86 阈值）或 `mode:"repair"` 验证失效的 DOI（Handle System API）并提出替换；干燥运行默认，确认写入需要 `write.enabled`。 | | `enrich_item_metadata` | 从 DOI 通过 doi.org CSL-JSON + OpenAlex 填写缺失的字段（摘要/场地/卷/期/页码/ISSN/出版商/日期）；干燥运行默认，确认写入需要 `write.enabled`。 | | `upgrade_preprints` | 通过 OpenAlex 标题搜索查找 arXiv 样式的预印本的已发表版本并升级 DOI/场地/日期/项目类型；旧值备份到 Extra；干燥运行默认。 | | `check_retractions` | 检查项目是否涉及 scite.ai 编辑通知，如撤回或更正。 | | `find_related_papers` | 通过 OpenAlex 遍历引用图以查找引用或引用的论文。 | | `synthesize_annotations` | 将高亮和笔记聚合为文献综述的 markdown 捆绑。 | | `find_duplicates` | 使用 Zotero 的原生重复引擎检测重复项目。 | | `merge_duplicates` | 将重复项目合并为选择的母项目。 | | `batch_update_tags` | 运行批量标签操作，如添加、删除或重命名。 | | `fetch_chinese_metadata` | 通过 jasminum 伴侣插件（资格分类和防挂卫士）抓取 CNKI/Wanfang/VIP 元数据。 | | `lint_metadata` | 在项目上运行 zotero-format-metadata（Linter）规则 - 标题大小写、日期、期刊缩写、中国名称拆分；未知 ID 被拒绝并提供有效列表。 | ## 构建于开源 - 集成状态和路线图 该插件建立在多个开源项目之上：它分叉了一个可写的进程内 MCP 基础，并融合了来自 ~17 个参考项目的最佳创意（存档为 `refs/` 下的子模块）。完整的技术比较位于： - [AI / MCP 集成方法](./docs/benchmarking/ai-plugins-mcp.md) - 5 个项目 - [元数据丰富插件](./docs/benchmarking/metadata-enrichment.md) - 8 个项目 - [PDF 下载方法](./docs/benchmarking/pdf-download.md) - 4 个项目 ### 1. 此分叉在基础之上添加的内容 从 [cookjohn/zotero-mcp](https://github.com/cookjohn/zotero-mcp) 分叉 - 一个干净的进程内本地可写的 MCP 服务器（27 个工具，直接 `saveTx`/`eraseTx`）。我们的添加： | 领域 | cookjohn 基础 | 此分叉添加 | | --- | --- | --- | | 认证 | 环回仅限 | **PSK Bearer** 认证 + `Origin` 验证（DNS 绑定防御） | | 评估 | 无 | **`run_javascript`** 特权评估工具（超时 + 100 KB 限制） | | 工具 | 27 | **46** - +19 个工具（标识符和批量参考文献导入、缺少 PDF 审计、引用图、重复、批量标签、元数据丰富、DOI 反向查找和修复、预印本升级、灰色来源下载、伴侣插件桥梁等） | | 搜索 | 关键字 | + RRF **混合** 语义搜索、0 结果 **fallback 阶梯** | | 测试 | 无 | 31 个场景 **selfTest** + 节点单元测试（91 个案例） | | 部署 | 手动 | 一次性 **deploy_live**（base64 船 + 自我升级） + `reload_plugin` / `install_plugin_from_url` | | i18n | zh / en | + de / es / fr / ja | ### 2. 从参考项目集成（集成） 想法 **重新实现**（而非 vendored）到原生工具： **AI / MCP** - 参见 [比较](./docs/benchmarking/ai-plugins-mcp.md） | 来源 | 集成到 | 状态 | TODO | | --- | --- | **TODO** | | [54yyyu/zotero-mcp](https://github.com/54yyyu/zotero-mcp) | `import_by_identifier`、`import_bibliography`（BibTeX / RIS / CSL-JSON）、`find_missing_pdfs`、 `find_related_papers`（OpenAlex）、`check_retractions`（scite）、`synthesize_annotations` | ✅ | 批量 OA 索引 | | [introfini/ZotSeek](https://github.com/introfini/ZotSeek) | RRF 混合 `semantic_search` | ✅ | WebGPU 加速；Matryoshka 维度截断 | | [introfini/mcp-server-zotero-dev](https://github.com/introfini/mcp-server-zotero-dev) | `run_javascript`、`reload_plugin`、`install_plugin_from_url` | ✅ | 截图 / DOM 检视工具，用于 UI 调试 | **元数据** - 参见 [比较](./docs/benchmarking/metadata-enrichment.md) | 来源 | 集成到 | 状态 | TODO | | --- | --- | --- | --- | | [zotero-metadata-hunter](https://github.com/federicotorrielli/zotero-metadata-hunter) | `enrich_item_metadata`（基于 DOI CSL-JSON + OpenAlex 填入字段）、`upgrade_preprints`（通过 OpenAlex 标题搜索升级已发布版本） | ✅ | — | | [zotero-doi-fix](https://github.com/pandaAIGC/zotero-doi-fix) | `find_doi`（标题相似性融合 + `mode:"repair"`：Handle-System 验证 → 替换为备份）、`extract_identifier_from_pdf` | ✅ | — | **PDF** - 参见 [比较](./docs/benchmarking/pdf-download.md) | 来源 | 集成到 | 状态 | TODO | | --- | --- | --- | --- | | [pdferret](https://github.com/urschrei/pdferret)、[zotero-scipdf](https://github.com/syt2/zotero-scipdf) | `manage_pdf_resolvers`（本地 `findPDFs.resolvers` 读取/写入）+ 灰色来源下载 | ✅ | 多镜像轮换；更强的 DOI 提取（scipdf 的 5 个正则表达式 + 附件扫描） | ### 3. 未集成，但可通过 `run_javascript` 调用（交互边界 + 路线图） 这些插件未合并到此插件中，但如果用户 **安装它们**，AI 代理可以通过 **`run_javascript`** 驱动它们 - 该功能在 Zotero 的特权上下文中运行，可以访问任何已安装插件的公开 API。当前边界和未来专用工具方向： | 插件 | 功能 | 当前代理边界 | TODO（专用工具） | | --- | --- | --- | --- | | [jasminum 茉莉花](https://github.com/l0o0/jasminum) | 中文元数据抓取（CNKI / 万方 / VIP） | ✅ 专用工具 **`fetch_chinese_metadata`**（v2.1.0）：资格分类 + 防挂卫士 | — | | [zotero-updateifsE 绿青蛙](https://github.com/redleafnew/zotero-updateifsE) | 影响因子 / JCR 和 CAS 四分位数 | 调用其 easyScholar 更新路径按项目通过 `run_javascript` | `update_journal_metrics(scope)` 工具 | | [zotero-format-metadata](https://github.com/northword/zotero-format-metadata) | 50+ 格式校验器，LTWA 期刊缩写 | ✅ 专用工具 **`lint_metadata`**（v2.1.0）：标准/显式规则超过 `Zotero.Linter.hooks.onLintInBatch`，未知 ID 被拒绝 | — | | [zotero-zotadata](https://github.com/ydeng11/zotero-zotadata) | 多源填充 + 多提供商 PDF 发现 | 调用其检索管道通过 `run_javascript` | `deep_enrich(itemKey)` 结合填充 + PDF 获取 | > `run_javascript` 是通用逃生口：任何已安装的插件在 `Zotero` 对象（或全局变量）上公开函数，可以被代理 **今天** 驱动。TODO 列是关于将最常用的交互提升为类型化的、干燥运行安全的 MCP 工具。