# 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.2.0** |
| [`plugins/pdf-file-attacher`](plugins/pdf-file-attacher/) (AutoAttach) | Inside the Zotero desktop app (`.xpi`) | **v1.0.1** |
| [`agent-skills/`](agent-skills/) | Loaded by an AI agent | planned |
| [`core/`](core/) | Shared libraries | not yet needed |
| [`docs/`](docs/) | Cross-package documentation | in progress |

```
zotero-toolkit/
├── mcp/                      # MCP servers (npm workspaces)
│   └── zotero-mcp-server/    # 24 tools + 3 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
├── 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. Every match carries
the evidence it was made on, and nothing is written until you confirm:

[![The AutoAttach review dialog: 171 PDFs scanned against 268 items, 146 matches,
each row showing its score and the evidence behind
it](plugins/pdf-file-attacher/docs/screenshots/review-matches.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     # 7 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.