uml-mcp

1. Démonstration

L’enregistrement vient du dépôt (docs/assets/mcp-app-demo.mp4). Un seul appel generate_uml_batch renvoie quatre diagrammes sous forme d’onglets dans la visionneuse MCP App ; l’utilisateur change d’onglet, puis refait le rendu d’un diagramme dans un autre format.

Les clients sans MCP Apps reçoivent le même résultat sous forme d’image en ligne et de liens, ce qu’affichent la plupart des clients de conversation :

3. Aperçu

Le serveur expose cinq outils, ainsi que des ressources (uml://types, uml://examples, uml://templates), des invites et des fichiers de compétences qui enseignent chaque notation à l’assistant.

Le README compte 46 types de diagrammes : 37 rendus par Kroki et 9 par quatre extensions fournies (graphes de forces D3 et diagrammes infonuagiques avec de vrais logos, diagrammes de pile, architecture, flux et séquences façon archify, et cartes de couches de LLM en 2D/3D).

4. Ce qui se passe lors d’un appel

generate_uml, dans mcp_core/tools/diagram_tools.py, n’est qu’une enveloppe ; le travail se fait dans generate_from_request (mcp_core/core/diagram_service.py) et run_diagram_pipeline (mcp_core/core/diagram_rendering.py).

sequenceDiagram
  participant AI as Assistant (client MCP)
  participant Tool as generate_uml
  participant Svc as generate_from_request
  participant Cache as Cache de rendu
  participant Pipe as run_diagram_pipeline
  participant K as Kroki
  participant FB as Serveur PlantUML / mermaid.ink
  AI->>Tool: diagram_type, code, output_format, theme, scale
  Tool->>Tool: resolve_diagram_type (clé exacte, sinon suggestions ou sélecteur)
  Tool->>Svc: DiagramRequest
  Svc->>Svc: validation GenerateUMLInput, type au catalogue ?
  Svc->>Cache: clé SHA-256 du type, de la source, du format, du thème, de l’échelle et du moteur
  alt présent en cache
    Cache-->>AI: résultat enregistré, cache_hit = true
  else absent
    Svc->>Pipe: rendu
    alt type d’extension
      Pipe->>Pipe: render_with_plugin
    else type Kroki
      Pipe->>K: GET /{type}/{format}/{source deflate+base64url}
      K-->>Pipe: SVG ou PNG
      opt échec de Kroki et repli activé
        Pipe->>FB: même source
      end
    end
    Pipe-->>Svc: résultat + attempts + render_ms
    Svc->>Svc: aplatit les étiquettes SVG, matricialise si PNG demandé pour un type SVG seulement, construit display_markdown
    Svc->>Cache: enregistre
    Svc-->>AI: url, playground, image, display_markdown
  end

Étape par étape :

1. Type. mrtr.resolve_diagram_type met la clé en minuscules et l’accepte si elle est au catalogue. Sinon, si le client sait afficher un formulaire, le serveur demande à l’utilisateur de choisir parmi jusqu’à huit types proches (difflib, seuil 0,45) ; sinon, il renvoie une erreur avec ces suggestions. Le thème suit le même traitement.
2. Validation. GenerateUMLInput (Pydantic) vérifie les arguments ; la source est limitée par MCP_MAX_CODE_LENGTH, 500 000 caractères par défaut. Un type inconnu renvoie UNSUPPORTED_DIAGRAM_TYPE avec un renvoi vers uml://types.
3. Format. Si le client demande du PNG ou du JPEG pour un type qui ne rend que du SVG, le service rend le SVG puis le matricialise.
4. Cache. Les appels qui n’écrivent pas de fichier sont mis en cache en mémoire. La clé est le SHA-256 d’un objet JSON contenant le type, la source sans espaces de bord, le format, le thème, l’échelle et l’identité du moteur. Valeurs par défaut : 300 secondes, 128 entrées, 32 Mio (MCP_RENDER_CACHE_*).
5. Rendu. Les types d’extension (moteur plugin:) sont rendus localement. Tout le reste part chez Kroki : la source est compressée avec zlib au niveau 9, encodée en base64url et placée dans l’URL {kroki}/{type}/{format}/{encodé}, qui est aussi le lien rendu à l’utilisateur.
6. Repli. Si Kroki échoue, les sources de la famille PlantUML sont renvoyées au serveur PlantUML et le Mermaid à mermaid.ink. Mermaid a un délai court de 8 secondes chez Kroki, et un disjoncteur évite le moteur Mermaid de Kroki pendant 60 secondes après des échecs répétés. Le repli est désactivé par défaut sur Vercel et avec un Kroki local, où les services publics ne seraient pas la bonne cible.
7. Réponse. Les étiquettes HTML des SVG (foreignObject) sont converties en texte SVG simple pour que le fichier s’affiche partout, display_markdown est construit pour la conversation, et chaque résultat porte attempts, fallback_used et render_ms : un échec dit quel moteur a échoué et pourquoi.

5. Exploitation

uml-mcp admin ouvre une console web sur http://127.0.0.1:8765/admin (sur un serveur déployé, /admin) : installation, réglages, activité, journaux en direct, métriques, limites de débit, outils et extensions, clients et contrôles de qualité. En local, les modifications exigent un jeton d’installation à usage unique ; avec l’authentification d’entreprise (Entra ID), la console reste en lecture seule tant que l’écriture n’est pas activée dans les réglages.

6. Démarrage

Utilisez le serveur hébergé dans n’importe quel client MCP :

"uml-mcp": {
  "transport": "http",
  "url": "https://uml-mcp.vercel.app/mcp"
}

Ou installez-le en local et laissez la commande d’installation écrire la configuration du client :

uv tool install uml-mcp && uml-mcp setup

Demandez ensuite un diagramme à l’assistant, par exemple « Dessine un diagramme de séquence d’un utilisateur qui se connecte par une passerelle d’API. » Le dépôt fournit des configurations prêtes pour Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json), Codex, Claude Desktop et Open WebUI, et docs/installation.md couvre Docker, Helm et l’exécution depuis les sources.

