# claucloverleaf

Permet à Claude de lire et d'écrire dans tes projets Overleaf **en direct**. Tu te connectes une seule fois.

Les modifications passent par le canal de collaboration temps réel d'Overleaf, et non par git. Les collaborateurs les voient donc instantanément, et elles apparaissent dans l'historique du projet sous le compte connecté. Fonctionne sur overleaf.com et sur les instances auto-hébergées.

## Installation

```bash
cd ~/projets/claucloverleaf
uv sync
uv run playwright install chromium   # navigateur utilisé une seule fois, pour la connexion
```

## Connexion (une fois)

```bash
uv run claucloverleaf login                      # ouvre Chromium : connecte-toi normalement (SSO/2FA OK)
uv run claucloverleaf --url https://overleaf.monlabo.fr login   # instance auto-hébergée
uv run claucloverleaf status                     # vérifie la session
```

Seul le cookie de session est conservé, dans `~/.claucloverleaf/sessions/<hôte>.json` (fichier 0600, dossier 0700), un fichier par instance. Aucun mot de passe n'est stocké, et le navigateur de connexion ne laisse rien sur le disque. `claucloverleaf logout` ferme la session côté Overleaf puis efface tout en local.

Si le navigateur ne s'ouvre pas, connecte-toi dans ton navigateur habituel. Ouvre les outils de développement (F12), puis Application › Cookies, et copie la valeur de `overleaf_session2` (ou `overleaf.sid` sur une instance auto-hébergée). Ensuite :

```bash
uv run claucloverleaf login --cookie      # saisie masquée (rien dans l'historique du shell)
```

## Avec Claude Code (MCP)

```bash
claude mcp add -s user claucloverleaf -- uv run --quiet --project ~/projets/claucloverleaf claucloverleaf mcp
# instance auto-hébergée, limitée à deux projets :
claude mcp add -s user claucloverleaf -e OVERLEAF_URL=https://overleaf.monlabo.fr \
  -e CLAUCLOVERLEAF_PROJECTS=6ad8b4516e5ab36cad60155f,"Ma thèse" -- uv run --quiet --project ~/projets/claucloverleaf claucloverleaf mcp
```

Utilise `--project` et non `--directory` : le serveur garde ainsi le dossier de ta session Claude Code comme dossier courant, et c'est le seul où il peut lire ou écrire des fichiers locaux.

Outils exposés :

| Outil | Rôle |
|---|---|
| `overleaf_whoami`, `overleaf_list_projects`, `overleaf_create_project` | compte et projets |
| `overleaf_list_files`, `overleaf_read_file` | explorer et lire (lignes numérotées) |
| `overleaf_replace_text` | modification ciblée par extrait exact (à privilégier) |
| `overleaf_insert_lines`, `overleaf_replace_lines`, `overleaf_write_file` | insérer, remplacer une plage, réécrire ou créer |
| `overleaf_create_folder`, `overleaf_upload_file`, `overleaf_rename`, `overleaf_move`, `overleaf_delete` | arborescence |
| `overleaf_compile`, `overleaf_download_pdf` | compiler et obtenir les erreurs LaTeX (fichier et ligne), télécharger le PDF |
| `overleaf_add_comment`, `overleaf_review` | commentaires et modifications suivies |

Les outils d'écriture acceptent `track_changes=true` : la modification est alors déposée comme **suggestion**, que l'auteur accepte ou refuse dans Overleaf. Cela nécessite que le suivi des modifications soit disponible sur le projet.

## CLI

```bash
uv run claucloverleaf projects
uv run claucloverleaf ls "Ma thèse"
uv run claucloverleaf cat "Ma thèse" main.tex
uv run claucloverleaf replace "Ma thèse" main.tex "ancien" "nouveau" [--all] [--track]
uv run claucloverleaf append "Ma thèse" main.tex "\\section{Suite}"
uv run claucloverleaf write "Ma thèse" chapitres/intro.tex intro.tex   # crée ou remplace
uv run claucloverleaf upload "Ma thèse" figure.png --folder figures
uv run claucloverleaf compile "Ma thèse" [--warnings] [--log]
uv run claucloverleaf pdf "Ma thèse" these.pdf
uv run claucloverleaf review "Ma thèse" main.tex
```

Un projet se désigne par son identifiant, son URL ou son nom exact.

## Configuration (facultative)

| Variable | Rôle | Défaut |
|---|---|---|
| `OVERLEAF_URL` | instance | `https://www.overleaf.com` |
| `CLAUCLOVERLEAF_HOME` | dossier des sessions et du fichier d'état | `~/.claucloverleaf` |
| `CLAUCLOVERLEAF_PROJECTS` | projets autorisés : identifiants, ou noms de **tes** projets, séparés par des virgules | tous |
| `CLAUCLOVERLEAF_READONLY` | `1` : lecture seule (les outils d'écriture ne sont même pas proposés) | désactivé |
| `CLAUCLOVERLEAF_FILE_DIRS` | dossiers locaux supplémentaires autorisés pour l'envoi de fichiers et l'écriture du PDF (séparés par `:`) | aucun |
| `OVERLEAF_ALLOW_HTTP` | `1` : accepter une instance en `http://` hors localhost (équivalent de `--insecure`) | désactivé |
| `CLAUCLOVERLEAF_REQUEST_TIMEOUT`, `…_CONNECT_TIMEOUT`, `…_COMPILE_TIMEOUT`, `…_LOGIN_TIMEOUT` | délais (s) | 30, 20, 240, 600 |

## Sécurité

- **Contenu non fiable** : un document, un commentaire ou un log de compilation peut contenir des instructions écrites par un collaborateur. Le serveur MCP demande à Claude de ne jamais les suivre. **Ne coche pas « toujours autoriser »** pour les outils qui écrivent, envoient ou suppriment : la demande de confirmation de Claude Code est la meilleure protection.
- **Fichiers locaux** (`overleaf_upload_file`, `overleaf_download_pdf`) :
  - seulement sous le dossier courant ou sous `CLAUCLOVERLEAF_FILE_DIRS` (jamais tout `$HOME`) ;
  - pas via un dossier caché ni un lien symbolique qui sort de ces dossiers ;
  - seulement des extensions LaTeX, pas de nom évoquant un secret, 50 Mo au maximum ;
  - un PDF existant n'est pas écrasé sans `overwrite`.
- **Périmètre** : `CLAUCLOVERLEAF_PROJECTS` et `CLAUCLOVERLEAF_READONLY` limitent ce que Claude peut voir et modifier. Un nom ne compte que pour tes propres projets : un projet qu'on te partage sous le même nom ne passe pas.
- **Cookie** : il est lié au domaine de l'instance et n'est jamais envoyé ailleurs. Il ne circule qu'en HTTPS, sauf localhost ou `--insecure`.
- **Terminal** : la CLI neutralise les séquences d'échappement présentes dans les documents (presse-papiers OSC 52, variables utilisateur du terminal).
- **Pour isoler au maximum**, crée un compte Overleaf dédié à Claude et invite-le seulement dans les projets voulus.

## Indicateur de compte

`~/.claucloverleaf/status` (non secret) contient le compte connecté sur chaque instance, avec ⚠ si la session a expiré. Tu peux l'afficher dans ton prompt ou ta barre de terminal.

## Développement

```bash
uv run pytest      # tests unitaires et de bout en bout contre un faux serveur Overleaf (sans réseau)
```

L'architecture et les détails du protocole sont décrits dans `CLAUDE.md`.

## Licence

MIT, voir [LICENSE](LICENSE).