Uml MCP Diagrams

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. .github/skills/uml-mcp-diagrams/SKILL.md (GitHub Copilot) must stay a byte-identical copy of this file.

uml-mcp diagram workflow

Goal

Turn the user’s intent into valid diagram_type + source code, call generate_uml (or generate_uml_image for chat-visible pictures), 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. When the user asks to show the diagram in chat, prefer generate_uml_image with output_format: png.

Positive patterns (do)

• Confirm types first when unsure: read uml://types / uml://formats or call list_diagram_types before generate_uml. Catalog includes ~37 Kroki-backed types (including goat, umlet).
• 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. Prefer strict: true for Mermaid sequence diagrams.
• Mermaid sequence: put each statement on its own line. Do not pack sequenceDiagram; participant A; A->>B: hi on one line — strict validation rejects that; flowcharts may still use end-of-statement ;.
• Return url, playground, and a short copy of code every time. Always format them as markdown links in the chat reply (see reply template). Never omit Playground when the tool returned it.
• For inline chat images, call generate_uml_image (png default). It fetches bytes even on hosted Vercel when MCP_URL_ONLY is on. generate_uml with output_format: png/jpeg also force-fetches. Tool text includes ![diagram](url), URL:, and Playground: for clients that do not attach ImageContent.
• 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.
• Do not pack Mermaid sequenceDiagram statements with ; on a single physical line.
• Prefer not to stampede Mermaid-heavy generate_uml_batch calls on hosted MCP (server caps concurrency when most items are Mermaid); recover failed Mermaid items with solo generate_uml.
• Do not embed local filesystem paths like output/foo.png in chat markdown; use MCP image content or the returned HTTPS URL.
• Do not invent diagram URLs or playground links — copy them from the MCP tool result only.

Before generating

1. If diagram_type is unknown or ambiguous, read uml://types (or uml://capabilities) to list valid types and supported backends.
2. 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.
3. 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.
4. 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:

1. 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.
2. 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. Mermaid: one statement per line.
• 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.

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.