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.

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.

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

Calling generate_uml_image

Use when the user wants the picture visible in chat (Cursor, Copilot, ChatGPT image-capable clients).

On hosted deployments with MCP_URL_ONLY=true, this tool still force-fetches rendered bytes so MCP ImageContent / content_base64 is present. Prefer this over asking the user to open a URL when they asked to “show” or “render in chat”.

generate_uml_batch

• Same per-item fields as generate_uml (no per-item output_dir).
• Env: MCP_BATCH_MAX_ITEMS (default 20), MCP_BATCH_CONCURRENCY (default 4, clamped 1–16).
• When a majority of items are Mermaid, the server caps workers at 2 to reduce Mermaid.ink stampedes on Vercel.
• Isolate failures per index; recover failed Mermaid items with solo generate_uml.

After generating

1. If the result includes error, fix code or diagram_type / output_format and retry (or run validate_uml again). If Mermaid PNG fails, retry with svg (URL + playground still useful) or confirm the server uses mermaid.ink /img/?type=png.
2. Present clearly in the chat reply (always as markdown links, never bare paths):
   • Diagram — show the MCP image / ![diagram](url) from the tool text.
   • URL — primary rendered diagram link (url).
   • Playground — interactive editor when playground is present (Mermaid → mermaid.live; PlantUML → plantuml.com). Required in the reply whenever the tool returned it.
   • local_path — only when output_dir was set.
3. Keep a short copy of the code in a fenced block so the user can edit and regenerate.

Reply template

![diagram](<url>)

- **URL:** <url>
- **Playground:** <playground>

\`\`\`mermaid
<code>
\`\`\`

Manual smoke prompts (ChatGPT / Cursor): tests/prompts/chatgpt_mcp_smoke_test.md.

Choosing a language from intent

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, generate_uml_image, 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.

Manual ChatGPT / Cursor smoke prompts: tests/prompts/chatgpt_mcp_smoke_test.md. Full Kroki catalog stress: tests/prompts/kroki_full_catalog_stress_test.md.

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.