@achmadya-dev/mcp-diagram 0.3.0

package/dist/assets/shared/create-diagram-intro.md

@@ -0,0 +1,52 @@
+Creates and displays an interactive draw.io diagram. Accepts either draw.io XML or Mermaid.js syntax — provide exactly one.
+
+**Format decision — this is the first thing to settle before you write anything:** if the diagram type appears on the Mermaid list below, use `mermaid`. Only use `xml` when the diagram type isn't on that list (UI mockups, floorplans, cloud/network/electrical architecture with stencils, hand-placed UML, etc.) or when the user has explicitly asked for draw.io XML.
+
+**Use Mermaid** for the following diagram types (all rendered natively, no upstream mermaid runtime):
+
+- flowchart / graph (TD, LR, …)
+- sequenceDiagram
+- classDiagram
+- stateDiagram / stateDiagram-v2
+- erDiagram
+- gantt
+- pie
+- journey (user-journey)
+- gitGraph
+- mindmap
+- timeline
+- quadrantChart
+- xychart-beta
+- sankey-beta
+- requirementDiagram
+- C4Context / C4Container / C4Component
+- block-beta
+- architecture-beta
+- packet-beta
+- kanban
+- radar-beta
+- treemap-beta
+- treeview-beta (draw.io-specific)
+- venn (draw.io-specific) — syntax: `venn` then `set A ["Label"]` for each set, `union A,B` for declared overlaps (informational), and `text A` / `text A,B` followed by `["Region label"]` for text inside a region. Do NOT use `A AND B[...]` or `A["..."]` shorthand — those lines are ignored.
+- ishikawa (draw.io-specific)
+- zenuml
+
+**Strong default: use Mermaid for every diagram type on that list above.** Mermaid is simpler, more reliable, and the native Mermaid layout handles positioning and routing for you. For a flowchart, state diagram, sequence, ER, class, gantt, gitGraph, mindmap, etc. — reach for the `mermaid` parameter, not `xml`. Do not default to XML for flowcharts.
+
+**Use XML** when the diagram type isn't on the Mermaid list above OR when the user explicitly asks for XML / draw.io format. Typical cases where XML is the right choice:
+
+- **UI mockups / wireframes / screen designs** — buttons, form fields, sidebars, modal dialogs (`shape=mxgraph.bootstrap.*`, `shape=mxgraph.ios.*`, `shape=mxgraph.android.*`)
+- **Floor plans / seating charts / room layouts** — rooms, doors, furniture (`shape=mxgraph.floorplan.*`)
+- **Cloud architecture** with AWS / Azure / GCP / Kubernetes icons (`shape=mxgraph.aws4.*`, `shape=mxgraph.azure.*`, `shape=mxgraph.gcp2.*`, `shape=mxgraph.kubernetes.*`)
+- **Network topology** with Cisco / Rack / networking shapes (`shape=mxgraph.cisco*.*`, `shape=mxgraph.rack.*`, `shape=mxgraph.networking.*`)
+- **P&ID / electrical / engineering schematics** (`shape=mxgraph.pid2.*`, `shape=mxgraph.electrical.*`, `shape=mxgraph.mscae.*`)
+- **Swimlanes / pools** with custom colors and hand-placed contents
+- **UML class / component / deployment diagrams** where positioning carries meaning
+- **Venn diagrams, quadrant charts, concept maps** with custom regions — anything where hand-placed geometry is the point
+- **Any diagram requiring specific colors, fonts, stencils, or layouts** that Mermaid can't control precisely
+
+Call `search_shapes` first when you need industry icons (AWS / Azure / Cisco / P&ID / Kubernetes / floorplan / mockup / electrical) to find the correct `style` string for each shape.
+
+**User preference override — XML only.** If the user expresses a preference for draw.io XML over Mermaid in any phrasing (examples: "no mermaid", "skip mermaid", "use xml", "I want drawio format", "stop using mermaid", "give me the xml", "native drawio only", etc.), from that point onward in the conversation you MUST use the `xml` parameter exclusively and MUST NOT use the `mermaid` parameter, even for diagram types where Mermaid would normally be preferable. This preference persists for the remainder of the conversation unless the user clearly reverses it (e.g. "mermaid is fine again"). When the preference is active, translate any diagram request — including flowcharts, sequence diagrams, ER diagrams, etc. — directly to well-formed mxGraphModel XML.
+
+When using XML: IMPORTANT — the XML must be well-formed. Do NOT include ANY XML comments (`<!-- -->`) in the output.

