---
name: drawio
description: "Créer et modifier des schémas draw.io (.drawio) sur le VPS : diagrammes, flowchart, architecture, séquence, classe, ERD, réseau, maquette/wireframe, mindmap, BPMN… via MCP (open_drawio_xml/csv/mermaid) ou fichiers persistants + exports PNG/SVG/PDF (CLI drawio-cli). Utiliser quand l'utilisateur demande un schéma/diagramme ou mentionne draw.io/.drawio, ou quand un export image d'un schéma est nécessaire."
---

# Draw.io — schémas (MCP + CLI local)

## Outillage (VPS, vérifié 2026-11-03)

| Élément | Valeur |
|---|---|
| Serveur MCP | `drawio` (npm `@drawio/mcp` v1.10.1, stdio) — tools : `open_drawio_xml`, `open_drawio_csv`, `open_drawio_mermaid`, `get_drawio_reference`, `search_shapes`, `list_pages` / `get_page` / `set_page` |
| CLI export/layout | `~/.local/bin/drawio-cli` (wrapper headless, Xvfb auto). Binaire : `~/.local/opt/drawio/drawio` (32.6.1, extraction locale sans root) |
| Éditeur | **draw.datagrandest.net** (SSO YunoHost). Env du serveur MCP : `DRAWIO_BASE_URL=https://draw.datagrandest.net/` → les URLs d'édition ouvrent l'instance locale |
| Script shapes (secours) | `~/.opencode/skills/drawio/scripts/find-shapes.js` (Node 18+, réseau) |

**SSO = non bloquant.** Le MCP ne dialogue jamais avec l'instance : le diagramme voyage dans le fragment `#` de l'URL (jamais transmis au serveur) ; seul le navigateur (déjà authentifié) charge l'éditeur.

## Deux flux

