Vgraph MCP Server

Create a CLD diagram as PNG image. A Causal Loop Diagram (CLD) is a Systems Thinking tool that maps feedback loops between variables, showing how a change in one variable causes changes in others. It reveals reinforcing dynamics (exponential growth or decline) and balancing dynamics (stabilisation toward equilibrium). You provide VGL (Vithanco Graph Language) code using the CLD notation and the tool renders it to an PNG image. ## Core Concepts A CLD consists of **variables** (called Stocks) connected by **causal links** with polarity: - **same** (`s`): when A increases, B increases; when A decreases, B decreases. Drawn as a solid arrow. - **opposite** (`o`): when A increases, B decreases; when A decreases, B increases. Drawn as a dashed arrow. A **feedback loop** is a closed chain of causal links returning to the starting variable: - **Reinforcing loop (R)**: even number of `opposite` edges (including zero). Drives exponential growth or decline — a snowball effect. - **Balancing loop (B)**: odd number of `opposite` edges. Drives the system toward equilibrium — a thermostat effect. ## How to Build a CLD 1. Identify the key variables (stocks) in the system — things whose value can increase or decrease. 2. For each pair of causally related variables, determine the polarity: does an increase in A cause B to increase (same) or decrease (opposite)? 3. Trace closed loops and classify them as reinforcing or balancing using the counting rule. 4. Give the diagram a title that frames the system boundary. ## VGL Syntax ``` vgraph <id>: CLD "<title>" { <nodes and edges> } ``` ### Node Types - `Stock` — A quantity or state in the system. Stock values change over time based on incoming causal links. ``` node <id>: Stock "<label>" ``` ### Edges - `same` — Positive causal link — both stocks change in the same direction. If the source increases, the target increases too. Marked with '+'. - `opposite` — Negative causal link — the stocks change in opposite directions. If the source increases, the target decreases. Marked with '−'. CRITICAL: You MUST specify the edge type (`: same` or `: opposite`) on every edge. Both edge types connect Stock to Stock, so the type CANNOT be inferred — omitting it will cause an error. ``` edge <from_id> -> <to_id>: same edge <from_id> -> <to_id>: opposite ``` ## Identifying Feedback Loops To classify a loop, trace a closed path back to the starting variable and count the `opposite` edges: - **0 opposite edges** → Reinforcing (R): Population → Birth Rate → Population (more people → more births → even more people) - **1 opposite edge** → Balancing (B): Population → Death Rate → Population (more people → more deaths → fewer people) Rule: even count = reinforcing, odd count = balancing. ## Complete Example ``` vgraph populationCLD: CLD "Population Dynamics" { node population: Stock "Population" node births: Stock "Birth Rate" node deaths: Stock "Death Rate" node resources: Stock "Available Resources" edge population -> births: same edge births -> population: same edge population -> deaths: same edge deaths -> population: opposite edge population -> resources: opposite edge resources -> births: same } ``` **Loop analysis:** - **R1 (Reinforcing):** Population → Birth Rate → Population — 0 opposite edges. More people produce more births, which increases population. Growth spiral. - **B1 (Balancing):** Population → Death Rate → Population — 1 opposite edge. More people means more deaths, which reduces population. Death regulation. - **B2 (Balancing):** Population → Available Resources → Birth Rate → Population — 1 opposite edge (population → resources). More people deplete resources, reducing birth rate. Resource constraint. ## Rules 1. ALWAYS specify the edge type (`: same` or `: opposite`) — it cannot be inferred 2. Stock labels should be nouns or noun phrases representing measurable quantities that can increase or decrease (e.g. "Population", "Revenue", "Stress Level" — not "People are born" or "Increasing") 3. Every Stock MUST connect to at least one other Stock — no isolated variables 4. Think in terms of "if A increases, what happens to B?" to determine same vs opposite polarity 5. Use meaningful IDs (population, revenue, stress — not n1, n2, n3) 6. Keep the diagram focused on one system — the title should frame the boundary 7. Aim for closed loops — a CLD without any feedback loop is just a causal chain and misses the point of systems thinking 8. Prefer 3–6 variables per loop for clarity — larger loops are hard to trace and verify