package/dist/assets/shared/mermaid-reference.md

@@ -0,0 +1,473 @@
+# Mermaid Reference
+
+Short hints for generating Mermaid diagrams that render correctly in draw.io. draw.io's Mermaid parser covers 28 diagram types — the header keyword on the first non-directive line selects the type.
+
+_Canonical list & dialog/ELK docs: <https://github.com/jgraph/drawio/discussions/5643>._
+
+## General rules
+
+- **Pick the type keyword carefully.** `graph`/`flowchart`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `sequenceDiagram`, `gitGraph`, `journey`, `pie`, `gantt`, `mindmap`, `timeline`, `quadrantChart`, `requirementDiagram`, `sankey-beta`, `xychart-beta`, `block-beta`, `c4Context`/`C4Container`/`C4Component`, `architecture-beta`, `radar-beta`, `packet-beta`, `venn-beta`, `treemap-beta`, `treeView-beta`, `ishikawa-beta`, `kanban`, `zenuml`, `wardley-beta`, `eventmodeling`. Misspelling the header yields a blank diagram.
+- **No trailing punctuation on node IDs.** IDs are identifiers (`myNode`, `node_1`, `A`) — spaces, hyphens (in some contexts), and reserved words (`end`, `class`, `subgraph`) break the parse. Put display text in brackets or quotes instead: `A["User's Account"]`.
+- **One statement per line.** Separate statements with newlines; `;` works as a delimiter in flowchart but not everywhere.
+- **Quote labels with special characters** (`:`, `-`, parentheses, non-ASCII). Use `"` not `'`.
+- **HTML in labels:** only `<br>`, `<b>`, `<i>`, `<u>` are reliable across types. Use `#` for hex colors in styles, never `rgb()`.
+- **Diagrams can take a title block** for some types:
+  ```
+  ---
+  title: My Diagram
+  ---
+  flowchart TD
+  ```
+- **Match the language of labels to the user's language** — if the user writes in German, French, etc., the diagram labels should be in that language too.
+
+## Flowchart (most common)
+
+```
+flowchart TD
+  A[Start] --> B{Decision?}
+  B -->|Yes| C[Do thing]
+  B -->|No| D[Skip]
+  C --> E((End))
+  D --> E
+```
+
+- **Direction:** `TD`/`TB` (top-down), `BT`, `LR`, `RL`.
+- **Node shapes by bracket:** `[rect]`, `(rounded)`, `([stadium])`, `[[subroutine]]`, `[(cylinder)]`, `((circle))`, `{rhombus}`, `{{hexagon}}`, `[/parallelogram/]`, `[\parallelogram alt\]`, `[/trapezoid\]`, `>asymmetric]`.
+- **Edges:** `-->` arrow, `---` no arrow, `-.->` dotted, `==>` thick, `<-->` bidirectional. Inline label: `A -- text --> B` or `A -->|text| B`.
+- **Subgraphs:**
+  ```
+  subgraph Frontend
+    A --> B
+  end
+  ```
+
+### Styling & colors
+
+Three ways — pick one, don't mix for the same node:
+
+**1. Inline per-node (`style`):**
+```
+flowchart LR
+  A[Start] --> B[End]
+  style A fill:#f9f,stroke:#333,stroke-width:2px,color:#fff
+  style B fill:#bbf,stroke:#f66,stroke-dasharray:5 5
+```
+
+**2. Reusable classes (`classDef` + `:::`):**
+```
+flowchart LR
+  A:::happy --> B:::sad
+  classDef happy fill:#dfd,stroke:#0a0
+  classDef sad fill:#fdd,stroke:#a00
+```
+Or apply to many: `class A,B,C happy`.
+
+**3. Link styling (edges):**
+```
+linkStyle 0 stroke:#f00,stroke-width:3px
+linkStyle default stroke:#999
+```
+`0` = first edge in order defined; `default` targets unstyled edges.
+
+Style properties that work: `fill`, `stroke`, `stroke-width`, `stroke-dasharray`, `color` (font color).
+
+## Sequence diagram
+
+```
+sequenceDiagram
+  participant U as User
+  participant S as Server
+  U->>S: Request
+  S-->>U: Response
+  Note right of S: Logged
+```
+
+- **Arrows:** `->` (no head), `->>` (arrow), `-->>` (dashed), `-x` (X end), `--x` (dashed X).
+- **Activate/deactivate:** `activate S` / `deactivate S` or `S->>+S2: call` / `S2-->>-S: return`.
+- **Blocks:** `alt/else/end`, `opt/end`, `loop/end`, `par/and/end`, `critical/option/end`.
+- **Notes:** `Note left of A`, `Note over A,B: text`.
+- Optional `autonumber` after header numbers the messages.
+
+## Class diagram
+
+```
+classDiagram
+  class Animal {
+    +String name
+    +int age
+    +eat() void
+  }
+  class Dog
+  Animal <|-- Dog : inherits
+  Dog "1" --> "*" Bone : has
+```
+
+- **Relations:** `<|--` inherit, `*--` composition, `o--` aggregation, `-->` association, `..>` dependency, `..|>` realize, `<-->` bidirectional.
+- **Visibility:** `+` public, `-` private, `#` protected, `~` package.
+- **Annotations:** `<<interface>>`, `<<abstract>>`, `<<enumeration>>` inside the class block or via `Animal <<interface>>`.
+- **Cardinality:** quoted strings flanking the arrow (`"1"`, `"0..*"`, `"*"`).
+
+## State diagram
+
+```
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Running : start
+  Running --> Idle : stop
+  Running --> [*]
+  state Running {
+    [*] --> Working
+    Working --> Waiting : block
+    Waiting --> Working : unblock
+  }
+```
+
+- Use `stateDiagram-v2`, not `stateDiagram` (v1 is legacy).
+- `[*]` = start (source) or end (target) depending on direction.
+- `state X { ... }` nests a compound state; `state fork1 <<fork>>`, `<<join>>`, `<<choice>>` mark junction nodes.
+- Transition labels: `A --> B : event [guard] / action`.
+
+## ER diagram
+
+```
+erDiagram
+  CUSTOMER ||--o{ ORDER : places
+  ORDER ||--|{ LINE-ITEM : contains
+  CUSTOMER {
+    string name
+    string email PK
+  }
+```
+
+- **Cardinality symbols:** `|o` zero-or-one, `||` exactly-one, `}o` zero-or-many, `}|` one-or-many. Mirror on both sides (e.g., `||--o{`).
+- Attribute blocks list `type name [PK|FK|UK]` plus optional comment in quotes.
+- Entity names are typically UPPERCASE by convention.
+
+## Journey
+
+```
+journey
+  title Morning routine
+  section Wake up
+    Coffee: 5: Me
+    Read news: 3: Me
+  section Commute
+    Drive: 2: Me, Traffic
+```
+
+Each task: `Name: score(1-5): Actor[, Actor...]`. Section headers group tasks.
+
+## Pie
+
+```
+pie showData title Browser share
+  "Chrome" : 60
+  "Firefox" : 20
+  "Safari" : 20
+```
+
+`showData` is optional (renders the numbers). Quotes on labels, colon, numeric value.
+
+## Gantt
+
+```
+gantt
+  title Project timeline
+  dateFormat YYYY-MM-DD
+  section Phase 1
+  Design : a1, 2025-01-01, 7d
+  Build  : after a1, 14d
+  section Phase 2
+  Test   : 2025-01-25, 5d
+```
+
+- `dateFormat` is mandatory.
+- Task line: `Name : [id,] [after id | YYYY-MM-DD], duration[d/w]`.
+- Status tags: `done`, `active`, `crit` before the id (`crit a1`).
+
+## Gitgraph
+
+```
+gitGraph
+  commit
+  branch develop
+  checkout develop
+  commit
+  commit
+  checkout main
+  merge develop
+```
+
+Commands: `commit [id: "x"] [tag: "v1"]`, `branch name`, `checkout name`, `merge name`, `cherry-pick id: "x"`.
+
+## Mindmap
+
+```
+mindmap
+  root((Project))
+    Frontend
+      React
+      CSS
+    Backend
+      Node
+      DB
+```
+
+- Indentation (2-space increments) defines hierarchy.
+- Root shape: `((circle))`, `[rect]`, `(rounded)`, `))cloud((`, `)hexagon(`, `{{hexagon}}`.
+- No edges — they are implied by nesting.
+
+## Timeline
+
+```
+timeline
+  title Company history
+  section 2020s
+    2021 : Founded
+    2022 : Series A
+         : Launched product
+  section 2030s
+    2030 : IPO
+```
+
+Colon separates year/label; multiple `:` lines under one year add sub-events.
+
+## Quadrant chart
+
+```
+quadrantChart
+  title Reach vs Engagement
+  x-axis Low --> High
+  y-axis Low --> High
+  quadrant-1 Stars
+  quadrant-2 Question Marks
+  quadrant-3 Dogs
+  quadrant-4 Cash Cows
+  Campaign A: [0.3, 0.6]
+  Campaign B: [0.75, 0.85]
+```
+
+Point coords are `[0..1, 0..1]`.
+
+## Requirement diagram
+
+```
+requirementDiagram
+  requirement req1 {
+    id: "1"
+    text: "The system shall..."
+    risk: high
+    verifymethod: test
+  }
+  element user_story {
+    type: "story"
+  }
+  user_story - satisfies -> req1
+```
+
+Requirement types: `requirement`, `functionalRequirement`, `performanceRequirement`, `interfaceRequirement`, `physicalRequirement`, `designConstraint`. Relations: `contains`, `copies`, `derives`, `satisfies`, `verifies`, `refines`, `traces`.
+
+## Sankey
+
+```
+sankey-beta
+Source,Intermediate,10
+Source,Direct,5
+Intermediate,Sink,10
+```
+
+CSV-style: `source,target,value`. No header. No `title` (use frontmatter).
+
+## XY chart
+
+```
+xychart-beta
+  title "Revenue"
+  x-axis [jan, feb, mar, apr]
+  y-axis "USD" 0 --> 10000
+  bar [2500, 5000, 7500, 9000]
+  line [3000, 4500, 6500, 8500]
+```
+
+`bar [...]` and `line [...]` can stack; order matters (later overlays earlier).
+
+## Block
+
+```
+block-beta
+  columns 3
+  A B C
+  D["Wide"]:2 E
+  A --> D
+```
+
+`columns N` sets grid width. `Name:N` spans N columns. Edges use flowchart arrow syntax.
+
+## C4
+
+```
+C4Context
+  Person(user, "User")
+  System(app, "App", "Does things")
+  Rel(user, app, "Uses")
+```
+
+- Variants: `C4Context`, `C4Container`, `C4Component`, `C4Dynamic`, `C4Deployment`.
+- Element helpers: `Person`, `System`, `System_Ext`, `Container`, `ComponentDb`, `Boundary(id, "label", "type")`, etc. Arguments are positional: `(id, label, [type/tech], [description])`.
+- `UpdateElementStyle(tag, $bgColor="#…")` and `AddElementTag` tweak appearance.
+
+## Architecture
+
+```
+architecture-beta
+  group cloud(cloud)[Cloud]
+  service api(server)[API] in cloud
+  service db(database)[DB] in cloud
+  api:R --> L:db
+```
+
+- Built-in icons: `cloud`, `server`, `database`, `disk`, `internet`. Suffix edge ends with `:T`, `:B`, `:L`, `:R` to pick the side.
+- `group id(icon)[Label]` then `in groupId` on services places nodes.
+
+## Radar
+
+```
+radar-beta
+  title Skills
+  axis js["JS"], py["Python"], go["Go"]
+  curve alice["Alice"]{80, 60, 70}
+  curve bob["Bob"]{50, 90, 65}
+```
+
+Axes and curves are positionally aligned — list values in axis order, 0–100.
+
+## Packet
+
+```
+packet-beta
+  0-15: "Source Port"
+  16-31: "Dest Port"
+  32-63: "Seq Number"
+```
+
+`start-end` (bit ranges) or single-bit `N`. Use a title frontmatter.
+
+## Venn
+
+```
+venn-beta
+  set A ["Set A"]
+  set B ["Set B"]
+  union A,B
+  text A ["only A"]
+  text A,B ["shared"]
+```
+
+Define every `union` combination whose region you plan to label. `text A,B [...]` places text in intersections.
+
+## Treemap
+
+```
+treemap-beta
+"Category"
+    "Leaf 1": 40
+    "Leaf 2": 60
+```
+
+Numbers are values (area-weighted). Indent (2+ spaces) for hierarchy.
+
+## Tree view
+
+```
+treeView-beta
+  "Root"
+    "Child 1"
+      "Grandchild"
+    "Child 2"
+```
+
+Pure indentation hierarchy, no numbers.
+
+## Ishikawa (fishbone)
+
+```
+ishikawa-beta
+  Main Problem
+    Category
+      Cause
+      Sub-cause
+    Another Category
+      Cause
+```
+
+First line after header is the problem; top-level indents are categories (Materials, Methods, Machinery, etc. — use whatever makes sense).
+
+## Kanban
+
+```
+kanban
+  todo[To Do]
+    task1[Write spec]@{ assigned: "Alice", priority: "High" }
+  doing[In progress]
+    task2[Build feature]
+  done[Done]
+```
+
+Columns are `id[Label]` at indent 0; cards are `id[Label]@{ metadata }` inside. Metadata keys: `assigned`, `priority` (`Very Low`/`Low`/`Medium`/`High`/`Very High`), `ticket`.
+
+## ZenUML
+
+```
+zenuml
+  @Actor User
+  @Boundary Web
+  @Control Service
+  User -> Web: request
+  Web -> Service: process()
+  Service -> Web: result
+```
+
+Participant roles: `@Actor`, `@Boundary`, `@Control`, `@Entity`, `@Database`. Messages use `->` with a colon-separated label. Supports `if/else`, `while`, `par` blocks like sequence diagrams.
+
+## Wardley map
+
+```
+wardley-beta
+  title Tea Shop
+  anchor Business [0.95, 0.63]
+  component Cup of Tea [0.79, 0.61]
+  component Kettle [0.43, 0.35] (inertia)
+  Business -> Cup of Tea
+  Cup of Tea -> Kettle
+  evolve Kettle 0.62
+```
+
+- Header `wardley` or `wardley-beta`; `title` optional.
+- `anchor`/`component Name [visibility, evolution]` — coords are `[0..1, 0..1]` (y = value-chain visibility, x = evolution from Genesis to Commodity).
+- Component evolution markers in parens: `(inertia)`, `(build)`, `(buy)`, `(outsource)`, `(market)`.
+- Links: `A -> B` dependency, `A +> B` flow. `evolve Name <x>` adds an evolution target; `evolution Genesis -> Custom -> Product -> Commodity` relabels the x-axis stages.
+- Extras: `note "text" [x,y]`, `annotation N,[x,y] "text"`, `accelerator`/`deaccelerator "text" [x,y]`.
+
+## Event Modeling
+
+```
+eventmodeling
+  tf 01 ui CartUI
+  tf 02 cmd AddItem
+  tf 03 evt ItemAdded
+  tf 04 rmo Cart
+```
+
+- Each `tf <id> <type> <Name>` is a time-frame (column). Types: `ui` / `pcr` (processor), `cmd` / `command`, `rmo` / `readmodel`, `evt` / `event` — placed on the UI/Automation, Command/Read-Model, and Events swimlanes.
+- Wire frames with `->>`: `tf 04 evt ItemChanged ->> 02 ->> 03` links frame 04 back to 02 and 03.
+- `Namespace.Name` groups frames into slices (e.g. `Order.ChangeOrder`).
+- `data <id> { ... }` blocks attach payloads, referenced inline with `[[id]]`: `tf 02 cmd AddItem [[AddItem01]]`.
+
+## When to prefer XML over Mermaid
+
+- Precise positions / custom coordinates.
+- draw.io-native shapes (AWS, Azure, GCP, P&ID, Cisco, electrical).
+- Mixed shape libraries or complex multi-layer diagrams.
+- Anything that needs exact colors per element with many variations — Mermaid's styling works but at scale XML is easier to reason about.
+
+Default to Mermaid for the standard types above; reach for XML only when Mermaid's syntax clearly can't express what's needed.