# Zotero Toolkit

Tools for [Zotero](https://www.zotero.org): MCP servers, Zotero plugins and agent
skills for reference management and systematic/scoping review workflows.

Built for real review work - screening decisions, exclusion logging, PRISMA record
accounting - rather than as a demo.

## What's here

| Component | Runs where | Status |
| --- | --- | --- |
| [`mcp/zotero-mcp-server`](mcp/zotero-mcp-server/) | Any MCP client, or as a standalone CLI | **v1.3.0** |
| [`plugins/pdf-file-attacher`](plugins/pdf-file-attacher/) (AutoAttach) | Inside the Zotero desktop app (`.xpi`, Zotero 7–10) | **v1.5.0** |
| [`agent-skills/`](agent-skills/) | Loaded by an AI agent | **3 skills** |
| [`core/`](core/) | Shared libraries | not yet needed |
| [`docs/`](docs/) | Cross-package documentation | in progress |

```
zotero-toolkit/
├── mcp/                      # MCP servers (npm workspaces)
│   └── zotero-mcp-server/    # 25 tools + 4 prompts over the Zotero Web API, plus a CLI
├── plugins/                  # Zotero .xpi add-ons, using Zotero's internal API
├── agent-skills/             # research workflows for AI agents (SKILL.md)
├── core/                     # shared libraries, once >1 package needs them
└── docs/                     # cross-package documentation
```

[**AutoAttach**](plugins/pdf-file-attacher/) matches downloaded PDFs to the items
you already have by reading what is inside each file — DOI, arXiv ID, embedded
metadata, first-page text — rather than comparing filenames. It also verifies
titles, abstracts, and document languages offline against attached PDFs, and
online against Crossref, OpenAlex, and Europe PMC (plus retraction screening).
Every match or repair carries the evidence it was made on, with filter tabs,
live search, and a side-by-side **Further Review Inspector** (`Inspect ▸`) so
nothing is written until you confirm:

[![The AutoAttach v1.5 review dialog: filter tabs, live search, score badges,
confidence bars, and close-call warnings](plugins/pdf-file-attacher/docs/screenshots/review-matches-v15.png)](plugins/pdf-file-attacher/)

[![The Further Review Inspector: side-by-side comparison of current Zotero
metadata, extracted PDF text preview, and proposed changes](plugins/pdf-file-attacher/docs/screenshots/deep-inspector.png)](plugins/pdf-file-attacher/)

[![Online DOI lookup against Crossref and OpenAlex with strict title, author,
and year corroboration](plugins/pdf-file-attacher/docs/screenshots/missing-dois.png)](plugins/pdf-file-attacher/)

It runs inside Zotero, and every command ends in that same reviewed dialog:

[![The review dialog open over the Zotero library
window](plugins/pdf-file-attacher/docs/screenshots/in-zotero.png)](plugins/pdf-file-attacher/)

[![The item context menu, with the online commands carrying a globe icon and an
Online label](plugins/pdf-file-attacher/docs/screenshots/item-menu.png)](plugins/pdf-file-attacher/)

Two different integration points, deliberately:

- **MCP servers** talk to the Zotero **Web API** over HTTPS. They work from any
  machine against your synced library and need no desktop app, but only see items
  that have synced.
- **Plugins** run **inside** Zotero using its internal API. They work offline and can
  touch local files and attachments, but must be installed in the app.

## Quick start

The MCP server is the finished piece. Requires **Node.js 18+**.

```bash
git clone https://github.com/adolinjonathan-bot/zotero-toolkit.git
cd zotero-toolkit
npm install
npm run build
npm run verify     # 11 checks, no credentials needed
```

Then follow [`mcp/zotero-mcp-server/README.md`](mcp/zotero-mcp-server/README.md) to
create a Zotero API key and connect a client - Claude Desktop, Claude Code, Cursor,
Zed, Continue, VS Code, LM Studio, or a local open-source model.

It also runs as a plain CLI with no AI involved at all:

```bash
node mcp/zotero-mcp-server/dist/cli.js search "youth employability" --limit 10
```

## Repository conventions

- `npm install` once at the root; workspaces cover `mcp/*` and `core/*`.
  `agent-skills/` is documentation, not code, and is deliberately excluded.
- `npm run build` and `npm run verify` fan out across every package.
- Build output (`dist/`, `build/`, `*.xpi`) is **not** committed. Plugin `.xpi`
  files ship as GitHub Release assets so each download traces to a source commit.
- Every package carries its own README; this file stays an index.

## Licence

MIT - see [LICENSE](LICENSE).

## Credits

Initial implementation generated with Claude, then debugged, hardened and tested
against a live research library.