Create a ConceptMap diagram as PNG image. A Concept Map defines the vocabulary of a domain through falsifiable propositions. It helps people align on exact wordings and shared understanding by stating facts as simple, readable sentences. You provide VGL (Vithanco Graph Language) code using the ConceptMap notation and the tool renders it to an PNG image. ## How to Build a Concept Map 1. Start with a Guiding Question (used as the graph title) — it determines what belongs on the map. 2. List all relevant concepts. 3. Connect every concept through relations. ALWAYS form readable propositions. 4. NEVER leave a concept unconnected. Every concept MUST connect to at least one relation. 5. Reuse relations when multiple concepts share the same relationship. ## VGL Syntax ``` vgraph <id>: ConceptMap "<Guiding Question>" { <nodes and edges> } ``` ### Node Types - `Concept` — A noun or term placed in relation to others. Concepts are connected through Relations to form falsifiable propositions. - `EmphasizedConcept` — A highlighted concept to draw attention to key terms. Use sparingly for maximum impact. - `Relation` — A verb or linking phrase connecting two concepts. Together with source and target, forms a falsifiable proposition. ``` node <id>: Concept "<label>" node <id>: EmphasizedConcept "<label>" node <id>: Relation "<label>" ``` ### Edges Valid connections: - Concept → Relation — A Concept connects to a Relation, forming the source of a proposition. - Relation → Concept — A Relation points to a Concept, completing the proposition. - EmphasizedConcept → Relation — An Emphasized Concept connects to a Relation, forming the source of a proposition. - Relation → EmphasizedConcept — A Relation points to an Emphasized Concept, completing the proposition. ``` edge <from_id> -> <to_id> ``` ALWAYS form the pattern: Concept -> Relation -> Concept. This creates a readable proposition. ## Reusing Relations When multiple concepts share the same relationship, reuse a single Relation node. No duplicate edges when reusing — create edges only where needed: **Multiple sources, one target:** ``` vgraph animals: ConceptMap "What are common pets?" { node dog: Concept "Dog" node cat: Concept "Cat" node isa: Relation "is a" node mammal: Concept "Mammal" edge dog -> isa edge cat -> isa edge isa -> mammal // Only ONE edge from relation to target } ``` Both "Dog is a Mammal" and "Cat is a Mammal" share one Relation node — only 4 nodes total. **One source, multiple targets:** ``` vgraph typography: ConceptMap "What defines a font?" { node font: Concept "Font" node has: Relation "has" node weight: Concept "Weight" node style: Concept "Style" edge font -> has // Only ONE edge from source to relation edge has -> weight edge has -> style } ``` Both "Font has Weight" and "Font has Style" share one Relation node — only 4 nodes total. **CRITICAL — Multiple inbound AND multiple outbound edges:** When a relation has BOTH multiple inbound edges (concepts pointing TO the relation) AND multiple outbound edges (relation pointing TO concepts), ALL inbound concepts must make sense as propositions with ALL outbound concepts. With n inbound and m outbound edges, you get n × m propositions — all must be valid. **Invalid example:** ``` vgraph learning: ConceptMap "What enables growth?" { node learning: Concept "Learning" node accountability: Concept "Accountability" node enables: Relation "enables" edge learning -> enables edge accountability -> enables edge enables -> learning edge enables -> accountability } ``` This creates 4 propositions (2 × 2): - Learning enables Learning ❌ (circular) - Learning enables Accountability ✓ - Accountability enables Learning ✓ - Accountability enables Accountability ❌ (circular) **Fix — Use specific relations:** ``` vgraph learning: ConceptMap "What enables growth?" { node learning: Concept "Learning" node accountability: Concept "Accountability" node facilitates: Relation "facilitates" node requires: Relation "requires" edge accountability -> facilitates edge facilitates -> learning edge learning -> requires edge requires -> accountability } ``` Now: "Accountability facilitates Learning" ✓ and "Learning requires Accountability" ✓ **Fix — Restructure:** ``` vgraph learning: ConceptMap "What enables growth?" { node learning: Concept "Learning" node accountability: Concept "Accountability" node environment: Concept "Environment" node creates: Relation "creates" edge learning -> creates edge accountability -> creates edge creates -> environment } ``` Now: "Learning creates Environment" ✓ and "Accountability creates Environment" ✓ ## Complete Example ``` vgraph learningCM: ConceptMap "What is Learning?" { node student: Concept "Student" node subject: Concept "Subject" node practice: EmphasizedConcept "Practice" node understanding: Concept "Understanding" node resources: Concept "Resources" node learns: Relation "learns" node requires: Relation "requires" node leads_to: Relation "leads to" node uses: Relation "uses" edge student -> learns edge learns -> subject edge subject -> requires edge requires -> practice edge practice -> leads_to edge leads_to -> understanding edge subject -> uses edge uses -> resources } ``` Propositions: Student learns Subject, Subject requires Practice, Practice leads to Understanding, Subject uses Resources. ## Rules 1. ALWAYS form readable propositions — every Concept -> Relation -> Concept chain MUST read as a natural, falsifiable sentence 2. NEVER leave a concept unconnected 3. **Concept labels are nouns** — concept labels should be nouns or noun phrases (things, ideas, entities), not actions, sentences, or verb phrases. Use "Understanding" not "How we understand things" 4. **Verb agreement** — Relation labels must match the subject's number: singular concepts (e.g., "Student", "Dog") use singular verbs ("requires", "is", "has"); plural concepts (e.g., "LLMs", "Dogs") use plural verbs ("require", "are", "have"). For mixed cases, use infinitive form without "(s)": "enable" not "enables", "prevent" not "prevents". The notation "Dog(s)" in concept labels can indicate the concept works in both forms, then use infinitive verb forms. 5. **Guiding question as filter** — the guiding question determines what belongs on the map. Every concept MUST help answer it. If a concept does not contribute to answering the guiding question, it does not belong. 6. **Relationship diversity** — use diverse relation types (not all "is a" or "has"). Avoid simple opposite pairs (e.g. "is parent of" / "is child of" are the same relationship stated twice in different directions). Use different verbs that reveal distinct aspects of how concepts relate. 7. **Rich connectivity** — every concept should connect to at least 2 others via different relations. Aim for a network structure where multiple paths exist between concepts — not a chain (linear A→B→C) or a spoke (one central concept with everything hanging off it). 8. Use meaningful IDs (student, practice — not n1, n2) 9. Keep relation labels short (verbs or short phrases) 10. Use EmphasizedConcept sparingly 11. **Introduce abbreviations** — if a concept label uses an abbreviation, spell out the full term first: e.g. "Gross National Product (GNP)", not just "GNP"

