# Données de travail → Cleyrop MCP

Serveur **MCP** pour interagir avec les **données de travail Cleyrop** via le
`cleyrop-sdk` : naviguer, rechercher, **lire le contenu d'un fichier pour le
requêter dans le chatbot**, et gérer fichiers/dossiers.

Packagé selon la convention des tools MCP de
[La Fabrique](https://cleyrop.gitbook.io/docs/la-fabrique/devspace) (même
structure que `tool-sharepoint` / `tool-excel`). S'appuie sur le
[cleyrop-sdk](https://cleyrop.gitbook.io/docs/support-and-ressources/references-techniques-api-sdk/sdk-cleyrop-sdk).

## Cas d'usage central

> *« Récupère le fichier X dans le projet Y et réponds à ma question dessus. »*

Le LLM localise le fichier (`list_projects` / `browse` / `search`), appelle
**`read_file`** qui télécharge le fichier et renvoie son **contenu texte**
(extrait selon le format), puis répond à partir de ce contenu.

## Tools exposés

### Lecture / navigation
| Tool | Rôle |
|------|------|
| `list_projects()` | Projets accessibles (id, nom, slug) |
| `browse(project, path?, folder_id?)` | Lister un projet / un dossier (fichiers + sous-dossiers) |
| `search(query, project?, item_type?, mode?)` | Rechercher (plein texte ou par nom) |
| `file_info(file_id? \| project+path)` | Métadonnées d'un fichier |
| `read_file(file_id? \| project+path, max_chars?)` | **Contenu texte** d'un fichier (txt/md/csv/json/xml…, .xlsx, .docx, .pdf) |

### Écriture / gestion
| Tool | Rôle |
|------|------|
| `create_folder(project, path)` | Créer un dossier (arborescence incluse) |
| `save_text_file(project, name, content, folder_path?)` | Écrire un contenu texte comme fichier |
| `rename_file` / `move_file` / `copy_file` / `delete_file` | Opérations fichier (delete = corbeille, ou `permanent`) |
| `rename_folder` / `delete_folder` | Opérations dossier |

### Corbeille
| Tool | Rôle |
|------|------|
| `list_trash(project)` / `restore_file(file_id)` / `empty_trash(project)` | Gestion de la corbeille |

### Divers
| Tool | Rôle |
|------|------|
| `diagnose()` | Diagnostiquer l'authentification / l'accès (sans fuite de secret) |

> **Désigner un fichier** : par son `file_id`, **ou** par `project` (id/slug) +
> `path` (chemin S3-style, ex. `/dossier/fichier.csv`).

## Extraction de contenu (`read_file`)

| Format | Méthode |
|--------|---------|
| txt, md, csv, json, xml, html, yaml, log, code… | décodage UTF-8 |
| `.xlsx` | openpyxl → feuilles en lignes tabulées |
| `.docx` | python-docx → paragraphes + tableaux |
| `.pdf` | pypdf → texte par page |
| binaire (image, archive…) | non extractible → métadonnées seules |

Le texte est tronqué à `max_chars` (défaut 200 000) pour ne pas saturer le
contexte du modèle.

## Authentification

Identique au pattern de production Cleyrop (cf. `tool-excel`) : **priorité au
compte de service** (`CLEYROP_CLIENT_ID` + `CLEYROP_CLIENT_SECRET`, injecté par
La Fabrique), sinon `CLEYROP_TOKEN`. Résolution d'URL in-cluster par défaut
(FQDN `.svc.cluster.local`), ou `CLEYROP_DOMAIN`, ou
`CLEYROP_API_URL`/`CLEYROP_KEYCLOAK_URL`. Voir `.env.example` et `diagnose()`.

> Les droits effectifs (lecture/écriture) dépendent du compte de service et de
> ses rôles sur le projet. `diagnose()` confirme l'authentification ; un échec
> d'écriture (403) indique un manque de droits côté projet.

## Installation / tests

```bash
cd /home/cleyrop/tool-donnees-travail
uv sync
PYTHONPATH=src python -m pytest tests/ -q
```

## Lancer

```bash
donnees-travail-cleyrop-mcp        # stdio (local)
python main.py                     # HTTP streamable-http (conteneur)
```

## Build (La Fabrique)

Le [Dockerfile](Dockerfile) suit la convention Cleyrop : base `astral/uv`,
`uv sync`, serveur HTTP sur `MCP_PORT` (8000, endpoint `/mcp`). `cleyrop-sdk`
est résolu via l'index privé `cleyrop-sdk-gitlab`
(`UV_INDEX_CLEYROP_SDK_GITLAB_USERNAME`/`_PASSWORD` injectées au build).

| Variable d'instance | Portée | Valeur |
|---------------------|--------|--------|
| `MCP_PORT` | globale | `8000` |
| *(client credentials)* | globale | injectées par La Fabrique |