1. **Flux rapide (MCP)** — discuter/tier le schéma à la volée : appeler `open_drawio_xml` (XML mxGraph), `open_drawio_mermaid` (syntaxe Mermaid, `postLayout: "elk"` possible pour flowchart) ou `open_drawio_csv` (organigrammes/tabulaire). L'agent reçoit une URL → la présenter à l'utilisateur (l'éditeur s'ouvre dans son navigateur sur l'instance). **Aucun fichier créé.**
2. **Flux fichier (CLI)** — artéfact persistant + exports : générer le `.drawio` (Mermaid ou XML), puis l'exporter et/ou l'archiver (persistance SilverBullet, cf. plus bas).

## Mermaid ou XML ?

| | Mermaid | XML |
|---|---|---|
| Idéal pour | flowchart, séquence, classe, état, ERD, gantt, mindmap, C4, git graph, pie | contrôle fin, positionnement précis, librairies de formes spécifiques (AWS, Azure, réseau, UML détaillé) |
| CLI requis ? | Oui (conversion) | Non (ELK optionnel) |
| Fiabilité | Très bonne (layout auto) | Nécessite de positionner les cellules |

- Si CLI présent (`drawio-cli`) et type standard → **préférer Mermaid**.
- Sinon → XML (fallback universel). Pour XML, possible de laisser le CLI appliquer un layout ELK au lieu de calculer les coordonnées.

## Pipeline fichier

1. **Author** : Mermaid → écrire dans un `.mmd` ; XML → écrire directement le `.drawio` (format natif `<mxfile><diagram>…<mxGraphModel>`).
2. **Mermaid → `.drawio`** (toujours convertir d'abord, puis supprimer le `.mmd`) :
   ```bash
   ~/.local/bin/drawio-cli -x -f xml -o diagram.drawio diagram.mmd
   ```
3. **Livraison** au choix :
   - *Fichier* : garder le `.drawio` (le donner à l'utilisateur, l'archiver dans SilverBullet).
   - *Export image* : `drawio-cli -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio` (avec `-e` : XML embarqué → le PNG reste éditable dans draw.io). Formats : `png`, `svg`, `pdf`.
   - *URL* : comprimer le XML en base64/zlib (pako) et ouvrir `draw.datagrandest.net/?...#R<data>` (via `open_drawio_xml` du MCP, plus simple).

## Layout (optionnel)

- **ELK** (ré-arrange nœuds + routes arêtes) :
  ```bash
  ~/.local/bin/drawio-cli -x -f xml --layout '[{"layout":"elkLayered","config":{"elk.direction":"RIGHT"}}]' -o diagram.drawio diagram.drawio
  ```
- **libavoid** (route les connecteurs autour des formes, positions conservées) :
  ```bash
  ~/.local/bin/drawio-cli -x -f xml --layout libavoid -o diagram.drawio diagram.drawio
  ```
- Les deux passent par le MCP : `postLayout: "elk"` (open_drawio_xml) et `routing: "libavoid"`. Ne pas combiner les deux.

## Recherche de formes (icônes cloud/réseau/brand)

Ne jamais inventer des `mxgraph.*` : utiliser `search_shapes` (MCP serveur drawio, ~10 000 formes) en priorité, une requête par icône, puis reprendre le `style` tel quel dans le XML. Script local en secours :
```bash
node ~/.opencode/skills/drawio/scripts/find-shapes.js "aws4 lambda" "azure2 function" "github"
```
Utile seulement pour les schémas avec icônes industrielles/brandées ; inutile pour flowchart/UML/ERD standard.

## Persistance SilverBullet (convention)

Les `.drawio` archivés (et leurs exports éventuels) sont des **attachments** de l'espace — source de vérité. Convention :
- **Dossier unique** : `07_DIAGRAMMES/` (page index [[07_DIAGRAMMES]]).
- Extension **`.drawio`** : le plugin SB Draw.io se déclenche sur cette extension (un `.xml` n'est pas reconnu → texte brut).
- Nommage : `<Projet>_<Description>.drawio` ; export : `<nom>.drawio.png` / `.svg` (XML embarqué).
- **Piège : ne PAS archiver une sortie layout ELK** (`--layout`) — le ré-arrangement automatique déforme les containers ; archiver l'original (positions maîtrisées).
- Un schéma = 2 fichiers max ; dépôt via l'API `/.fs` (PUT).
- **Ouverture** : [SB] cliquer le `.drawio` (plugin Draw.io) ou le `.png` ; [draw.io] **File → Open / glisser-déposer** le fichier téléchargé — le `.png` embarqué s'ouvre aussi. `Open from URL` vers SB = **impossible** (fetch sans credentials → 401, même SSO partagé) → ne pas proposer.

## Pièges connus

- **Ne jamais exporter Mermaid → PNG en une étape** (`-e` direct cassé dans draw.io Desktop) : toujours `mmd → drawio` puis export.
- Electron sur serveur : ajouter `--disable-gpu` si erreur `GPU process isn't usable` (via le wrapper, rien à faire en normal).
- Très grands schémas : l'URL peut dépasser la limite du navigateur (~32K–2 Mo) → livrer un fichier `.drawio` à la place.
- `DRAWIO_BASE_URL` : sans elle, les URLs ouvriraient `app.diagrams.net` (public) au lieu de l'instance locale.
- Le MCP ne sauvegarde rien : la persistance est une décision explicite (flux fichier + archivage SB).
- `Open from URL` (draw.io) vers une URL SilverBullet échoue : fetch cross-origin sans credentials (cookie SSO non envoyé → 401) + CORS. Même SSO partagé ne suffit pas (origines différentes). Solution possible : app statique même-origin sur draw.datagrandest.net.

## Référence XML/Mermaid

Avant le premier schéma (ou en cas de doute), lire la référence via `get_drawio_reference` du serveur MCP (`format: "xml"` ou `"mermaid"`). Docs officielles : <https://github.com/jgraph/drawio-mcp> (skill d'origine, pipeline et dépannage).