Decompose a node into a detailed node and return the updated VGL document. Only a node whose type has a detailing can be decomposed; `describe_notation` lists them. The node keeps its id, type, label and attributes and becomes a group holding new details, one per edge, so every edge keeps its id and label and now ends at a detail. Rename and retype the new details afterwards.

Return the self-describing Markdown document for a built-in VGraph notation. The document includes the notation's purpose, when to use it, node types, edge types, group types, detailings (which node types can be decomposed and what goes inside them), history, and references.

Create a IBIS diagram as PNG image. IBIS (Issue-Based Information System) maps out any decision, discussion, or thought process using just four node types: Questions, Answers (Ideas), Pros, and Cons. Attaching Questions to any node lets you drill into any aspect at any depth. You provide VGL (Vithanco Graph Language) code using the IBIS notation and the tool renders it to an PNG image. ## How to Build an IBIS Diagram 1. Start with a root Question (used as the graph title). 2. Add Answers (Ideas) that respond to the question. 3. Add Pro and Con arguments for each answer. 4. Attach further Questions to any node to drill deeper. 5. Keep going until the topic is explored to the depth you need. ## VGL Syntax ``` vgraph <id>: IBIS "<title>" { <nodes and edges> } ``` ### Node Types - `Question` — Questions are the key driver of IBIS. They are the starting point and can be connected to all other node types. - `Answer` — An idea or answer for a question. Answers are evaluated through pro and con arguments. - `Pro` — An argument in favour of an answer. Pros help evaluate and decide between competing answers. - `Con` — An argument against an answer. Cons help evaluate and decide between competing answers. ``` node <id>: Question "<label>" node <id>: Answer "<label>" node <id>: Pro "<label>" node <id>: Con "<label>" ``` ### Edges Edge types are inferred from node types — just write `edge <from> -> <to>`. Valid connections: - Question → Question — A question can raise a further question, enabling infinite depth of inquiry. - Answer → Question — An answer can raise a further question — e.g., to probe its assumptions. - Pro → Question — A pro argument can raise a further question — e.g., to test its validity. - Con → Question — A con argument can raise a further question — e.g., to explore how to overcome it. - Question → Answer — A question is answered by this idea or answer. - Answer → Pro — This answer is supported by a pro argument. - Answer → Con — This answer is objected to by a con argument. ``` edge <from_id> -> <to_id> ``` ## The Drill-Down Mechanism The power of IBIS is that you can attach a Question to **any** node type: - Question a Question: "Shouldn't we rather discuss X?" - Question an Answer: "What would we need to implement this?" - Question a Pro: "Is this advantage really significant?" - Question a Con: "Can we mitigate this disadvantage?" Each sub-question starts its own Answer/Pro/Con branch, allowing unlimited depth. ## Complete Example ``` vgraph techChoice: IBIS "Which database should we use?" { node q1: Question "Which database should we use?" node a1: Answer "PostgreSQL" node a2: Answer "MongoDB" edge q1 -> a1 edge q1 -> a2 node pro1: Pro "ACID compliance" node pro2: Pro "Mature ecosystem" node con1: Con "Schema migrations can be complex" edge a1 -> pro1 edge a1 -> pro2 edge a1 -> con1 node pro3: Pro "Flexible schema" node con2: Con "Weaker transaction support" edge a2 -> pro3 edge a2 -> con2 node q2: Question "How to handle schema migrations?" edge con1 -> q2 node a3: Answer "Use Flyway or Liquibase" edge q2 -> a3 node pro4: Pro "Industry-standard tooling" edge a3 -> pro4 } ``` ## Rules 1. ALWAYS start with a root Question — it frames the entire diagram 2. Follow the structure: Question -> Answer -> Pro/Con 3. Use Questions to drill down — attach them to any node that needs exploration 4. Keep labels concise — Questions as questions, Answers as noun phrases, Pros/Cons as short statements 5. Use meaningful IDs (q1, mainIdea, costCon — not n1, n2, n3) 6. Each Answer should have at least one Pro or Con to be useful 7. Avoid orphan nodes — every node must connect to the tree

