Aller au contenu

uml-mcp : D’un appel MCP à un diagramme

uml-mcp expose des outils de diagrammes aux clients MCP. Le client fournit une source et des options; le serveur valide la demande, l’oriente vers les services de rendu et retourne les résultats avec des liens d’édition.

Application et services API
  • Mis à jour
  • 108
  • Python · 90.9%
  • MIT
Langages du dépôtPython 90.9%9

Parts calculées à partir des octets GitHub Linguist.

Langage%Octets
Python90.9%1 642 190
TypeScript7.99%144 367
Shell0.31%5 667
CSS0.26%4 713
Go Template0.23%4 227
Makefile0.14%2 522
3 autres langages
Dockerfile0.11%1 964
JavaScript0.03%587
HTML0.02%422

GitHub · README · Statistiques de langages

Aperçu

Pourquoi il existe

Serveur phare Model Context Protocol (MCP) générant PlantUML, Mermaid et Kroki directement depuis des LLMs (Claude, Cursor, ChatGPT) sans dépendance locale.

Cas d’usage

Génération interactive de diagrammes d'architecture pour le pair programming avec IA et la documentation.

Démarrage

Ces commandes viennent de la documentation du dépôt. Elles n’ont pas été exécutées pendant cette revue.

README.md · Quick start
git clone https://github.com/antoinebou12/uml-mcp.git
cd uml-mcp
uv sync
uv run python server.py
README.md · Quick start
git remote add origin https://github.com/antoinebou12/uml-mcp.git
tests/mcp-rig/README.md · Running
make mcp-rig
tests/mcp-rig/README.md · Running
uvx [email protected] run tests/mcp-rig/
uvx [email protected] run tests/mcp-rig/ --tag smoke
uvx [email protected] run tests/mcp-rig/generate.yaml --case "batch*"
uvx [email protected] run tests/mcp-rig/ --server-logs   # show server stderr when debugging
Commandes déclarées dans les manifestes

frontend/package.json

dev
vite
build
npm run typecheck && vite build
typecheck
node node_modules/typescript-7/bin/tsc --noEmit
lint
eslint .
test
vitest run

Références du dépôt

Extraits des guides du dépôt, dans leur langue d’origine. Les liens ouvrent la version du code consultée.

Prérequis et premier essai

Quick start

README.md

Remote (recommended) — add to your MCP client: Use /mcp, not the site root. Then ask: “Draw a sequence diagram of a user logging in through an API gateway.” or paste PlantUML / Mermaid / Kroki source. Repo defaults: .cursor/mcp.json · .vscode/mcp.json · .codex/config.toml.

ClientConfigGuide
Cursor.cursor/mcp.jsondocs/integrations/cursor.md
VS Code / Copilot.vscode/mcp.jsondocs/integrations/vscode_copilot.md
OpenAI Codex.codex/config.tomldocs/integrations/openai_codex.md
Ollama / Open WebUIconfig/openwebui_mcp.jsondocs/integrations/ollama.md
Claude Desktopconfig/claude_desktop_*.jsondocs/integrations/claude_desktop.md
All snippets: config/README.md
Install locally (guided):
PathCommand
——
Installer (needs only Python + typer + tqdm)python scripts/install.py
Setup wizarduv tool…
Lire les instructions complètes ↗

Prerequisites

CONTRIBUTING.md

  • Python 3.12+ (supported range is >=3.12,<3.16 in pyproject.toml; CI exercises 3.12 and 3.15; Docker uses 3.15)
  • uv, Poetry, or pip
Lire les instructions complètes ↗

Lockfile and `requirements.txt`

CONTRIBUTING.md

uv.lock is the runtime source of truth for CI, Vercel, and release validation. Deploy/install paths export from the lockfile at runtime. Keep requirements.txt updated for users that still install with pip: Run this after changing runtime dependencies in pyproject.toml / uv.lock, then commit the updated requirements.txt. Transitive pins: Some packages are pinned only in [tool.uv] override-dependencies in pyproject.toml (they are not direct Poetry deps). Dependabot is configured for the uv ecosystem so PRs target uv.lock consistently. After merging a dependency PR, re-export requirements.txt if the lockfile changed so CI’s “export matches requirements.txt” step stays green.
Lire les instructions complètes ↗

Installation

