zotero-mcp-dsh

Readme

# zotero-mcp-dsh

**DeepSeek Harness (DSH) 插件**：把本地 Zotero 文献库接入 DSH，让模型在会话中
直接检索文献、读取文献基本信息和 PDF 全文、导出 BibTeX，用于构造 LaTeX
参考文献库并在 tex 中插入 `\cite{}`。

模型侧新增工具（`mcp__zotero__*`）：

| 工具 | 功能 |
|---|---|
| `zotero_search` | 按关键词/集合/年份搜索文献，返回 itemKey、citekey、标题、作者、年份、期刊、DOI |
| `zotero_get_item` | 按 itemKey 取单条文献完整元数据（摘要、关键词、附件列表） |
| `zotero_get_fulltext` | 读取文献 PDF 全文（Zotero 全文索引），`maxChars` 控制长度 |
| `zotero_export_bibtex` | 按查询/集合/itemKeys 导出 Better BibTeX 风格 BibTeX 文本（含 citekey） |
| `zotero_list_collections` | 列出文献库全部集合（分类） |

## 原理

- 这是一个 **DSH bundle**：npm 包格式，`package.json` 声明
  `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`，通过 pnpm 从
  GitHub 安装到 DSH profile。
- `cordis.patch.yml` 注册一个 `@deepseek-ai/dsh-mcp-client` 插件实例（stdio
  transport），spawn 包内的 `server.mjs`。
- `server.mjs` 是零依赖 MCP 服务器（Node ≥ 18），通过 Zotero 桌面端本地
  HTTP API（`http://127.0.0.1:23119`，**只读、无需 API key**）工作。
- 安装后作为 profile 的 bundle 层加载；profile 的 `cordis.patch.yml` 变更会
  被 HMR 热加载，**新增/升级 bundle 后需重启 DSH 生效**。

## 安装

前置条件：本机 Zotero 桌面端已打开（本地 API 默认开启）。建议安装
[Better BibTeX](https://github.com/retorquere/zotero-better-bibtex) 以获得
稳定 citekey（非必需）。

从 GitHub 安装：

```sh
dsh plugin --profile web add github:LiJunfeng000000000000/zotero-mcp-dsh
```

或指定 tag/branch（tag 发布后可用）：

```sh
dsh plugin --profile web add github:LiJunfeng000000000000/zotero-mcp-dsh#v0.1.0
```

安装完成后**重启 DSH**，模型工具列表即出现 `mcp__zotero__*`。

## 写作工作流

1. **找文献**：`mcp__zotero__zotero_search`（如 `collection: "节理"`、
   `query: "numerical manifold"`），从结果挑选合适的文献。
2. **核对内容**：对关键文献用 `zotero_get_fulltext` 读 PDF 全文，确认方法、
   公式、结论与正文一致。
3. **构造 .bib**：用 `zotero_export_bibtex` 拿 BibTeX 文本，写入
   `docs/latex/references.bib` 等目标库。
4. **插入引用**：在正文相应句子后写 `\cite{citekey}`，按
   XeLaTeX—BibTeX—XeLaTeX—XeLaTeX 顺序编译。

## 卸载

```sh
dsh plugin --profile web remove zotero-mcp-dsh
```

## 开发

```sh
# 本地直接测试 MCP 服务器（不经 DSH）
node server.mjs
# 向 stdin 发送 MCP JSON-RPC 消息即可
```

## 说明与边界

- MCP 服务器**只读**：不会修改 Zotero 库；BibTeX 文本由模型写入 .bib 文件
  （文件写入走 DSH 沙箱审计）。
- PDF 全文依赖 Zotero 已建立全文索引；未索引的文献返回提示（可在 Zotero 中
  右键"重新索引"）。
- 集合搜索时，无 citekey 的 PDF 附件条目会被跳过（它们不是可引用的文献条目）。

## License

MIT