Create a Timeline diagram as PNG image. A Timeline visualises events over time, optionally across multiple parallel tracks (groups). The default layout is left-to-right but can be changed to any direction. The base notation provides generic TimePoint and Event types — use `vnotation extends Timeline` to define domain-specific event types (e.g. Battle, Treaty, Release, Incident) with custom colours and categories. You provide VGL (Vithanco Graph Language) code using the Timeline notation and the tool renders it to an PNG image. ## Core Concept: alignGroup The key mechanism is the `alignGroup` attribute. Nodes sharing the same `alignGroup` value are placed at the same position in the layout — pinned to the same column (left-to-right) or the same row (top-to-bottom). This is what creates time alignment. ``` node t1800: TimePoint "1800" [alignGroup: "1800"] node e1: Event "Something happened" [alignGroup: "1800"] ``` These two nodes will appear at the same horizontal position because they share alignGroup "1800". ## How to Build a Timeline 1. Choose a title that describes the scope of the timeline. 2. Decide whether you need TimePoints (axis markers) or whether alignGroup alone suffices. 3. Add Events for things that happened, each with an `alignGroup` matching its time. 4. Use `sequence` edges between TimePoints to form the visible time axis. 5. Use `influence` edges between Events to show causal or contextual links. 6. Optionally use groups to create named parallel tracks (countries, teams, systems). ## VGL Syntax ``` vgraph <id>: Timeline "<title>" { <nodes, edges, and groups> } ``` ### Node Types - `TimePoint` — A marker on the time axis labelling a point in time (e.g., '1805', 'Q3 2025'). Defines the temporal structure of the diagram. - `Event` — A generic event placed at a point in time. Extend with vnotation for domain-specific event types. ``` node <id>: TimePoint "<label>" [alignGroup: "<time_value>"] node <id>: Event "<label>" [alignGroup: "<time_value>"] ``` ALWAYS include `alignGroup` on every node to ensure correct time alignment. ### Edges - `sequence` — Links TimePoints in chronological order, creating the time axis. Rendered as a thin gray arrow. - `influence` — Shows a causal or dependency link between events. Dashed line that does not distort the layout alignment. `influence` can optionally carry a label. ``` edge <from_id> -> <to_id>: sequence edge <from_id> -> <to_id>: influence edge <from_id> -> <to_id>: influence "<label>" ``` ### Groups (Tracks) Groups create named parallel tracks rendered as labelled cluster boxes. Groups are optional. ``` group <id> "<label>" { node <id>: Event "<label>" [alignGroup: "<value>"] } ``` ## Changing Layout Direction The default is left-to-right. Use `vnotation extends Timeline` to change direction. All four directions are supported: `topToBottom`, `bottomToTop`, `leftToRight`, `rightToLeft`. ``` vnotation VerticalTimeline extends Timeline { layout: topToBottom } vgraph myTimeline: VerticalTimeline "My Timeline" { ... } ``` ## Custom Event Types with vnotation For domain-specific timelines, use `vnotation extends Timeline` to add custom node types, edge types, and change the layout — all in one block. The base TimePoint and Event types plus sequence and influence edges remain available. ``` vnotation WarTimeline extends Timeline { layout: topToBottom node type: Battle [nodeStyle: withCategory, color: "#883333", category: "Battle"] node type: Treaty [nodeStyle: withCategory, color: "#339933", category: "Treaty"] edge type: resolved_by from: Battle to: Treaty edge type: influenced from: Battle to: Battle } vgraph napoleonicWars: WarTimeline "Napoleonic Wars" { node t1805: TimePoint "1805" [alignGroup: "1805"] node t1812: TimePoint "1812" [alignGroup: "1812"] node t1815: TimePoint "1815" [alignGroup: "1815"] edge t1805 -> t1812: sequence edge t1812 -> t1815: sequence node f1: Battle "Battle of Austerlitz" [alignGroup: "1805"] node f2: Battle "Invasion of Russia" [alignGroup: "1812"] node f3: Battle "Battle of Waterloo" [alignGroup: "1815"] node e1: Treaty "Treaty of Pressburg" [alignGroup: "1805"] node e2: Treaty "Congress of Vienna" [alignGroup: "1815"] edge f1 -> e1: resolved_by edge f3 -> e2: resolved_by edge f1 -> f2: influenced "overconfidence" edge f2 -> f3: influenced "weakened army" } ``` ## Basic Example (without vnotation) ``` vgraph europe: Timeline "19th Century Europe" { node t1800: TimePoint "1800" [alignGroup: "1800"] node t1850: TimePoint "1850" [alignGroup: "1850"] node t1871: TimePoint "1871" [alignGroup: "1871"] edge t1800 -> t1850: sequence edge t1850 -> t1871: sequence group germany "Germany" { node g1: Event "Napoleon defeats Prussia" [alignGroup: "1800"] node g2: Event "German Unification" [alignGroup: "1871"] } group england "England" { node e1: Event "Industrial Revolution peaks" [alignGroup: "1850"] node e2: Event "Franco-Prussian War impact" [alignGroup: "1871"] } edge g1 -> g2: influence "led to" edge e1 -> e2: influence edge e1 -> g2: influence "industrialization enabled" } ``` ## Rules 1. ALWAYS use `alignGroup` on every node to ensure correct time alignment. 2. TimePoints are optional — alignGroup alone suffices for alignment. 3. Keep TimePoint labels short (dates, phase names). 4. Use influence edges sparingly — only for meaningful causal or contextual links. 5. Use meaningful IDs (t1800, battleOfWaterloo — not n1, n2). 6. Groups are optional — use them when you have distinct parallel tracks. 7. When you need domain-specific event types, use `vnotation extends Timeline` — don't overload the generic Event type. 8. When changing layout direction, always use `vnotation extends Timeline` with a `layout:` directive — the base Timeline is always left-to-right.