# FlowZap MCP - Documentation complète pour les agents IA

**Version :** 1.4.3  
**Dernière mise à jour :** Mai 2026  
**Public cible :** LLM, agents IA et systèmes agentiques  
**Documentation officielle :** https://flowzap.xyz/fr/flowzap-code

---

## Vue d'ensemble

FlowZap MCP (Model Context Protocol) permet aux agents IA de créer, valider et partager des diagrammes de workflow, de séquence et d’architecture à partir de **FlowZap Code**, une DSL stricte pensée pour la génération machine.

### Ce qu’est FlowZap

FlowZap est une plateforme de diagrammes qui transforme du code textuel en diagrammes visuels.
Contrairement à Mermaid ou PlantUML, FlowZap Code est conçu pour :

- **La génération AI-first** — syntaxe optimisée pour les sorties LLM
- **Les workflows agentiques** — utile pour n8n, Make.com, Zapier et les agents métier
- **Le rendu triple vue** — le même code rend un workflow, une séquence et une architecture
- **Le partage instantané** — création d’URL partageables sans authentification

---

## Garanties de sécurité

Le serveur MCP FlowZap met en place plusieurs protections par défaut.

### Sécurité réseau

| Protection | Mise en œuvre |
|------------|----------------|
| **Prévention SSRF** | Connexions limitées à `flowzap.xyz` et `www.flowzap.xyz` via HTTPS |
| **Validation des URL** | Toutes les URL renvoyées sont vérifiées comme provenant des domaines FlowZap |
| **Timeout requête** | 30 secondes pour éviter les connexions bloquées |

### Validation des entrées

| Limite | Valeur | Objectif |
|-------|--------|----------|
| **Taille max du code** | 50 000 caractères | Éviter l’épuisement mémoire |
| **Taille max d’entrée** | 100 000 caractères | Réduire les attaques par payload |
| **Suppression des octets nuls** | Automatique | Réduire les risques d’injection |
| **Nettoyage des caractères de contrôle** | Automatique | Retirer les caractères non imprimables |

### Limitation de débit

| Paramètre | Valeur |
|-----------|--------|
| **Max requêtes** | 30 par minute |
| **Fenêtre** | 60 secondes |
| **Comportement** | Retourne un délai d’attente si dépassé |

### Confidentialité

- **Aucune authentification requise** pour les endpoints publics
- **Aucune donnée utilisateur persistée** dans ces endpoints publics
- **Pas de tracking** côté machine-readable
- **Cookies non requis** pour l’usage MCP public

---

## Outils disponibles

### 1. `flowzap_get_syntax`

**But :** récupérer la documentation complète de la syntaxe FlowZap Code.

**Quand l’utiliser :** avant toute génération de code, pour apprendre la DSL correcte.

**Entrée :**

```json
{
  "type": "object",
  "properties": {}
}
```

**Sortie :** guide complet avec contraintes globales, formes, syntaxe des nœuds, syntaxe des arêtes, boucles et erreurs fréquentes.

---

### 2. `flowzap_validate`

**But :** valider la syntaxe FlowZap Code avant la création d’un diagramme.

**Quand l’utiliser :** toujours avant `flowzap_create_playground`.

**Entrée :**

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "FlowZap Code à valider"
    }
  },
  "required": ["code"]
}
```

**Sortie attendue :**

- validité du code
- erreurs détaillées ligne par ligne
- warnings de bonnes pratiques
- statistiques (`lanes`, `nodes`, `edges`, `loops`)

---

### 3. `flowzap_create_playground`

**But :** créer une URL playground partageable avec le diagramme.

**Quand l’utiliser :** après validation, pour fournir une URL interactive à l’utilisateur.

**Entrée :**

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "FlowZap Code à charger"
    },
    "view": {
      "type": "string",
      "enum": ["workflow", "sequence", "architecture"]
    }
  },
  "required": ["code"]
}
```

**Notes :**

- le code est validé automatiquement
- en cas d’erreur, la validation est renvoyée
- l’URL est partageable
- la vue `architecture` est recommandée pour les diagrammes multi-systèmes

---

### 4. `flowzap_export_graph`

**But :** exporter FlowZap Code sous forme de graphe JSON structuré.

**Cas d’usage :** raisonnement programmatique sur les lanes, nœuds et arêtes.

### 5. `flowzap_artifact_to_diagram`

**But :** convertir logs HTTP, spécifications OpenAPI ou code en diagrammes FlowZap.

**Cas d’usage :** transformer un artefact technique brut en diagramme visualisable.

### 6. `flowzap_diff`

**But :** comparer deux versions de FlowZap Code.

**Cas d’usage :** expliquer des changements ou générer un diff structuré.

### 7. `flowzap_apply_change`

**But :** appliquer des opérations de patch structurées à un diagramme existant.

**Cas d’usage :** édition incrémentale de diagrammes sans tout régénérer.

---

### 8. `flowzap_compliance_check`

**But :** lancer une analyse automatisée de conformité SOC2, GDPR et PIPL sur un diagramme de flux de données FlowZap Code.

**Cas d'usage :** lorsque l'utilisateur demande une revue de confidentialité, sécurité ou conformité d'un diagramme. Basé sur le LLM Deepseek.

**Limites de débit (strictes — protection coût LLM) :**
- **3 appels réussis/jour** par IP ou par mcpIdentity
- **1 appel/heure** en rafale par IP
- **Disjoncteur global de 5 minutes** en cas d'échecs amont répétés
- Seuls les appels réussis comptent dans le quota journalier

