| name | uml-mcp-diagrams |
| description | Creates diagrams via the uml-mcp MCP server (generate_uml, validate_uml, list_diagram_types, generate_uml_batch) and returns shareable Kroki URLs. Use when the user wants diagrams, PlantUML/Mermaid/D2/UML, URLs, Kroki, or diagram_type. |
Maintainers: Keep tool tables and output_dir wording aligned with the Smithery bundle uml-skill/SKILL.md (diagramming-uml) and the Claude Code plugin skill plugins/uml-mcp/skills/uml-diagrams/SKILL.md when you edit any of them.
uml-mcp diagram workflow
Goal
Turn the user’s intent into valid diagram_type + source code, call generate_uml, and surface the url (and playground when present). Prefer URL-first output (omit output_dir / use null) unless the user explicitly asks to save a file.
Positive patterns (do)
- Confirm types first when unsure: read
uml://types / uml://formats or call list_diagram_types before generate_uml.
- Match
diagram_type to the language of code (e.g. Mermaid body → mermaid; PlantUML with @startuml → plantuml or the specific Kroki PlantUML subtype if applicable).
- Use
validate_uml before an expensive retry loop or when the user pastes untrusted LLM output.
- Return the
url plus a short copy of code so the user can edit and regenerate.
- When an LLM produces the diagram text first, prefer fenced or raw source that downstream tools accept; strip ``` fences from pasted input when needed, but still prefer clean DSL without prose inside the diagram.
Negative patterns (avoid)
- Do not invent
diagram_type or output_format values; confirm against uml://types / uml://formats.
- Do not set
output_dir unless the user asked for files on disk (MCP).
- Do not mix human-readable essays into
code—Kroki expects valid DSL only (prose belongs in the chat message, not inside PlantUML/Mermaid source).
- Do not pass invalid JSON for
diagram_options when the API expects a JSON object—never use a bare array or malformed string.
Before generating
- If
diagram_type is unknown or ambiguous, read uml://types (or uml://capabilities) to list valid types and supported backends.
- For starter syntax, use
uml://templates or uml://examples; use resources/list for extra guides (e.g. named Mermaid samples, BPMN 2.0.2 reference) when those URIs are registered.
- Optional quality pass: call
validate_uml with the same diagram_type, code, and planned output_format. Use strict: true for stricter Mermaid/D2 checks when needed.
- If you cannot read
uml://types, call list_diagram_types for the same metadata.
Complex requests
For ambiguous specs, large diagrams, or many actors/states/messages, plan before coding:
- Use an ordered plan (participants, scope, emphasis), revise when wrong, and split the work when one diagram would be too large for a single canvas.
- If the client exposes a sequential-thinking tool or an installed sequential-thinking skill, prefer it for that planning phase, then produce diagram source and call
validate_uml / generate_uml.
Readability (Kroki / DSL)
These rules apply to diagram source (Mermaid, PlantUML, D2, etc.), not to HTML layout:
- Complexity: Aim for roughly <25 nodes in Mermaid and <30 in PlantUML; fewer lifelines in sequence diagrams. If the user’s scope exceeds that, split into two diagrams or an overview plus a detail view.
- Sequence: Time flows top → bottom. Do not model upward message arrows. Use activation where the notation supports it (PlantUML
activate / deactivate; Mermaid activate / deactivate when appropriate). Close every activation interval you open.
- State and flowchart: Label every transition or decision branch (event/guard or yes/no). Avoid drawing the same “to error” edge from every state; prefer one note, a group, or a single
* / global exception path where the DSL allows.
- Emphasis: At most one strong visual highlight when the backend allows it (e.g. one Mermaid
classDef / highlighted participant, one PlantUML skinparam / styled element, one D2 node style). Avoid rainbow or per-node rainbow fills — hierarchy and labels carry meaning.
- Arrow overlap: Set one layout direction (
flowchart TD/LR, PlantUML left to right direction + skinparam linetype ortho, D2 direction: right), group related nodes (subgraph / together { } / D2 container), and use directional arrows (-down->, -right->) on edges that would otherwise cross. Canonical per-backend rules live in the algorithm_explainer and paper_concept_diagram prompt outputs (and uml_diagram_with_thinking).
LLM prompt channels: positive vs negative
When the user (or pipeline) splits positive (must follow) and negative (must refuse) instructions for an LLM that emits diagram source, keep both sides short and non-overlapping.
| Channel | Purpose | Good content |
|---|
| positive | Additive constraints on the model | “Output only valid Mermaid.” “Use sequenceDiagram.” “No prose outside the diagram.” |
| negative | Things to refuse | “No markdown fences.” “No YAML front matter.” “No explanation after the diagram.” |
Positive pattern: short, imperative, DSL-focused. Negative pattern: forbid specific failure modes you see in logs (fences, preamble, wrong diagram type keyword).
Do not duplicate the entire user spec in both positive and negative—negatives should be exclusions, not a second copy of the task.
Prose around URLs
For assistant-facing explanations (summaries, caveats, next steps), you may use a Humanizer skill if it is installed in the client. Do not run humanizer output through diagram code — Kroki needs valid DSL only.
Calling generate_uml
| Input | Guidance |
|---|
diagram_type | Required. Must match a key from uml://types (e.g. class, sequence, mermaid, d2). |
code | Required. Source in the language that matches diagram_type. |
output_dir | Omit or null for URL-first output (no write to disk; responses may include content_base64 when no directory is set). Set only if the user wants a saved image. |
output_format | Default svg is usually best for URLs; use png/pdf/jpeg/txt only if valid for that type (see uml://formats). |
theme | PlantUML types only; omit otherwise. |
scale | SVG only; optional size multiplier. |
After generating
- If the result includes
error, fix code or diagram_type / output_format and retry (or run validate_uml again).
- Present clearly:
url — primary Kroki link to the rendered diagram.playground — if present, link for interactive editing.local_path — only when output_dir was set.
- Keep a short copy of the
code in the reply so the user can edit and regenerate.
Choosing a language from intent
| User intent | Typical diagram_type |
|---|
| Classes, associations, packages | class (PlantUML) or mermaid with classDiagram |
| Messages over time, lifelines | sequence or Mermaid sequence |
| Flows, swimlanes, BPMN | activity, bpmn, or Mermaid flowchart |
| Components, deployment | component, deployment, or C4-style types if listed in uml://types |
| Quick graphs, Gantt, pie | mermaid |
| Declarative layout / modern DSL | d2 |
| ASCII box drawings, monospace diagrams | ditaa or svgbob (still use generate_uml with that diagram_type) |
When several types fit, pick the one the user named; otherwise prefer the type with the clearest template in uml://templates.
MCP tools and resources
- Tools:
generate_uml, validate_uml, list_diagram_types, generate_uml_batch
- Resources:
uml://types, uml://formats, uml://templates, uml://examples, uml://capabilities, uml://recipes, uml://server-info, uml://workflow, plus type-specific URIs from resources/list (named Mermaid samples, BPMN guide, …)
Prompts (when the client exposes them): uml_diagram, uml_diagram_with_thinking, and type-specific prompts (class_diagram, sequence_diagram, activity_diagram, usecase_diagram, mermaid_sequence_api, mermaid_gantt, bpmn_process_guide, c4_model, wireviz_harness, bpmn_executable_process, convert_class_to_mermaid, algorithm_explainer, paper_concept_diagram) help structure code before generate_uml.
Always use the MCP tool/resource APIs exposed in the environment; do not guess unsupported diagram_type or output_format values when unsure—confirm with uml://types / uml://formats.
