herbertkokholm/cite-caddy

A reference-library bridge for AI assistants — a standalone, remote MCP
server.
> Independent, unofficial project. Not affiliated with, endorsed by, or
> sponsored by the Corporation for Digital Scholarship (Zotero) —
> see Zotero's trademark policy.
> Built on the Zotero Web API; today's backend is Zotero, but the name and
> tool surface are meant to support others later.
Cite Caddy gives full read/write access to a Zotero library — search, add,
tag, update, delete, and move items; create, rename, and delete
collections; upload/download attachments and read their extracted full
text; read and write item notes; manage tags, trash, and saved searches
library-wide; and look up Zotero's own item-type/field schema. 39 tools
total — see Tools below for the full list.
Why this exists
Read-only tools that match findings against a Zotero library (e.g. by
DOI/arXiv ID) can safely stop at reporting — they never need to write
anything back. This project goes further on purpose: full CRUD against a
Zotero library, including delete and move, so that tagging, adding, and
cleaning up items can be automated too.
That's a deliberate scope choice, and it comes with a real risk: any write
that changes an existing item's *key* (delete, move to another library,
"clean library" reset) breaks Word documents that cite it via the Zotero
Word plugin's live field codes — see "Key safety" below before touching
delete/move.
Key safety (read this before implementing delete/move)
Any Zotero item cited in a Word document via the Zotero Word plugin is
referenced by that item's **key**, embedded in a live field code. Operations
that preserve an item's key (create, update fields, add/remove tags, add
notes) are safe. Operations that don't (delete, and library-to-library move,
which Zotero implements as delete+recreate) will break those citations
silently — the Word document won't error, it'll just show stale/broken
field text next time someone updates fields or opens Zotero the next time.
Full CRUD was chosen deliberately for this project despite that risk. When
implementing delete/move tools:
- Make the destructive intent obvious in the tool name and docstring (an MCP
client's model reads both before calling), not just in this README.
- Consider requiring the caller to pass back the item's current Zotero
version (optimistic concurrency) so a delete/update can't silently clobber
a change made concurrently from the Zotero desktop app or another client.
- A dry-run / confirmation step for delete is worth considering, but is an
implementation decision for whoever builds that tool, not decided here.
Idempotency
delete_item_permanently, delete_collection, delete_tag,
delete_saved_search, move_item_to_different_library, and
update_publication_status all accept an optional idempotency_key. Pass
the same opaque string when retrying a call after a lost or ambiguous
response (e.g. a network timeout) and the *original* outcome — success or
error — is replayed instead of running the operation against Zotero again.
Reusing a key for a call with different arguments raises an error instead of
silently returning the old result, so it's safe to generate one key per
logical request and reuse it freely on retries of that same request.
This matters most for move_item_to_different_library: it recreates the
item in the target library, then deletes it from the source. If the create
succeeds but the delete then fails, a bare retry would redo the whole thing
— since the source item's version hasn't changed — creating a *second*
duplicate in the target library. With idempotency_key, the retry replays
the cached failure (and its "clean up manually" guidance) instead of
touching Zotero again.
The cache is in-memory per server process (per onboarded tenant in HTTP
mode), with a 24h TTL — it survives retries within that window, not across a
redeploy/restart.
Configuration
**stdio mode** (local, single-user — no $PORT): the library to connect to
comes from env vars.
**HTTP mode** (remote, multi-tenant — $PORT set): there's no single
configured library — each caller brings their own Zotero Library ID/Type/API