# zotero-brain-slim

Minimal Zotero MCP server（stdio）：库检索、十源论文发现、全文证据语义检索（Sciverse）、多级全文获取瀑布（OA PDF / 出版社订阅 XML）、Zotero 导入。
不做解析与向量化——只负责「找到、下载、入库」。

## 工具面（7 个）

| 工具 | 说明 |
|---|---|
| `search_zotero_library` | 检索 Zotero 库（关键词/标题/DOI） |
| `search_sciverse_evidence` | 【事实问答首选】Sciverse 语义检索全文证据片段（OpenDataLab，4.5 亿记录 + 3000 万 AI-Ready 全文；返回可引用的原文 chunk + doc_id/偏移/页码，`expand=true` 扩读原文上下文）。科研问答/高可信度作答优先用它；发现与下载文献才用 `discover_papers` |
| `discover_papers` | 十源搜索（综合 5 + 分域 5），附在库标记 |
| `download_paper` | 9 级双格式瀑布全文获取（XML 趟优先、PDF 趟补档）：缓存（任一格式命中即短路）→ XML 趟 Elsevier（订阅 XML，需 key）→ Springer（OA JATS XML，需 key）→ PDF 趟 Unpaywall → arXiv → S2 → CORE → OpenAlex → Sci-Hub（默认关闭；XML 已命中时 PDF 补档趟剔除该级）；全败返回结构化 `no_pdf` + `landing_page`（Unpaywall → OpenAlex → doi.org 兜底）+ 人工指引（含接入校园网/机构 VPN 解锁订阅源提示） |
| `import_to_zotero` | 建条目 + linked_file 附件（PDF/XML 均留本地）+ 入 Collection |
| `list_collections` | 列 Collection（可选带条目数） |
| `create_collection` | 创建 Collection（同名复用） |

### 数据源分域建议（Agent 路由）

**先分流**：日常问答 / 基于事实与原文证据的作答 → `search_sciverse_evidence`（直接拿全文证据片段）；发现文献 / 下载导入 → `discover_papers`（只回元数据/摘要）。

`discover_papers` 的 `sources` 参数按提问方向只选 2-3 个相关源，避免十源全量轮询：

| 提问方向 | 建议源 |
|---|---|
| 综合 / 材料 / 工程 / 计算机 | `openalex` + `semantic_scholar`（补充 `crossref` 核对元数据；配了 token 可加 `sciverse`） |
| 电子 / 电气 / 计算机 · IEEE 系 | `ieee`（元数据级，需 key）+ `openalex` |
| 物理 / 数学 预印本 | `arxiv` + `openalex` |
| 天文 · 天体物理 · 空间科学 | `ads`（需 token）+ `arxiv` |
| 生物医学 · 生命科学 | `europepmc` + `openalex` |
| 开放获取全文 | `doaj` + `openalex`（OA 链接直给） |
| 欧盟项目 / 数据集关联 | `openaire` |

不传 `sources` 默认 `sciverse/openalex/arxiv/crossref/semantic_scholar` 五综合源（sciverse 未配 token 时自动降级跳过）。

## 配置（全部经环境变量 / MCP env 传入）

