# CiteCheck MCP

Servidor MCP que confere cada citação de um manuscrito (LaTeX ou Markdown, em português ou inglês) contra o
trecho correspondente na fonte citada. Ele também sugere reescritas e as aplica no `.tex` com validação e backup.

**O servidor não chama nenhuma API de LLM.** O trabalho determinístico fica com ele:
- parsing do LaTeX e do BibTeX;
- busca e extração dos PDFs;
- busca lexical;
- verificação literal das citações;
- checagem da bibliografia;
- edição segura dos arquivos.

O julgamento (se o trecho sustenta a afirmação, como reescrever a frase) fica com o modelo do cliente que você
já usa (Claude Code ou Claude Desktop), dentro da sua assinatura.

```
manuscrito.tex ─► frases + \cite ─► .bib ─► PDFs (pasta local, Zotero, arXiv, OA) ─► texto com página
                                                                                         │
 relatório HTML ◄── veredito (com citação literal verificada) ◄── modelo do host ◄── busca BM25
```

## Instalação

Requer o [uv](https://docs.astral.sh/uv/) (`brew install uv`), que já instala o Python 3.12.

```bash
git clone https://github.com/lucasgris/citecheck.git
cd citecheck
uv sync
uv run pytest        # 19 testes, offline
```

### Claude Code

```bash
claude mcp add citecheck -s user -- uv run --directory /caminho/para/citecheck citecheck-mcp
```

### Claude Desktop

Em `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "citecheck": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "--directory", "/caminho/para/citecheck", "citecheck-mcp"],
      "env": { "CITECHECK_EMAIL": "seu@email" }
    }
  }
}
```

Use em `command` o caminho que `which uv` mostra na sua máquina.

### Variáveis de ambiente (todas opcionais)

| Variável | Para quê |
|---|---|
| `CITECHECK_EMAIL` | Entra no "polite pool" do Crossref e habilita o Unpaywall (mais PDFs de acesso aberto). |
| `SEMANTIC_SCHOLAR_API_KEY` | Sem a chave, o Semantic Scholar costuma responder 429. A chave é gratuita e melhora a detecção de "preprint com versão publicada" e a busca de PDFs. |
| `ZOTERO_STORAGE` | Pasta de anexos do Zotero (padrão `~/Zotero/storage`). |
| `CITECHECK_MANUSCRIPT` | Abre um manuscrito automaticamente ao iniciar. |

## Uso

No Claude Code, peça em linguagem natural ou use os prompts prontos:

- `/mcp__citecheck__audit` com o caminho do `main.tex`: faz a auditoria completa e gera o relatório.
- `/mcp__citecheck__rewrite`: sugere reescritas para as afirmações com problema, em `pt` ou `en`, mostra o diff e
  só aplica depois que você aprovar.
- `/mcp__citecheck__write_with_evidence`: redige um parágrafo usando apenas trechos verificados das fontes
  escolhidas e o insere no `.tex`.

Exemplos de pedidos:

> Audita as citações do capítulo 2 de ~/tese/main.tex e me mostra só os problemas.

> Reescreve em inglês as frases marcadas como "partial", mantendo os \cite.

Todo o estado fica em `.citecheck/`, ao lado do manuscrito: SQLite, cache dos PDFs, backups e `report.html`.
Essa pasta tem um `.gitignore` próprio, porque PDFs de terceiros não devem ir para o repositório.

## Ferramentas

| Ferramenta | O que faz |
|---|---|
| `open_project` | Lê o manuscrito (segue `\input`/`\include`), o `.bib` e os vereditos anteriores. |
| `list_claims` / `get_claim` | Lista as frases citadas com o status; mostra o detalhe com o LaTeX bruto e o contexto. |
| `fetch_sources` / `attach_pdf` | Localiza os PDFs (campo `file` do .bib, pastas `pdfs/` e `papers/`, Zotero, arXiv, Semantic Scholar, OpenAlex, Unpaywall), extrai o texto com página e confere se o título bate. |
| `find_evidence` / `read_source` | Busca BM25 com números como âncora; leitura por página. |
| `verify_quote` | Confere se o trecho está literalmente no PDF (tolerante a ligaduras, hifenização e aspas). |
| `record_verdict` | Grava o veredito; **rejeita** citações que não estão no PDF. |
| `scan_uncited` | Encontra frases que parecem precisar de citação (heurística EN/PT). |
| `check_bibliography` | Chaves ausentes, entradas não usadas, duplicatas, DOI ausente (com sugestão), metadados divergentes do Crossref, retratações e preprint com versão publicada. |
| `propose_rewrite` / `propose_insertion` | Valida a reescrita (`{}` e `$` balanceados, chaves de citação preservadas e existentes no .bib, caracteres especiais, idioma) sem escrever nada. |
| `apply_rewrite` / `revert_rewrite` / `discard_rewrite` / `list_rewrites` | Escrita atômica que preserva a codificação (UTF-8 ou latin-1) e o CRLF, com backup. |
| `export_report` | Relatório HTML (pt/en) com vereditos, trechos e páginas. |
| `audit_status` | Progresso da auditoria. |

## Suporte a LaTeX

Funciona bem via MCP, porque o servidor lê e escreve os arquivos `.tex` direto no disco:

- `\cite`, `\citep`, `\citet`, `\parencite`, `\textcite`, `\autocite`, `\cites{a}{b}` e variantes com `*` e
  argumentos opcionais; `\nocite`; `thebibliography`/`\bibitem`; `\bibliography` e `\addbibresource`.
- Ignora comentários, o preâmbulo, equações, tabelas, `verbatim` e afins; trata legendas e `\item` como
  unidades separadas.
- Converte acentos LaTeX (`\c{c}`, `\~a`, `{\'e}`) para comparar o texto, mas escreve de volta exatamente o que
  foi aprovado. Avisa quando a reescrita usa acentos Unicode num arquivo que usa macros.
- Não compila o documento. Para conferir a compilação depois de aplicar reescritas, rode `latexmk`.

## Limitações conhecidas

- PDFs escaneados não têm camada de texto. Rode `ocrmypdf` antes.
- Tabelas e figuras são extraídas como texto corrido; afirmações sustentadas só por uma figura precisam de
  verificação manual.
- A busca é lexical. Para uma afirmação em português e uma fonte em inglês, o modelo passa os termos em inglês
  em `query` (os prompts já instruem isso). Os números servem de âncora entre idiomas.
- Ainda não lê `.docx` (é o próximo formato a suportar).

## Licença

MIT. Veja [LICENSE](LICENSE).