docs/installation.md

PathBest forCommand
InstallerAnyone; needs only Python 3.12+, typer and tqdmpython scripts/install.py
Setup wizardTerminal usersuv tool install uml-mcp && uml-mcp setup
Web setupA guided form in the browseruml-mcp setup –web
Server / KubernetesTeamsDocker · Helm + SSO
Lire les instructions complètes ↗

1. Quick install

docs/installation.md

The installer picks uv (uv tool install), then pipx, then pip –user, shows progress and then starts the setup wizard.

OptionMeaning
–method uv|pipx|pipForce an installer
–version 1.4.0Pin a version
–extras otelOptional extras (otel = OpenTelemetry)
–webRun the browser setup form instead of the terminal wizard
–no-setupInstall only
–dry-runPrint the commands, change nothing
Prefer doing it yourself? uv tool install uml-mcp (or pipx install uml-mcp).
Lire les instructions complètes ↗
Configuration et utilisation

Development setup

CONTRIBUTING.md

  1. Fork and clone the repo:
  2. Create a virtual environment and install dependencies (including dev): With uv (recommended): With Poetry: With pip:
  3. (Optional) Install pre-commit hooks so lint/format run before each commit:
Lire les instructions complètes ↗

MCP Client Configuration Examples

config/README.md

Lire les instructions complètes ↗

Client matrix

config/README.md

ClientHosted HTTPLocal stdioGuide
Cursorcursor_http.json · .cursor/mcp.jsoncursor_config.jsondocs/integrations/cursor.md
Claude Desktopclaude_desktop_http.jsonclaude_desktop_config.jsondocs/integrations/claude_desktop.md
VS Code / GitHub Copilotvscode_mcp.json · .vscode/mcp.jsonvscode_mcp_stdio.jsondocs/integrations/vscode_copilot.md
OpenAI Codexcodex_config.toml · .codex/config.tomlcodex_stdio.tomldocs/integrations/openai_codex.md
Open WebUI + Ollamaopenwebui_mcp.jsonOptional via mcpodocs/integrations/ollama.md
Continue + Ollamacontinue_config.yamlSee comments in that filedocs/integrations/ollama.md
Lire les instructions complètes ↗

OpenAI Codex (CLI + IDE)

config/README.md

  • User: ~/.codex/config.toml
  • Project: .codex/config.toml (loads only when the project is trusted)
  • Verify: codex mcp list or /mcp in a session
Lire les instructions complètes ↗

2. Setup wizard (`uml-mcp setup`)

docs/installation.md

The wizard asks for:

  • a profile (local, docker or enterprise)
  • which features to turn on (each one is explained, with whether it applies live or needs a restart)
  • a Kroki server
  • which MCP clients to register It then runs, with a progress bar:
  1. validate the configuration
  2. write ~/.config/uml-mcp/config.yaml (mode 0600, with a backup of any previous file)
  3. register the clients
  4. run a health check
    Feature keyWhat it doesApplies
    memory_onlyKeep diagrams in memory; return URLs/bytes, no filesrestart
    diagram_fallbackRetry with PlantUML server or mermaid.ink when Kroki failsrestart
    auditMXCP-style audit trail of every call (redacted)live
    json_logsOne JSON object per log linelive
    metrics_endpointPrometheus /metricsrestart
    otelOpenTelemetry traces (needs uml-mcp[otel])live
    rate_limit…
Lire les instructions complètes ↗
Exploitation et dépannage

Uninstall

docs/installation.md

Then remove the uml-mcp entry from your client’s MCP config. A backup of the previous config is kept next to it.
Lire les instructions complètes ↗

Troubleshooting

docs/installation.md

SymptomFix
uml-mcp: command not foundOpen a new terminal, or run uv tool update-shell or pipx ensurepath
Setup page says “Enter the setup token”Use the token printed by uml-mcp admin, or set UML_MCP_ADMIN_TOKEN
Diagrams fail to renderCheck rendering.kroki_server reachability; enable diagram_fallback
Settings are read-onlyThe file is mounted read-only (e.g. Kubernetes); use Download YAML and apply it through your deployment
uml-mcp lint reports CFG010pip install “uml-mcp[otel]” or turn OpenTelemetry off
Lire les instructions complètes ↗

Health check (HTTP deployment)

