Zotero MCP 开发者指南：从零源码构建与调试 Zotero 插件（含热重载）

Zotero MCP 是一个运行在 Zotero 内的插件，通过 MCP 协议让 Claude、ChatGPT 等 AI 助手直接检索和管理你的文献库。本文带你从零完成 Zotero MCP 插件的源码构建与调试：安装 Node.js 开发环境、构建.xpi插件包、用npm run start开启热重载即时调试，再到单元测试、日志排查与版本发布，一套完整的 Zotero 插件开发工作流，零基础也能照做。

开发环境准备：搭建 Zotero 插件开发依赖

在开始源码构建之前，先确认本地已具备以下 4 项依赖（版本要求以 CLAUDE.md 与中文文档为准）：

然后克隆仓库并安装依赖：

git clone https://gitcode.com/gh_mirrors/zote/zotero-mcp cd zotero-mcp/zotero-mcp-plugin npm install

💡 插件代码全部位于zotero-mcp-plugin/子目录，后续所有命令都在该目录下执行。

源码结构速览：读懂 Zotero MCP 插件的 5 个核心目录

构建之前先花 2 分钟了解代码布局，调试时会频繁在这些目录间跳转：

整体架构非常简洁：AI 客户端 ↔ Streamable HTTP ↔ Zotero 插件（内置 MCP 服务器），不再需要独立的服务器进程。

一键构建：从零生成可安装的 .xpi 插件包

生产构建只有一条命令（脚本定义见 package.json）：

npm run build

它做了两件事：

1. 调用zotero-plugin build，把src/经 esbuild 打包并连同addon/静态资源一起打成.scaffold/build/zotero-mcp-plugin.xpi；
2. 执行tsc --noEmit做 TypeScript 类型检查，构建失败会先报类型错误。

构建完成后，在 Zotero 中通过工具 → 附加组件（齿轮图标 → 从文件安装附加组件）加载该.xpi，重启 Zotero 即生效。

提交代码前建议顺手跑一遍格式与静态检查：

npm run lint:check # prettier 格式 + eslint 检查 npm run lint:fix # 自动修复

热重载开发模式：npm run start 让代码改动即时生效

日常调试不用反复打包安装，项目内置了热重载（hot reload）开发服务器：

npm run start

即zotero-plugin serve，它会自动启动一个 Zotero 实例并加载插件；保存代码后自动重新编译并热重载，无需手动重启。整个热重载链路是这样工作的：

1. bootstrap.js 在 Zotero 启动时注册 chrome 资源，并加载编译产物content/scripts/zotero-mcp-plugin.js；
2. 入口 src/index.ts 创建全局Addon实例（定义于 src/addon.ts），并把ztoolkit挂载为全局工具；
3. src/hooks.ts 的onStartup()依次完成：等待 Zotero 初始化 → 初始化多语言 → 按首选项启动 HTTP 服务器（默认端口23120）→ 注册条目变化监听 → 标记initialized = true。

调试三件套：

• 📝日志：项目统一使用ztoolkit.log()输出日志（带[MCP Plugin]前缀），在工具 → 开发者 → 错误控制台中即可看到完整的启动/关闭生命周期日志（STARTUP BEGIN…SHUTDOWN COMPLETE）；
• 🩺心跳探测：插件内置健康检查端点，浏览器访问http://127.0.0.1:23120/ping返回pong即表示服务器存活；
• 🔁偏好热更新：hooks.ts 监听了端口与开关两项偏好，在首选项 → Zotero MCP Plugin中修改端口后服务器会自动重启，改配置同样免重启。

测试与排查：单元测试、集成测试与常见错误定位

跑测试

npm run test:unit # 纯 Node 环境下的 mocha 单元测试 npm run test # 集成测试：由 zotero-plugin test 启动 Zotero 加载插件

单元测试示例 test/httpRequestReader.test.ts 用FakeReader模拟分片字节流，专门验证多字节 UTF-8 被截断在 chunk 边界时的解析正确性；test/writeOperations.test.ts 则覆盖写入操作的边界场景。新增功能时仿照这两个文件补充用例即可。

高频故障速查

发布流程：版本升级与自动更新配置

本地验证通过后，发布走语义化版本 + 自动更新清单的流程：

1. 升版本：npm run release（正式版）或npm run release:beta（beta 版），会自动执行npm version并打 tag；
2. 生成更新清单：scripts/prepare-release.js 依据package.json的version生成 update.json（正式版）或update-beta.json（beta），内容即上文截图所示的版本 + 下载链接结构；
3. 构建产物：.xpi重命名为zotero-mcp-plugin-X.Y.Z.xpi后与update.json一并作为 Release 资源上传；
4. 用户侧：Zotero 定期请求 manifest.json 中update_url指向的地址，比对版本后提示自动更新。完整机制与手工验证方法见 AUTO_UPDATE_GUIDE.md。

⚠️ 注意版本要同步：package.json、update.json、README 徽章三处版本号必须一致，否则自动更新会静默失效。

小结：Zotero MCP 插件开发的完整闭环

回顾一下这条从零开始的开发链路，每一步都已给出对应命令：

1. git clone+npm install—— 搭好开发环境；
2. npm run build—— 生成.xpi并做类型检查；
3. npm run start—— 热重载调试，改动保存即生效，配合错误控制台读日志；
4. npm run test:unit/npm run test—— 单元测试与集成测试双保险；
5. npm run release—— 升版本、生成update.json，用户端自动更新。

掌握这套流程后，无论是给 Zotero MCP 插件加一个 MCP 工具、调整首选项界面，还是修复端口与索引相关的 Bug，都能在几分钟内完成“改码 → 重载 → 验证”的完整调试闭环。