Skip to content

## Implement: biblio zotero pull — read items + PDFs from Zotero via API Phase

Implement: biblio zotero pull — read items + PDFs from Zotero via API

Phase 2 of the pool ecosystem spec (docs/specs/biblio/pool-ecosystem.md).

What

Add biblio zotero pull command and MCP tool that pulls items and PDFs from a Zotero library (personal or group) into a biblio workspace (project or pool).

Dependencies

  • pyzotero as optional dependency: pip install "biblio-tools[zotero]"
  • Zotero API key configured in biblio.yml or env var

Behavior

# Pull a collection into personal pool
biblio zotero pull --collection "Oscillations" --target pool

# Pull from group library into lab pool
biblio zotero pull --group 67890 --collection "Core" --target lab-pool

# Pull everything new since last sync
biblio zotero pull --incremental

Implementation

  1. Zotero client wrapper — packages/biblio/src/biblio/zotero_sync.py
  2. Thin wrapper around pyzotero
  3. pull_collection(collection_name, target_root) → list of pulled items
  4. pull_items(item_keys, target_root) → download metadata + attachments
  5. Map Zotero item types → BibTeX entry types (use zotero-schema as reference)
  6. Download PDF attachments → bib/articles/{citekey}/{citekey}.pdf

  7. Write pulled items as BibTeX → bib/srcbib/zotero-{collection}.bib

  8. Incremental sync — packages/biblio/src/biblio/zotero_state.py

  9. Track last sync version per collection in .projio/biblio/zotero-sync.yml
  10. Use Zotero's since parameter to only fetch changed items

  11. Store item version map for conflict detection

  12. Config — add to biblio.yml: 

    zotero:
  api_key_env: ZOTERO_API_KEY
  library_type: user      # user | group
  library_id: "12345"
  sync_target: pool       # pool | local

  13. MCP tool: 

    def biblio_zotero_pull(
    collection: str = "",
    group_id: str = "",
    incremental: bool = True,
    target: str = "pool",  # "pool" | "local"
) -> dict  # {"pulled": N, "skipped": N, "errors": [...]}

  14. CLI: biblio zotero pull [--collection NAME] [--group ID] [--target pool|local]

Key references (indexed in RAG)

  • .projio/codio/mirrors/urschrei--pyzotero/ — pyzotero API surface
  • .projio/codio/mirrors/zotero--zotero-schema/ — Zotero data model, item type mapping
  • .projio/codio/mirrors/zotero--translators/ — how Zotero generates BibTeX (for field mapping)
  • packages/biblio/src/biblio/ingest.py — existing ingest pipeline to follow
  • packages/biblio/src/biblio/pool.py — pool write patterns