7. Guide du dépôt

• server.py, app.py : points d’entrée stdio et HTTP ; server.py résout l’objet MCP à la demande, si bien qu’un import n’écrit rien sur stdout, qui transporte le protocole stdio.
• mcp_core/tools/ : les fonctions des outils, leurs schémas, l’aide à l’élicitation (mrtr.py), les notifications de progression des lots et l’export.
• mcp_core/core/ : catalogue, validation, chaîne de rendu, cache de rendu, matricialisation SVG, thèmes et configuration.
• mcp_core/plugins/, examples/plugins/ : le chargeur d’extensions et les quatre extensions fournies (D3, diagramme de pile, archify, visualiseur de LLM).
• mcp_core/apps/ : la visionneuse MCP App (ui://uml-mcp/diagram-viewer) et le nettoyage des SVG.
• mcp_core/admin/, mcp_core/auth/, mcp_core/observability/ : console d’administration, authentification unique et métriques.
• tools/kroki/ : le client Kroki, l’encodage des URL, les liens d’éditeur et les aides propres à chaque langage.
• deploy/helm/, Dockerfile, docker-compose*.yml, vercel.json : déploiement.
• tests/ : 127 entrées, tests unitaires et d’intégration avec des bancs MCP et HTTP.

8. Limites

• Les types rendus par Kroki dépendent d’une instance Kroki joignable, et comme la source voyage dans l’URL, les très gros diagrammes donnent des liens très longs.
• Le cache de rendu est propre à chaque processus et en mémoire : il n’est pas partagé entre instances sans serveur.
• Quand ils sont activés, les replis envoient la source du diagramme à des services tiers (serveur PlantUML, mermaid.ink) ; réglez MCP_DIAGRAM_FALLBACK=false si la source est privée.
• La prise en charge des MCP Apps varie selon les clients ; les autres ne reçoivent que l’image et les liens.

9. Sources

• Dépôt GitHub
• Documentation
• Paquet PyPI
• mcp_core/tools/diagram_tools.py
• mcp_core/core/diagram_service.py
• mcp_core/core/diagram_rendering.py
• mcp_core/core/render_cache.py
• tools/kroki/kroki.py
• Article associé

flowchart LR
  subgraph wf0["Build Package"]
    direction LR
    wf0_build[["build<br/>ubuntu-latest"]]
  end
  subgraph wf1["UML-MCP CD Pipeline"]
    direction LR
    wf1_prepare["prepare<br/>ubuntu-latest"]
    wf1_build["build<br/>réutilise build.yml"]
    wf1_deploy["deploy<br/>réutilise deploy.yml"]
  end
  subgraph wf2["UML-MCP CI Pipeline"]
    direction LR
    wf2_lint["lint<br/>ubuntu-latest"]
    wf2_test[["test<br/>ubuntu-latest"]]
    wf2_public_kroki["public-kroki<br/>ubuntu-latest"]
    wf2_helm[["helm<br/>ubuntu-latest"]]
    wf2_frontend["frontend<br/>ubuntu-latest"]
    wf2_build["build<br/>réutilise build.yml"]
  end
  subgraph wf3["Deploy (Vercel conformance + Smithery publi…"]
    direction LR
    wf3_test_and_publish[["test-and-publish<br/>ubuntu-latest"]]
  end
  subgraph wf4["Deploy docs"]
    direction LR
    wf4_build[["build<br/>ubuntu-latest"]]
    wf4_deploy[["deploy<br/>ubuntu-latest"]]
  end
  subgraph wf5["MCP 2026 Conformance"]
    direction LR
    wf5_protocol_conformance[["protocol-conformance<br/>ubuntu-latest"]]
  end
  t0(["lancement manuel · appelé par un workflow"])
  t1(["push · publication · lancement manuel"])
  t2(["lancement manuel · push · demande de fusion"])
  t3(["appelé par un workflow · lancement manuel"])
  t4(["push · lancement manuel"])
  t5(["lancement manuel · demande de fusion"])
  d0[("GitHub Pages")]
  t0 --> wf0_build
  t1 --> wf1_prepare
  wf1_prepare --> wf1_build
  wf1_build --> wf1_deploy
  t2 --> wf2_lint
  t2 --> wf2_test
  t2 --> wf2_public_kroki
  t2 --> wf2_helm
  t2 --> wf2_frontend
  t2 --> wf2_build
  t3 --> wf3_test_and_publish
  t4 --> wf4_build
  wf4_build --> wf4_deploy
  wf4_deploy -.-> d0
  t5 --> wf5_protocol_conformance

flowchart LR
  repo[("Dépôt GitHub")]
  ci[["GitHub Actions<br/>11 workflows"]]
  image["Image Docker<br/>FROM python:3.15-slim"]
  pub_GitHub_Pages[("GitHub Pages")]
  pub_PyPI[("PyPI")]
  host_Vercel("Vercel<br/>vercel.json")
  host_Kubernetes_manifests("Kubernetes<br/>deploy/helm/uml-mcp/")
  host_MkDocs_site("Site de documentation (MkDocs)<br/>mkdocs.yml")
  subgraph compose["Docker Compose"]
    svc_uml_mcp["uml-mcp"]
    svc_kroki["kroki"]
    svc_mermaid["mermaid"]
    svc_blockdiag["blockdiag"]
    svc_bpmn["bpmn"]
    svc_excalidraw["excalidraw"]
    svc_plantuml_server["plantuml-server"]
    svc_mermaid_ink["mermaid-ink"]
  end
  repo -->|"push ou demande de fusion"| ci
  ci -->|"docker build"| image
  ci -->|"publie"| pub_GitHub_Pages
  ci -->|"publie"| pub_PyPI
  ci -.->|"configuré"| host_Vercel
  ci -.->|"configuré"| host_Kubernetes_manifests
  ci -.->|"configuré"| host_MkDocs_site
  image -->|"docker compose up"| compose