zotio

zotio est un outil en ligne de commande et un serveur MCP positionné comme une couche de confiance et d'automatisation pour les bibliothèques de références Zotero. Il cible les utilisateurs qui doivent opérer sur une bibliothèque à grande échelle plutôt que via l'interface graphique : trouver des PDF manquants, détecter les clés de citation en double avant soumission, exporter des annotations, synchroniser un coffre de notes, ou fournir un contexte borné à des agents IA. Architecture et accès aux données Les lectures sont locales : zotio communique avec l'API du bureau Zotero en cours d'exécution sur localhost et un miroir SQLite synchronisé, sans nécessiter de clé API et fonctionne hors ligne sur une copie synchronisée. Les écritures sont divisées selon l'intention. La création d'un nouvel élément avec pièces jointes privilégie le connecteur local du bureau (le même canal utilisé par le bouton « Enregistrer dans Zotero » du navigateur), tandis que les modifications de champs, suppressions, enrichissement, opérations sur les étiquettes, déplacements et création/mise à jour de collections passent par l'API Web de Zotero et nécessitent une clé configurée. Le chemin du connecteur est décrit comme une préférence, non une garantie : le routage automatique ne l'utilise que pour une bibliothèque personnelle avec le bureau en cours d'exécution, et bascule sinon vers l'API Web, tandis que les bibliothèques de groupe passent toujours par le cloud. Les services externes référencés pour l'enrichissement et l'import incluent CrossRef, OpenAlex, Semantic Scholar, Unpaywall et OpenCitations. Une commande doctor signale la connectivité, la fraîcheur du cache et la disponibilité de l'écriture en retour. Sécurité des écritures Toutes les commandes d'écriture partagent une même enveloppe de mutation. L'aperçu est la valeur par défaut ; --yes applique et --dry-run l'emporte toujours. Le mode agent définit des valeurs par défaut JSON et non interactives mais n'applique pas automatiquement les écritures. Des garde-fous limitent le rayon d'action : --max-changes vaut 500 par défaut (50 en mode agent), et les opérations irréversibles telles que la fusion, la suppression définitive et le vidage de la corbeille nécessitent un indicateur explicite --allow-destructive. Les écritures appliquées sont rejouées dans le miroir local afin qu'une lecture ultérieure voie la modification sans nouvelle synchronisation. Chaque exécution appliquée est enregistrée dans un journal en ajout seul, et journal undo inverse les opérations réversibles (renommages d'étiquettes, appartenance à une collection, créations) tout en refusant les fusions, suppressions et écrasements de champs. Santé de la bibliothèque et CI La commande phare de santé de la bibliothèque compose les vérifications existantes (conflits de clés de citation, doublons, métadonnées manquantes, dérive des étiquettes, pièces jointes cassées) en un seul rapport classé et typé par constat. Un indicateur --for sélectionne un préréglage : quick, citation, systematic-review, vault ou all. Les constats portent une recommended_action nommant la commande qui les corrige. La commande prend en charge le verrouillage CI avec --fail-on, se terminant par le code 11 lorsque le seuil n'est pas atteint, et --require-fresh, se terminant par le code 12 sur un miroir obsolète. Les vérifications nécessitant l'application de bureau deviennent des sauts explicites avec remèdes plutôt que de disparaître silencieusement, et un saut pertinent pour un garde-fou se termine par le code 9. Une option --badge génère un artefact JSON de point de terminaison shields.io. Une GitHub Action compagnon empaquette l'installation, la synchronisation, le verrouillage et la comparaison de référence. Autres capacités La vérification de rétractation valide les DOI par rapport aux données Retraction Watch de Crossref, couvrant les rétractations, les expressions de préoccupation et les corrections. L'analyse des lacunes de collection classe les articles fréquemment cités manquants dans une bibliothèque. La vérification bibliographique analyse les citations LaTeX ou pandoc et signale les clés inconnues ou ambiguës. L'audit des étiquettes regroupe les doublons de casse et de variantes avec des commandes de fusion prêtes à exécuter. Les statistiques de bibliothèque, les audits d'éléments, la détection de doublons et la détection de conflits de clés de citation sont inclus. Les fonctionnalités de lecture et de synthèse incluent des lots de résumé bornés pour le transfert vers un LLM (zotio lui-même n'appelle pas de modèle), l'export et la recherche d'annotations, un cycle de vie de liste de lecture, des modèles de notes, des liens profonds et un bilan annuel avec des cartes SVG partageables. L'enrichissement remplit les DOI, résumés et champs de citation manquants à partir de fournisseurs externes et joint des PDF en accès ouvert, en enregistrant la provenance dans le champ Extra. La vérification de prépublication met à niveau les enregistrements arXiv vers les DOI de revues publiées. Les options d'export incluent CSL-JSON, BibTeX, BibLaTeX, RIS et un instantané JSONL reprenable avec un fichier de verrouillage de contenu. Sync, watch et tail maintiennent le miroir à jour, et la dérive de schéma détecte les changements après les mises à niveau de Zotero. Flux d'import et de coffre L'import en masse passe par les étapes scan, resolve et apply avec un manifeste JSON modifiable comme point de contrôle de revue humaine. La synchronisation de coffre maintient un coffre Obsidian ou Logseq en phase avec Zotero dans les deux sens, en utilisant une région gérée et une région de prose utilisateur, avec une écriture en retour en avance rapide uniquement et des artefacts de conflit examinables plutôt que des fusions silencieuses. Intégration d'agent Un indicateur --agent fournit une sortie JSON, compacte et non interactive. Une commande capabilities expose un registre de commandes étiquetées par opération, sources de données, cible d'écriture, caractère destructif et préconditions. Une commande agent-context décrit le CLI, une commande which résout les requêtes en langage naturel vers des commandes, et les enveloppes et codes de sortie sont documentés comme des contrats stables. Un binaire de serveur MCP est distribué aux côtés du CLI. Distribution L'installation est disponible via Homebrew sur macOS et Linux, des paquets de publication GitHub pour deb, rpm et apk, et WinGet ou Scoop sur Windows. Le CLI, une compétence d'agent et le serveur MCP peuvent être installés indépendamment. Le projet est sous licence MIT et écrit en Go.