| 变量 | 必填 | 说明 |
|---|---|---|
| `ZOTERO_MODE` | 否 | `auto`（默认）/ `local` / `web`。auto：配了 Web 凭据走 Web（读写全功能），无凭据回落本地（只读） |
| `ZOTERO_USER_ID` / `ZOTERO_API_KEY` | auto/web 模式需要 | Zotero Web API 凭据（本地模式可免） |
| `ZOTERO_LIBRARY_TYPE` | 否 | `user`（默认）或 `group` |
| `ZOTERO_LOCAL` | 否 | 兼容旧配置：`true` 等价于 `ZOTERO_MODE=local` |
| `UNPAYWALL_EMAIL` | 否 | Unpaywall 认证邮箱（[unpaywall.org](https://unpaywall.org/) 免注册，填真实邮箱即可）。**默认占位值**（`zotero-brain-slim@example.com`）**会使该下载级静默失效** |
| `OPENALEX_API_KEY` | 否 | OpenAlex key（[openalex.org](https://openalex.org/users/me) 注册即得；不配走 mailto 礼貌池也能用） |
| `CORE_API_KEY` | 否 | CORE 下载级：[core.ac.uk access API](https://core.ac.uk/services/api) 申请（Academic key 免费；**30 天轮换**，到期 dashboard 点 Renew） |
| `ELSEVIER_API_KEY` | 否 | Elsevier ScienceDirect 全文 XML 级（级 7）：[dev.elsevier.com](https://dev.elsevier.com/) 自助注册（TDM click-through）。个人 key 不进仓库不分发；机构订阅按**来源 IP** 判定——校园网 / 机构 VPN 环境下带机构权限可取订阅内容，无权限时该级优雅跳过（提示接入机构网络），不阻塞后续级 |
| `SPRINGER_NATURE_API_KEY` | 否 | Springer Nature OA 全文 XML 级（JATS，瀑布 XML 趟主力）：[dev.springernature.com](https://dev.springernature.com/) 自助申请（免费 key 即取 OA 全文，无订阅/IP 限制） |
| `IEEE_API_KEY` | 否 | IEEE Xplore 检索源（十源之一，元数据级）：[developer.ieee.org](https://developer.ieee.org/) 申请（即时发 key，可能 waiting 审批 1-2 天） |
| `ADS_API_TOKEN` | 否 | NASA ADS 源（天文/天体物理）；[免费申请](https://ui.adsabs.harvard.edu/user/settings/token) |
| `SCIVERSE_API_TOKEN` | 否 | Sciverse 证据检索与检索源（`search_sciverse_evidence` 工具 + 十源之一）：[sciverse.space](https://sciverse.space) 控制台免费申请；不配则对应功能优雅降级 |
| `SCIHUB_ENABLED` | 否 | Sci-Hub 级开关（默认关闭；设 `true` 开启。下载瀑布最后一级，前面各级命中——含 XML 趟命中——不会走到它） |
| `PROXY_URL` | 否 | 应用级 HTTP 代理（如 `http://127.0.0.1:7890`），留空则按 env 代理 → 系统代理 → 直连自动选择 |

也支持同目录 `.env` 文件（本地调试用）。

## 快速上手：从申请 key 到接入 Better SageRead

### 第 0 步：什么都不配也能用（本地模式，3 分钟）

1. Zotero 桌面端保持运行，并开启本地 API 开关（见下方「本地模式前置条件」）；
2. 在 Better SageRead：**AI 中心 → MCP 服务器 → 添加服务器**，按下表填写：

| 表单字段 | 填什么 |
|---|---|
| 类型 | **stdio**（「请求头」是 HTTP 型服务器的字段，stdio 不需要也不会显示） |
| 名称 | `zotero-brain`（任意） |
| 命令 | `uvx` |
| 参数（每行一个） | `--from` ／ `git+https://github.com/Feplus2/zotero-brain-slim` ／ `zotero-brain-slim` |
| 环境变量 | 此步可全空 |

保存后卡片转绿即通。本地模式可搜库/查重/九源检索；**写入类操作**（导入条目、建 Collection）需要 Zotero Web key（[zotero.org/settings/keys](https://www.zotero.org/settings/keys) 创建，env 填 `ZOTERO_USER_ID` + `ZOTERO_API_KEY`）。

本地开发运行（不走 uvx 拉远端）：命令填 `uv`，参数三行 `--directory` ／ `F:\...\zotero-brain-slim`（仓库绝对路径）／ `run mcp_server.py`。

### 第 1 步：按需申请出版社 key（全部免费，且都**不锁 IP**）

| key | 申请入口 | 用途 | 备注 |
|---|---|---|---|
| `SPRINGER_NATURE_API_KEY` | [dev.springernature.com](https://dev.springernature.com/) | SN OA 全文 **JATS XML**（双格式瀑布 XML 趟主力） | 自助即时；免费 key 即取 OA 全文 |
| `ELSEVIER_API_KEY` | [dev.elsevier.com](https://dev.elsevier.com/) | ScienceDirect 全文 XML（订阅刊） | 自助即时；**订阅全文按来源 IP 判机构权限**（校园网/VPN 才放行，元数据与 OA 不受限） |
| `IEEE_API_KEY` | [developer.ieee.org](https://developer.ieee.org/) | IEEE 检索源（元数据级） | 审批可能 waiting 1-2 天 |
| `CORE_API_KEY` | [core.ac.uk/services/api](https://core.ac.uk/services/api) | CORE OA 下载级 | 30 天轮换，到期点 Renew |
| `OPENALEX_API_KEY` | [openalex.org/users/me](https://openalex.org/users/me) | OpenAlex 检索/下载级 | 不配也能用（mailto 礼貌池） |
| `UNPAYWALL_EMAIL` | 无需申请 | Unpaywall 下载级 | env 填**真实邮箱**即可（占位值=该级静默失效） |
| `ADS_API_TOKEN` | [ADS 设置页](https://ui.adsabs.harvard.edu/user/settings/token) | 天文/天体物理检索源 | 免费即时 |
| `SCIVERSE_API_TOKEN` | [sciverse.space](https://sciverse.space) 控制台 | Sciverse 全文证据检索（问答首选）+ 综合检索源 | 免费 starter quota，超额 429 |

申请到的 key 逐条填进上一步表单的「环境变量」（或 `.env` 文件）。**一个都不配也成立**——瀑布只是少了对应级，OA 链路照常工作。

### 第 2 步：网络口径（重要）

- 所有 key 均无 IP 锁，在哪都能调；**唯一例外**是 Elsevier 的订阅刊全文（按请求来源 IP 判定机构订阅，挂校园网/全隧道 VPN 后自动解锁）。
- 若配置了 `PROXY_URL`：zbs 全部出网流量走它，**代理进程没开会整体假死**（各端点报 404/401 假象）。排障口诀：先查代理，再怀疑 key。
- 「浏览市场」装的 npm 型 MCP（如 `sageread-mcp`）与本仓无关——zbs 是 Python 仓，经 uvx/本地 uv 运行。

## 本地模式前置条件（两个常见坑）

本地模式免 key、不限流，适合只读场景（搜库/查重）；写入操作必须走 Web API。使用本地模式需同时满足：

1. **Zotero 桌面端必须正在运行**——本地 API 由 Zotero 进程内的 HTTP server 提供，
   未启动时连接直接失败；
2. **必须手动开启本地 API 开关**：Zotero 菜单 **编辑 → 设置 → 高级 → 杂项**，
   勾选 **「允许其他应用程序通过本地 API 通信」**（Allow other applications to
   communicate with Zotero），否则请求返回 `403 - Local API is not enabled`。

**重要：Zotero 本地 API 是只读的**（`POST/PATCH/DELETE` 一律 400
"Endpoint does not support method"，Zotero 的硬性设计）。因此凡涉及写入
（建文件夹、导入条目、挂附件）必须走 Web API + key。

`ZOTERO_MODE=auto`（默认）的策略：**配置了 Web 凭据则整体走 Web**（读写全功能，
避免"本地读、Web 写"的数据不一致观感）；未配置凭据且本地 API 可用则回落本地
只读模式（搜库/查重可用，写入会报明确指引）。

## 运行

<!-- 发布时替换为 Feplus2 -->

```bash
# uv / uvx（推荐）
uvx --from git+https://github.com/Feplus2/zotero-brain-slim zotero-brain-slim

# 本地开发
pip install -r requirements.txt
python mcp_server.py
```

作为 MCP server 注册（stdio，适用于 Claude Desktop 等通用 MCP 客户端）：

```json
{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/Feplus2/zotero-brain-slim", "zotero-brain-slim"],
  "env": {
    "ZOTERO_USER_ID": "…",
    "ZOTERO_API_KEY": "…"
  }
}
```

## 在 Better SageRead 中使用

本服务是 Better SageRead 文献工作流的一环：在 SageRead 的 MCP 管理器中注册为
stdio MCP server 即可。SageRead 的 env 支持 `{{secret:NAME}}` 占位符——spawn
进程前由 Rust 侧从系统凭据管理器取出同名条目并替换注入，凭据不写入配置文件：

```json
{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/Feplus2/zotero-brain-slim", "zotero-brain-slim"],
  "env": {
    "ZOTERO_USER_ID": "{{secret:ZOTERO_USER_ID}}",
    "ZOTERO_API_KEY": "{{secret:ZOTERO_API_KEY}}",
    "UNPAYWALL_EMAIL": "{{secret:UNPAYWALL_EMAIL}}"
  }
}
```

其余可选变量（`ZOTERO_MODE`、`PROXY_URL`、`SCIHUB_ENABLED` 等）按需添加，
明文值与 `{{secret:...}}` 占位符可混用。

## 代理与网络环境

本服务全部流量为 HTTPS API 请求，**应用级 HTTP 代理即可，无需 TUN**。代理选择优先级：
`PROXY_URL` 显式配置 > 宿主注入的 `HTTP_PROXY`/`HTTPS_PROXY`（httpx trust_env 自动遵循）
> 操作系统代理回退（Windows 注册表 / macOS 系统设置；兜底「宿主只注入 `NO_PROXY`
导致 trust_env 读不到系统代理」的场景）> 直连。
境外源不可达时，下载瀑布会返回人工下载指引。

## 免责声明

Sci-Hub 级默认关闭（作为下载瀑布最后一级，前面各级命中——含 XML 趟——时不会走到它）。需要时可设 `SCIHUB_ENABLED=true` 显式开启；开启前请了解你所在地区的法律法规，使用者自行承担责任
（Keep the laws of your locality in mind）。本项目仅提供检索/下载/入库的工程实现，
不对任何下载源的合法性背书。

出版社官方 API 级（Elsevier）走 [TDM 政策](https://www.elsevier.com/about/policies-and-standards/text-and-data-mining)
允许的正式接口，个人非商业研究用途；机构订阅按来源 IP 判定（校园网 / 学校 VPN），
key 个人持有不进仓库不分发。使用图书馆电子资源请遵守所在机构规定（禁止连续、
系统、过量下载；禁止凭证自动登录；禁止私设代理供校外访问）。

## 贡献

PR 欢迎：修 bug / 加下载源 / 改工具面。请保持「不做解析与向量化」的边界。