docs/configuration.md

When running the FastAPI app (app.py) for HTTP deployment (e.g. Vercel, Docker, uvicorn), a health endpoint is available:

  • Endpoint: GET /health (no authentication required)
  • Response: {“status”: “healthy”, “modules_available”: true|false}
  • status: Always “healthy” when the server is up.
  • modules_available: Whether diagram backends (Kroki, PlantUML, etc.) could be loaded. Use /health for load balancers, Kubernetes or Docker liveness/readiness probes, Vercel checks, and similar monitoring whenever you run the FastAPI app (app.py). When running the MCP server via fastmcp run with HTTP transport only (no FastAPI app), the standalone server does not expose /health unless you add a custom route; use the FastAPI app if you need the health endpoint.
Lire les instructions complètes ↗

Troubleshooting

docs/admin/install.md

SymptomCause and fix
404 on /admin of a serverAuth is off and admin.allow_local_without_auth is not true, or the request didn’t come from loopback
Buttons are disabled, “Enter the setup token”Use the link printed by uml-mcp admin, or paste the token into the key icon in the top bar
docker is not installed / the Docker daemon is not runningInstall Docker Desktop or Engine, start it, then run uml-mcp kroki up again
port is already allocatedAnother service uses 8001: uml-mcp kroki up –port 8002 –use
A companion shows HTTP 500 right after startIt is still starting. Run uml-mcp kroki status again after a few seconds; up already waits up to 5 minutes
KROKI_SERVER is set by the environment (409)An environment variable wins over uml-mcp.yaml. Change or unset it where the server is started
Rendering works in the playground but…
Lire les instructions complètes ↗
Développement et contributions

Contributing to UML-MCP

CONTRIBUTING.md

Thank you for considering contributing. This document explains how to set up your environment, run tests, and submit changes.
Lire les instructions complètes ↗

Running tests

CONTRIBUTING.md

With coverage: Black-box tests of the stdio server (real transport, YAML suites, no network) run with MCP Rig: See tests/mcp-rig/README.md for the suites, tags and how to update snapshots.
Lire les instructions complètes ↗

Development install (from a clone)

docs/installation.md

To work on the console, see Frontend. Poetry (poetry install –with dev) and pip (pip install -e .) also work.
Lire les instructions complètes ↗

Contributing

docs/developers/contributing.md

Thanks for your interest in improving UML-MCP. The full guidelines live in the repo root; this page summarises the most useful entry points.

DocumentWhy
CONTRIBUTING.mdLocal setup, branching model, commit and PR conventions.
CODE_OF_CONDUCT.mdCommunity expectations.
SECURITY.mdHow to responsibly report a security issue.
Lire les instructions complètes ↗
Documentation source

17 documents lus parmi 17 candidats.

Fonctions et composants 2

Un point d’entrée sans sortie parasite
server.py délègue le démarrage à mcp_core.core.server. L’objet mcp est résolu à la demande par __getattr__, ce qui évite de construire le serveur ou d’écrire sur stdout lors d’un simple import. C’est important quand stdout transporte le protocole stdio.
Transport et rendu
Le serveur propose des parcours stdio et HTTP. Le cœur regroupe l’enregistrement des outils, la configuration et l’intégration Kroki. Le rendu reste une opération en aval: la couche MCP décrit les outils et transporte leurs entrées et résultats.

Architecture

Les composants et leurs liens restent lisibles en texte. Le diagramme ajoute une vue interactive.

Contexte système Contexte
  1. Client MCP
  2. Transport stdio ou HTTP
  3. Outils FastMCP et validation
  4. Moteur Kroki
  5. Résultat et liens

Liens vérifiés dans le dépôt.

Mermaid Diagramme interactif (chargement à l’ouverture)

Vue générale des composants et des échanges vérifiés dans le dépôt.

Vue statique de l’architecture de uml-mcp
Aperçu statique. Le diagramme interactif le remplace après le chargement de Mermaid.
flowchart LR

subgraph group_runtime["MCP Runtime"]
  node_mcp_server["MCP Server<br/>[server.py]"]
  node_diagram_tools["Diagram Tools<br/>[diagram_tools.py]"]
  node_plugin_loader["Plugin Loader<br/>[loader.py]"]
end