**Sortie :** rapport d'audit Markdown + URL de résultat éphémère partageable (TTL 60 min).

---

## Référence rapide de validation

### Erreurs bloquantes

- `CONTAINS_EMOJI`
- `NESTED_LANE`
- `UNMATCHED_BRACE`
- `UNCLOSED_BRACE`
- `DUPLICATE_NODE_ID`
- `INVALID_SHAPE`
- `MISSING_LABEL`
- `NODE_OUTSIDE_LANE`
- `MISSING_HANDLES`
- `INVALID_EDGE_SYNTAX`
- `INVALID_DIRECTION`
- `EDGE_OUTSIDE_LANE`
- `UNDEFINED_LANE_REF`
- `INVALID_LOOP_SYNTAX`
- `LOOP_OUTSIDE_LANE`
- `MISPLACED_COMMENT`
- `COMMENT_OUTSIDE_LANE`
- `UNDEFINED_NODE`
- `NON_SEQUENTIAL_NUMBERING`
- `WRONG_LABEL_SYNTAX`
- `WRONG_EDGE_LABEL_SYNTAX`
- `ORPHAN_NODE`
- `MISSING_RETURN_EDGE`
- `MULTIPLE_OUTBOUND_REQUESTS`
- `CHRONOLOGICAL_PAIRING_VIOLATION`
- `EMPTY_DIAGRAM`
- `WRONG_DSL_FORMAT`

### Warnings

- `NON_PRINTABLE_CHARS`
- `DUPLICATE_LANE`
- `MISSING_LANE_LABEL`
- `NON_STANDARD_NODE_ID`
- `TASKBOX_MISSING_PROPS`
- `LOOP_TOO_FEW_NODES`
- `UNKNOWN_ATTRIBUTE`
- `LABEL_TOO_LONG`

---

## Règles essentielles de FlowZap Code

- UTF-8 texte brut uniquement
- IDs globaux `n1`, `n2`, `n3` sans doublons ni trous
- Formes autorisées : `circle`, `rectangle`, `diamond`, `taskbox`
- Attributs autorisés : `label`, `owner`, `description`, `system`
- Les attributs de nœud utilisent `:`
- Les labels d’arêtes utilisent `=` dans `[]`
- Les handles autorisés sont `left`, `right`, `top`, `bottom`
- Les références inter-lanes utilisent `laneName.nX.handle(direction)`
- Le commentaire de lane doit être sur la même ligne que l’accolade ouvrante : `laneName { # Label`
- En vue séquence, alternez strictement requête, réponse, puis requête suivante

### Exemple simple

```plaintext
process { # Processus
  n1: circle label:"Début"
  n2: rectangle label:"Étape"
  n3: circle label:"Fin"
  n1.handle(right) -> n2.handle(left)
  n2.handle(right) -> n3.handle(left)
}
```

### Exemple multi-lanes

```plaintext
sales { # Équipe Sales
  n1: circle label:"Commande reçue"
  n2: rectangle label:"Soumettre la commande"
  n5: rectangle label:"Recevoir décision"
  n1.handle(right) -> n2.handle(left)
  n2.handle(bottom) -> fulfillment.n3.handle(top) [label="Soumettre"]
}

fulfillment { # Fulfillment
  n3: rectangle label:"Réviser la commande"
  n4: rectangle label:"Retourner décision"
  n3.handle(right) -> n4.handle(left)
  n4.handle(top) -> sales.n5.handle(bottom) [label="Approuvée"]
}
```

---

## Workflow recommandé pour un agent

1. Appeler `flowzap_get_syntax`
2. Générer du FlowZap Code
3. Appeler `flowzap_validate`
4. Corriger les erreurs si nécessaire
5. Appeler `flowzap_create_playground`
6. Renvoyer l’URL à l’utilisateur

---

## Endpoints publics utiles

| Endpoint | Méthode | Limite | Utilité |
|----------|---------|--------|---------|
| `/api/validate` | POST | 30/min | Valider la syntaxe FlowZap Code |
| `/api/playground/create` | POST | 5/min, 50/jour | Créer une URL playground (TTL 15 min) |
| `/api/compliance-check` | POST | 5/min, 30/jour | Analyse de conformité SOC2/GDPR/PIPL sur FlowZap Code. Retourne les frameworks + URL de résultat partageable (TTL 60 min). Basé sur Deepseek LLM. |

**OpenAPI :** https://flowzap.xyz/.well-known/openapi.json

---

## Liens utiles

- Documentation humaine : https://flowzap.xyz/fr/docs/mcp
- Documentation JSON : https://flowzap.xyz/fr/docs/mcp.json
- Markdown brut : https://flowzap.xyz/fr/docs/mcp.md
- Manifest capabilities : https://flowzap.xyz/fr/.well-known/capabilities.json
- Package npm : https://www.npmjs.com/package/flowzap-mcp
- Skill FlowZap : https://skills.sh/flowzap-xyz/flowzap-mcp/flowzap-diagrams

---

## Escalade humaine

Utilisez le support humain si :

- la validation échoue encore après plusieurs corrections
- une URL playground renvoie une erreur 404/500
- la limite de débit bloque un usage légitime
- le diagramme demandé dépasse les capacités de la DSL

**Support :** https://flowzap.xyz/fr/feedback  
**Email :** hello@flowzap.xyz