zotero-local-mcp-bridge

<div align="center"> # Zotero 本地 MCP 桥接 使用 Zotero 插件托管的 MCP 端点，让本地代理安全地管理本地 Zotero 库。 <p align="center"> <a href="LICENSE"><img alt="许可证" src="https://img.shields.io/badge/许可证-AGPL--3.0--or--later-blue.svg"></a> <a href="src/zotero-plugin/manifest.json"><img alt="版本" src="https://img.shields.io/badge/版本-0.1.56-4c78a8.svg"></a> <a href="https://www.zotero.org/"><img alt="Zotero" src="https://img.shields.io/badge/Zotero-9.x-cc2936.svg"></a> <a href="#工作原理"><img alt="MCP" src="https://img.shields.io/badge/MCP插件托管-2e7d32.svg"></a> <a href="#范围"><img alt="本地优先" src="https://img.shields.io/badge/本地优先-仅限本地循环访问-2e7d32.svg"></a> <a href="https://github.com/PhoenixChenLu/zotero-local-mcp-bridge/pulls"><img alt="欢迎PR" src="https://img.shields.io/badge/PRs欢迎-brightgreen.svg"></a> <a href="skills/zotero-local-mcp-bridge/SKILL.md"><img alt="Codex 准备就绪" src="https://img.shields.io/badge/Codex准备就绪-111827.svg"></a> <a href="skills/zotero-local-mcp-bridge/SKILL.md"><img alt="OpenCode 准备就绪" src="https://img.shields.io/badge/OpenCode准备就绪-111827.svg"></a> <a href="skills/zotero-local-mcp-bridge/SKILL.md"><img alt="Claude Code 准备就绪" src="https://img.shields.io/badge/Claude%20Code准备就绪-111827.svg"></a> </p> AGPL-3.0-or-later · 插件版本 0.1.56 · Zotero 9.x · 插件托管 MCP · 本地循环访问 [简体中文](README.zh-CN.md) · [功能概述](#功能概述) · [不具备功能](#不具备功能) · [范围](#范围) · [工作原理](#工作原理) · [快速开始](#快速开始) · [示例](#示例) · [支持作者](#支持作者) · [许可证](#许可证) </div> --- ## ✨ 功能概述 Zotero 本地 MCP 桥接允许具备 MCP 功能的代理通过 Zotero 本身管理本地 Zotero 库。它不是绕过 Zotero 的数据库脚本，而是运行在 Zotero 插件内的本地 MCP 入口。 | 领域 | 功能 | |---|---| | 📚 项目和集合 | 读取、搜索、创建和编辑项目；管理字段、创建者、标签、注释、集合和集合成员 | | 📎 附件 | 添加、移动、重命名和检查附件；调用 Zotero 内置的附件重命名逻辑 | | 📝 注释和引用 | 读取、创建和更新支持的 PDF 注释；通过 Zotero 格式化引用和参考文献 | | 🔁 导入和导出 | 导入和导出 BibTeX、RIS 和 CSL JSON | | 🔎 搜索 | 使用基本搜索、高级搜索和保存的搜索读取/更新工作流 | | 🛡️ 安全工作流 | 为所有写入强制执行预运行；支持审批、审计、文件级备份和撤销 | | 🧩 重复项 | 查找重复项并运行受控的重复项合并流程 | > [!NOTE] > 写入操作不会立即执行。代理首先接收预运行计划、警告、受影响的目标和确认数据。在审批模式下，执行必须等待用户审批。 --- ## 🚫 不具备功能 | 不支持的功能 | 原因 | |---|---| | 管理在线 Zotero 库 | 该项目不通过 Zotero Web API 或管理远程 Zotero 账户 | | 使用 `ZOTERO_API_KEY` | 该项目不请求、读取或存储 Zotero API 密钥 | | 直接写入 `zotero.sqlite` | 更改应通过 Zotero 内部 API | | 暴露任意 JavaScript 评估 | 普通管理必须来自插件命令表 | | 管理组库 | 当前公共范围仅涵盖本地用户库 | | 永久删除或清空回收站 | 当前删除类似流程使用 Zotero 回收站或受控合并，而不是不可恢复的擦除 | | 直接删除现有附件文件 | 附件文件操作必须尊重备份/撤销和安全边界 | --- ## 📍 范围 该插件设计用于 Zotero 桌面版和本地 MCP 客户端在同一台机器上。MCP 端点在 Zotero 的本地连接器服务器上注册，并且仅使用本地循环访问。 | 项目 | 当前设置 | |---|---| | 运行位置 | 在 Zotero 插件内 | | 端点 | `http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp` | | 库范围 | 本地用户库 | | 写入路径 | Zotero 内部 API | | 网络模型 | 本地循环访问，无云写入 | | 审计和备份 | 必须位于 Zotero 配置文件、Zotero 数据目录、链接附件根目录和附件目录之外 | 运行模式在 `设置 -> Zotero 本地 MCP 桥接`中配置： | 模式 | 行为 | |---|---| | `readonly` | 阻止所有写入 | | `askforapprove` | 代理在预运行后请求用户审批 | | `yolo` | 普通写入操作可能会在计划允许时自动执行；高风险或未来不可恢复的操作仍需要明确确认 | --- ## ⚙️ 工作原理 ```text 具备 MCP 功能的代理 -> MCP 工具调用 -> Zotero 本地连接器服务器 -> Zotero 本地 MCP 桥接插件端点 -> 插件命令表 -> Zotero 内部 API ``` MCP 端点在 Zotero 插件内托管： ```text http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp ``` 无需启动单独的 Node、Python 或侧车 MCP 进程。启动 Zotero 会启动插件端点。关闭 Zotero 会停止它。发布版本会公开 MCP 工具，而不是旧的私有命令端点。 --- ## 🚀 快速开始 ### 1. 下载发布文件 从 [GitHub Releases](https://github.com/PhoenixChenLu/zotero-local-mcp-bridge/releases) 下载： | 文件 | 用途 | |---|---| | `zotero-local-mcp-bridge.xpi` | Zotero 插件 | | 英语技能 | 适用于英语代理 | | 中文技能 | 适用于中文代理 | ### 2. 安装 Zotero 插件 打开 Zotero 插件管理器： ```text 工具 -> 插件 ``` 将 `zotero-local-mcp-bridge.xpi` 拖入插件管理器窗口，在提示时确认安装，然后重启 Zotero。 ### 3. 选择运行模式 打开： ```text 设置 -> Zotero 本地 MCP 桥接 ``` 首次使用时，从 `readonly` 或 `askforapprove` 开始。只有在了解预运行、审批、审计和备份行为后，才使用 `yolo`。 ### 4. 连接 MCP 客户端 配置您的具备 MCP 功能的代理以通过 Streamable HTTP / HTTP JSON-RPC 连接： ```text http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp ``` ### 5. 安装匹配的技能 | 语言 | 技能 | |---|---| | 英语 | [skills/zotero-local-mcp-bridge/SKILL.md](skills/zotero-local-mcp-bridge/SKILL.md) | | 中文 | [skills/zotero-local-mcp-bridge-zh-cn/SKILL.md](skills/zotero-local-mcp-bridge-zh-cn/SKILL.md) | 告诉代理通过 Zotero 本地 MCP 桥接使用 Zotero。当需要审批时，代理应简要描述待处理的操作并等待用户审批。 --- ## 🧪 示例 | 请求代理 | 预期行为 | |---|---| | 列出我的 Zotero 集合树 | 只读查询，无写入确认 | | 在“当前项目”下创建“阅读队列”子集合 | 先进行预运行，然后请求审批 | | 将此 PDF 附件添加到此项目 | 解析项目和文件路径，然后进行附件操作的预运行 | | 将选定项目导出为 BibTeX | 只读导出，无写入确认 | | 使用选定样式格式化参考文献 | 使用 Zotero 的引用格式化程序 | 在审批模式下，单个写入操作应通过代理交互如下： ```text 我即将创建名为“阅读队列”的子集合，位于“当前项目”下。是否批准执行？ ``` 多个待处理操作使用编号表格，以便用户可以批准所有操作或仅批准选定的编号： ```text 以下操作需要审批： | 编号 | 操作 | |---:|---| | 1 | 将子集合“临时”从“旧项目”移动到 Zotero 回收站 | | 2 | 合并重复项目“Smith 2024”和“Smith 2024 副本” | | 3 | 将“Zotero MCP 设计笔记”添加到“当前项目 / 阅读队列” | ``` 用户可以回复“批准所有”，或回复“批准 1 和 3，拒绝 2”。 --- ## ❤️ 支持作者 <div align="center"> <a id="ko-fi-support" href="https://ko-fi.com/phoenixchen"><img alt="Ko-fi" src="https://img.shields.io/badge/Ko--fi-支持作者-ff5e5b?logo=kofi&logoColor=white"></a> <a id="afdian-support" href="https://afdian.com/a/PhoenixChen"><img alt="Afdian" src="https://img.shields.io/badge/Afdian-支持作者-946ce6"></a> </div> --- ## 📄 许可证 Zotero 本地 MCP 桥接在 AGPL-3.0-or-later 下获得许可。参见 [LICENSE](LICENSE)。