Génération Excel → Cleyrop MCP

Serveur MCP qui génère des fichiers Excel (.xlsx) mis en forme à partir d'une demande utilisateur et les dépose dans les données de travail d'un projet Cleyrop (via cleyrop-sdk).

POC inspiré de la note interne « Génération de documents », packagé selon la convention des tools MCP de La Fabrique (même structure que tool-sharepoint).

Principe : séparer contenu et mise en forme

Le LLM ne produit jamais de mise en forme : il produit du contenu structuré, et un moteur de rendu distinct applique le style depuis un thème.

LLM ──> Contenu structuré (WorkbookSpec) ──> Moteur de rendu (openpyxl) ──> Thème ──> .xlsx
                                                                                        │
                                                          cleyrop-sdk.upload_file()  ──▶  Données de travail (projet Cleyrop)

Avantages : on change de thème sans toucher au prompt, on teste contenu et rendu séparément, et le même contenu pourrait alimenter d'autres formats plus tard. Bibliothèque : openpyxl (recommandée dans la note).

Tools exposés

Tool	Rôle
generate_excel(spec, project=None, cleyrop_folder=None, user=None)	Génère le .xlsx. Sans project : renvoie le fichier en ressource téléchargeable (blob xlsx). Avec project : tente le dépôt dans les données de travail (nécessite des droits d'écriture).
cleyrop_list_projects()	Lister les projets Cleyrop (id / slug) pour le paramètre project
cleyrop_diagnose()	Diagnostiquer l'authentification Cleyrop (sans fuite de secret)
get_excel_schema()	JSON Schema complet de la WorkbookSpec attendue

Téléchargement vs dépôt. Les tokens personnels Cleyrop sont en lecture seule : ils ne permettent pas d'écrire dans un projet. Le mode par défaut (sans project) renvoie donc le fichier en téléchargement. Le dépôt (project) ne réussit qu'avec un compte de service disposant des droits d'écriture (client_credentials injectés par La Fabrique).

Déploiement 100 % interne (cas Cleyrop). Si le tool n'a pas d'URL publique (image buildée et déployée sur la plateforme, connexions chat→tool internes), un lien de téléchargement servi par le tool n'est pas joignable depuis le navigateur de l'utilisateur. La livraison se fait alors par dépôt dans un projet : définis EXCEL_MCP_DEFAULT_PROJECT (ou CLEYROP_PROJECT_SLUG) et le fichier est déposé dans les données de travail, où l'utilisateur le télécharge depuis l'UI Projets. Le dépôt exige un compte de service avec droits d'écriture (vérifie avec cleyrop_diagnose).

Ressource MCP lisible (sans URL). generate_excel joint aussi le fichier comme ressource MCP (ResourceLink vers excel://download/{token}, + blob embarqué). Un client qui sait lire les ressources peut récupérer le fichier via la connexion MCP elle-même (resources/read), sans aucune URL publique. Dépend du support côté client (panneau ressources / pièces jointes).

Lien de téléchargement HTTP (si URL publique). Le serveur expose aussi une route GET /download/{token}. À n'utiliser que si le tool est exposé publiquement : renseigne alors EXCEL_MCP_PUBLIC_URL.

Capacités de rendu

Multi-feuilles · titre · entêtes stylées · colonnes typées (text/number/integer/currency/percent/date/datetime) · formats de nombre auto ou personnalisés · largeurs auto · zébrage · volet figé · filtres · ligne de totaux (sum/avg/count/min/max via formules Excel) · mise en forme conditionnelle (color_scale/data_bar/greater_than/less_than) · graphiques natifs (bar/line/pie) · thèmes (cleyrop, default, minimal).

Architecture

Fichier	Rôle
src/excel_mcp/models.py	Schéma du contenu (Pydantic) : classeur → feuilles → colonnes typées → lignes
src/excel_mcp/themes.py	Thèmes de mise en forme (couleurs, polices)
src/excel_mcp/renderer.py	Moteur de rendu : spec → openpyxl.Workbook
src/excel_mcp/cleyrop_io.py	Wrapper cleyrop-sdk (dépôt dans les données de travail)
src/excel_mcp/storage.py	Nommage {timestamp}_{user}_{type}_{slug}.xlsx + stockage local (fallback)
src/excel_mcp/server.py	Serveur MCP (FastMCP) exposant les tools
main.py	Point d'entrée conteneur (transport HTTP streamable-http)

---

1. Configuration côté Cleyrop

Le client cleyrop-sdk est construit dans src/excel_mcp/cleyrop_io.py selon le pattern de production des tools/apps Cleyrop. Deux modes d'authentification, par ordre de priorité :

Priorité	Mode	Variables	Comportement
1	Compte de service	CLEYROP_CLIENT_ID + CLEYROP_CLIENT_SECRET	Flux client_credentials. Identité injectée par La Fabrique au déploiement (rien à mettre dans le code — cf. Assistant_Contrat). Prioritaire si présent.
2	Token pré-obtenu	CLEYROP_TOKEN	Token de service ou personnel, utilisé tel quel (Bearer), sans login. Utilisé seulement si aucun client_secret n'est présent.

⚠️ Le compte de service est prioritaire sur CLEYROP_TOKEN : un token résiduel ou invalide ne peut donc pas masquer les client_credentials injectés par la plateforme. Si tu veux forcer l'usage d'un token personnel, ne fournis pas de client_secret.

Les CLEYROP_CLIENT_ID / CLEYROP_CLIENT_SECRET ne sont jamais stockés dans le dépôt : ils sont injectés par La Fabrique au niveau de l'instance (le .env d'Assistant_Contrat ne les contient pas non plus). Le code se contente de les lire via os.getenv.

Résolution des URL (auto-détectée) : in-cluster par défaut (FQDN apisix-gateway.<namespace>.svc.cluster.local, CLEYROP_NAMESPACE), ou externe via CLEYROP_DOMAIN, ou override explicite via CLEYROP_API_URL + CLEYROP_KEYCLOAK_URL. Voir .env.example.

Dans un Tool/App de La Fabrique, ces variables sont normalement injectées automatiquement. Détails : doc cleyrop-sdk.

Le package cleyrop-sdk est privé (registre GitLab) : l'installation nécessite UV_INDEX_CLEYROP_SDK_GITLAB_USERNAME / ..._PASSWORD (injectées au build).

2. Installation (DevSpace)

cd /home/cleyrop/tool-excel
uv venv && source .venv/bin/activate

# cleyrop-sdk vient d'un registre privé GitLab :
export UV_INDEX_CLEYROP_SDK_GITLAB_USERNAME=...
export UV_INDEX_CLEYROP_SDK_GITLAB_PASSWORD=...
uv sync

Copie .env.example → .env si besoin de surcharger des variables.

3. Build de l'image (Docker / La Fabrique)

Le Dockerfile suit la convention des tools MCP Cleyrop : base astral/uv, uv sync, serveur exposé en HTTP (streamable-http) sur le port MCP_PORT (défaut 8000, endpoint /mcp).

cleyrop-sdk est résolu par uv via l'index cleyrop-sdk-gitlab déclaré dans pyproject.toml ; uv s'authentifie avec les variables UV_INDEX_CLEYROP_SDK_GITLAB_USERNAME / _PASSWORD injectées par l'environnement de build Cleyrop — aucun secret à passer au build.

# build local (hors Cleyrop) : exporter d'abord les credentials du registre
export UV_INDEX_CLEYROP_SDK_GITLAB_USERNAME=...
export UV_INDEX_CLEYROP_SDK_GITLAB_PASSWORD=...
docker build -t excel-cleyrop-mcp .
docker run --rm -p 8000:8000 --env-file .env excel-cleyrop-mcp

Dans La Fabrique : Registre interne → Créer une image → Dépôt interne → dépôt tool-excel, branche v1, chemin du Dockerfile Dockerfile.

Variables d'environnement de l'instance (Cleyrop)

Variable	Portée	Valeur
MCP_PORT	globale	8000 (= « port exposé » de l'instance)
MCP_HOST	globale (option)	0.0.0.0
MCP_TRANSPORT	globale (option)	streamable-http
EXCEL_MCP_DEFAULT_PROJECT	globale (recommandé en interne)	Projet Cleyrop où déposer par défaut (id/slug) quand aucun project n'est passé. CLEYROP_PROJECT_SLUG accepté en alias.
EXCEL_MCP_PUBLIC_URL	globale (si URL publique)	URL publique du tool (sans /mcp), pour les liens de téléchargement. Inutile en déploiement 100 % interne.
(client credentials cleyrop-sdk)	globale	injectées par La Fabrique (sinon .env)

4. Usage local (client MCP de bureau, stdio)

Pour tester sans déploiement, le serveur tourne aussi en stdio via la commande excel-cleyrop-mcp :

{
  "mcpServers": {
    "excel-cleyrop": {
      "command": "/home/cleyrop/tool-excel/.venv/bin/excel-cleyrop-mcp",
      "env": { "EXCEL_MCP_EXPORT_DIR": "~/.excel-mcp/exports" }
    }
  }
}

Sans paramètre project, generate_excel sauvegarde le fichier localement (EXCEL_MCP_EXPORT_DIR) — pratique pour tester le rendu sans projet Cleyrop.

Exemple d'usage (depuis un client MCP)

1. cleyrop_list_projects() → récupère l'id/slug du projet.
2. « fais-moi un tableau Excel des ventes T1 par région avec totaux et un graphique, dépose-le dans le projet X » → le LLM construit la WorkbookSpec et appelle generate_excel(spec, project="X", cleyrop_folder="exports/2026").

Voir examples/example_spec.json pour une spec complète (devise, pourcentages, dates, totaux, mise en forme conditionnelle, graphique).

Tests

PYTHONPATH=src python -m pytest tests/ -q

Tests de non-régression du moteur de rendu (contenu, formats, formules, nommage).

Feuille de route

• Pré-visualisation : convertir le .xlsx en aperçu (cf. note : XLSX→PDF via Gotenberg, déjà utilisé pour le flux DOCX).
• Templates XLSX versionnés : lire un classeur modèle (entêtes/styles nommés) plutôt que tout générer from scratch — openpyxl le permet.
• Génération incrémentale pour les gros classeurs (plan → données → validation → assemblage).