subgraph group_diagrams["Diagram Workflow"]
  node_validation["Input Validation"]
  node_diagram_service["Diagram Service<br/>[diagram_service.py]"]
  node_rendering["Diagram Rendering"]
  node_kroki["Kroki Renderers<br/>[kroki.py]"]
  node_render_cache["Render Cache<br/>[render_cache.py]"]
  node_delivery["Chat and Image Output<br/>[chat_packet.py]"]
  node_catalog["Diagram Catalog<br/>[diagram_catalog.py]"]
end

subgraph group_agent["Agent Interfaces"]
  node_prompts["Diagram Prompts<br/>[diagram_prompts.py]"]
  node_resources["Diagram Resources"]
  node_agui["AG-UI Events<br/>[agui.py]"]
end

subgraph group_admin["Admin Console"]
  node_admin_api["Admin API<br/>[routes.py]"]
  node_admin_settings["Settings Service"]
  node_kroki_admin["Kroki Playground<br/>[kroki_routes.py]"]
  node_console_ui["Admin Web Console<br/>[App.tsx]"]
end

subgraph group_operations["Security and Operations"]
  node_enterprise_auth["Bearer Authentication<br/>[mcp_auth.py]"]
  node_audit["Audit and Metrics<br/>[audit.py]"]
end

node_client(("AI Client"))
node_kroki_service["Kroki Service"]

node_client -->|"requests tools"| node_mcp_server
node_mcp_server -->|"registers tools"| node_diagram_tools
node_diagram_tools -->|"validates input"| node_validation
node_diagram_tools -->|"requests generation"| node_diagram_service
node_diagram_service -->|"generates diagram"| node_rendering
node_diagram_service -->|"reads and writes"| node_render_cache
node_rendering -->|"renders source"| node_kroki
node_kroki -.->|"sends render request"| node_kroki_service
node_diagram_service -->|"builds display output"| node_delivery
node_diagram_tools -->|"lists diagram types"| node_catalog
node_mcp_server -->|"registers prompts"| node_prompts
node_mcp_server -->|"registers resources"| node_resources
node_mcp_server -.->|"serves event interface"| node_agui
node_console_ui -.->|"uses console API"| node_admin_api
node_admin_api -->|"reads and saves"| node_admin_settings
node_admin_api -->|"adds Kroki routes"| node_kroki_admin
node_kroki_admin -->|"renders playground"| node_diagram_service
node_enterprise_auth -.->|"protects requests"| node_mcp_server
node_admin_api -->|"records operations"| node_audit
node_mcp_server -->|"loads plugins"| node_plugin_loader
node_plugin_loader -.->|"routes plugin types"| node_kroki


class node_mcp_server,node_diagram_tools,node_plugin_loader,node_client toneBlue
class node_validation,node_diagram_service,node_rendering,node_kroki,node_render_cache,node_delivery,node_catalog toneAmber
class node_prompts,node_resources,node_agui toneMint
class node_admin_api,node_admin_settings,node_kroki_admin,node_console_ui toneRose
class node_enterprise_auth,node_audit,node_kroki_service toneIndigo

Un serveur MCP pour découvrir, valider, rendre et livrer des diagrammes. Le runtime enregistre les outils, invites et ressources, puis dirige la source vers les moteurs, le cache et une sortie adaptée au chat; l’administration et l’observabilité suivent un parcours distinct.

Composants
21
Connexions
21
Liens appuyés par le code ou le README
16/21
Version texte du diagramme
  • Client MCP → Transport stdio ou HTTP
  • Transport stdio ou HTTP → Outils FastMCP et validation
  • Outils FastMCP et validation → Moteur Kroki
  • Moteur Kroki → Résultat et liens
  • Résultat et liens → Client MCP
Suivre un parcours dans le code

Partez de server.py, suivez main dans mcp_core, puis examinez l’outil de diagramme avant son moteur. Un appel fournit des arguments structurés, sans rendre automatiquement un texte quelconque valide en Mermaid ou PlantUML.

Contrat des outils MCP

Le service hébergé accepte les messages MCP JSON-RPC sur /mcp. tools/list retourne les schémas d’entrée et de sortie. Le client envoie tools/call avec le nom d’un outil et des arguments structurés.

