zotio

zotio é uma ferramenta de linha de comando e servidor MCP posicionada como uma camada de confiança e automação para bibliotecas de referência do Zotero. Destina-se a usuários que precisam operar em uma biblioteca em escala, em vez de pela GUI do desktop: encontrar PDFs ausentes, detectar chaves de citação duplicadas antes da submissão, exportar anotações, sincronizar um vault de notas ou fornecer contexto limitado a agentes de IA. Arquitetura e acesso a dados As leituras são locais: zotio se comunica com a API do Zotero desktop em execução no localhost e com um espelho SQLite sincronizado, sem exigir chave de API e funcionando offline contra uma cópia sincronizada. As gravações são divididas por intenção. Criar um novo item com anexos prefere o conector local do desktop (o mesmo canal usado pelo botão "Save to Zotero" do navegador), enquanto edições de campos, exclusões, enriquecimento, operações de tags, movimentações e criação/atualização de coleções são encaminhadas para a Zotero Web API e exigem uma chave configurada. O caminho do conector é descrito como preferência, não garantia: o roteamento automático o usa apenas para uma biblioteca pessoal com o desktop em execução, recorrendo à Web API caso contrário, e bibliotecas de grupo sempre vão para a nuvem. Serviços externos referenciados para enriquecimento e importação incluem CrossRef, OpenAlex, Semantic Scholar, Unpaywall e OpenCitations. Um comando doctor relata conectividade, atualidade do cache e se a gravação de volta está disponível. Segurança de gravação Todos os comandos de gravação compartilham um único envelope de mutação. A pré-visualização é o padrão; --yes aplica e --dry-run sempre prevalece. O modo agente define padrões JSON e não interativos, mas não aplica gravações automaticamente. Gates limitam o raio de impacto: --max-changes tem padrão 500 (50 no modo agente), e operações irreversíveis como merge, exclusão permanente e esvaziar lixeira exigem uma flag explícita --allow-destructive. As gravações aplicadas são reproduzidas no espelho local para que uma leitura seguinte veja a mudança sem outra sincronização. Cada execução aplicada é registrada em um journal somente-anexação, e o undo do journal reverte operações reversíveis (renomeações de tags, associação a coleções, criações), recusando merges, exclusões e sobrescritas de campos. Saúde da biblioteca e CI O comando principal de saúde da biblioteca compõe verificações existentes (conflitos de citekey, duplicatas, metadados ausentes, desvio de tags, anexos quebrados) em um único relatório classificado e tipado por achados. Uma flag --for seleciona um preset: quick, citation, systematic-review, vault ou all. Os achados carregam um recommended_action nomeando o comando que os corrige. O comando suporta gating de CI com --fail-on, saindo com 11 quando o limite não é atingido, e --require-fresh, saindo com 12 em um espelho desatualizado. Verificações que precisam do app desktop tornam-se skips explícitos com soluções, em vez de desaparecerem silenciosamente, e um skip relevante para o gate sai com 9. Uma opção --badge gera um artefato JSON de endpoint shields.io. Uma GitHub Action complementar empacota instalação, sincronização, gate e diff de baseline. Outros recursos A verificação de retratações valida DOIs contra os dados do Retraction Watch do Crossref, cobrindo retratações, expressões de preocupação e correções. A análise de lacunas de coleção classifica artigos frequentemente citados ausentes de uma biblioteca. A verificação de bibliografia analisa citações LaTeX ou pandoc e sinaliza chaves desconhecidas ou ambíguas. A auditoria de tags agrupa duplicatas de maiúsculas/minúsculas e variantes com comandos de merge prontos para executar. Estatísticas de biblioteca, auditorias de itens, detecção de duplicatas e detecção de conflitos de citekey estão incluídas. Recursos de leitura e síntese incluem pacotes de resumo limitados para handoff a LLM (o próprio zotio não chama um modelo), exportação e busca de anotações, um ciclo de vida de lista de leitura, modelos de notas, deep links e um ano em revisão com cartões SVG compartilháveis. O enriquecimento preenche DOIs, resumos e campos de citação ausentes a partir de provedores externos e anexa PDFs de acesso aberto, registrando proveniência no campo Extra. A verificação de preprints atualiza registros arXiv para DOIs de periódicos publicados. As opções de exportação incluem CSL-JSON, BibTeX, BibLaTeX, RIS e um snapshot JSONL retomável com um lockfile de conteúdo. Sync, watch e tail mantêm o espelho atualizado, e o schema drift detecta mudanças após atualizações do Zotero. Fluxos de importação e vault A importação em massa passa por estágios de scan, resolve e apply com um manifesto JSON editável como ponto de revisão humana. A sincronização de vault mantém um vault Obsidian ou Logseq em passo com o Zotero em ambas as direções, usando uma região gerenciada e uma região de prosa do usuário, com gravação de volta apenas fast-forward e artefatos de conflito revisáveis em vez de merges silenciosos. Integração com agentes Uma flag --agent fornece saída JSON, compacta e não interativa. Um comando capabilities expõe um registro de comandos marcados com operação, fontes de dados, destino de gravação, destrutividade e pré-condições. Um comando agent-context descreve a CLI, um comando which resolve consultas em linguagem natural para comandos, e envelopes e códigos de saída são documentados como contratos estáveis. Um binário de servidor MCP é distribuído junto com a CLI. Distribuição A instalação está disponível via Homebrew no macOS e Linux, pacotes de release do GitHub para deb, rpm e apk, e WinGet ou Scoop no Windows. A CLI, uma skill de agente e o servidor MCP podem ser instalados independentemente. O projeto é licenciado sob MIT e escrito em Go.