Exemple de requête
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_uml",
    "arguments": {
      "diagram_type": "mermaid",
      "code": "flowchart LR\n  Client --> Server",
      "output_format": "svg"
    }
  }
}

Réponse et erreurs

Lisez result.structuredContent : success, url, playground et output_format décrivent le rendu. En cas d’échec, inspectez error et error_detail; traitez séparément les erreurs de protocole MCP et isError au niveau de l’outil. Une réponse URL ne contient pas nécessairement les octets de l’image.
Utilisez validate_uml pour vérifier la syntaxe sans générer d’image. generate_uml_batch traite plusieurs éléments et retourne leurs résultats individuels. Envoyez uniquement du texte public au service hébergé; les URL de rendu peuvent encoder ce texte.
Authentification, limites et pagination

Ce point d’accès public a répondu à la génération documentaire sans en-tête Authorization. Cette observation ne définit pas l’authentification de tous les déploiements. tools/list n’annonçait aucun quota fixe. Le rendu retourne un résultat; la découverte du catalogue doit suivre la pagination MCP si le serveur retourne un curseur.

Schéma du service consulté le 2026-10-24 · MCP

Types et structure des fichiers

264 types déclarés, dont 12 dans l’aperçu des relations de base.

Diagramme des types
classDiagram
direction TB
class t8c933d751656["_MCPAcceptHeaderMiddleware"] {
  __init__()
  __call__()
}
class tbbd7d80c6537["_MCPOriginValidationMiddleware"] {
  __init__()
  __call__()
}
class t633b66ae0a60["DiagramRequest"] {
  validate_code_length()
}
class tb2bc4a0b3d1b["DiagramResponse"] {
}
class t57c712c6e160["KrokiEncodeRequest"] {
}
class t3cbf0983a349["KrokiEncodeResponse"] {
}
class teae27f6a16b7["AguiRunRequest"] {
  _normalize_format()
}
class t32b0b600cbbf["AguiRunResponse"] {
}
class t3cbf9378a674["AguiProtocolRunInput"] {
}
class tb9167f0f3b08["D3Renderer"] {
  __init__()
  configure()
  validate()
  render()
}
class t69997369a348["ForceModel"] {
}
class t69a1ba4997d9["Provider"] {
}
class bda110f9bf6d7["BaseModel"] {
  <<unresolved_base>>
}
bda110f9bf6d7 <|-- t633b66ae0a60
bda110f9bf6d7 <|-- tb2bc4a0b3d1b
bda110f9bf6d7 <|-- t57c712c6e160
bda110f9bf6d7 <|-- t3cbf0983a349
bda110f9bf6d7 <|-- teae27f6a16b7
bda110f9bf6d7 <|-- t32b0b600cbbf
bda110f9bf6d7 <|-- t3cbf9378a674

Les bases non résolues restent identifiées; les signatures complètes ne sont pas reconstruites.

Index des types

Référence

297 / 297 fichiers admissibles lus (706 dans l’arbre); 0 trop volumineux, 0 échec de lecture et 0 diagnostic de syntaxe.

Ce que couvre l’analyse

Les dossiers connus de dépendances et de compilation, les fichiers d’identifiants et les binaires sont exclus. La collecte couvre les README, les manifestes reconnus et les fichiers source pris en charge.

Les statistiques Linguist couvrent l’ensemble du dépôt et peuvent inclure d’autres langages.

Carte des fichiers
flowchart TD
  root["uml-mcp"]
  f0["README.md"]
  root --> f0
  f1["server.py"]
  root --> f1
  f2["mcp_core/core/server.py"]
  root --> f2
  f3["Makefile"]
  root --> f3
  f4["app.py"]
  root --> f4
  f5["docker-compose.yml"]
  root --> f5
  f6["pyproject.toml"]
  root --> f6
  f7[".plan/README.md"]
  root --> f7
  f8["api/app.py"]
  root --> f8
  f9["config/README.md"]
  root --> f9
  f10["examples/README.md"]
  root --> f10
  f11["examples/generate_example_files.py"]
  root --> f11
  f12["examples/generate_kroki_url.py"]
  root --> f12
  f13["examples/kroki_standalone_encoding.py"]
  root --> f13
  f14["examples/test_fallback.py"]
  root --> f14
  f15["frontend/eslint.config.js"]
  root --> f15

Fichiers à lire 3

Références