vgraph-mcp
Server Details
Concept Maps, IBIS, Causal Loop Diagrams and Timelines as images. Runs locally via WebAssembly.
The last two health checks of this connector failed. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
- Status
- Unhealthy
- Uptime
- 0.0% over the last 24 hours
- Last Tested
- Transport
- Streamable HTTP · MCP 2025-11-25
- URL
- Repository
- Vithanco/VGraph
- GitHub Stars
- 0
- ChatGPT
- –
- Claude
- –
TDQS
Scored across 6 tools
The four create_* tools target entirely distinct diagram notations (CLD, ConceptMap, IBIS, Timeline) with no purpose overlap, and decompose and describe_notation are clearly separate meta-operations. describe_notation even helps resolve which notation/tooling applies, reinforcing clarity.
All names use consistent snake_case, and four tools follow the create_noun pattern (create_cld, create_concept_map, create_ibis, create_timeline). The only minor deviation is decompose, which is a bare verb without a noun object, though it remains readable and predictable.
Six tools is well-scoped: one per supported notation plus two infrastructure helpers (describe_notation, decompose). Each earns its place, and splitting the notations into separate create tools is justified by their distinct VGL syntaxes rather than redundancy.
The set covers creation for four notations, plus introspection (describe_notation) and structural editing (decompose), which is solid lifecycle coverage. Minor gaps exist: no generic render/validate path for raw VGL or a notation-listing tool, but agents can work around these via the provided create tools.
Available Tools
6 toolscreate_cldAInspect
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
oppositeedges (including zero). Drives exponential growth or decline — a snowball effect.Balancing loop (B): odd number of
oppositeedges. Drives the system toward equilibrium — a thermostat effect.
How to Build a CLD
Identify the key variables (stocks) in the system — things whose value can increase or decrease.
For each pair of causally related variables, determine the polarity: does an increase in A cause B to increase (same) or decrease (opposite)?
Trace closed loops and classify them as reinforcing or balancing using the counting rule.
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>: oppositeIdentifying 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
ALWAYS specify the edge type (
: sameor: opposite) — it cannot be inferredStock 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")
Every Stock MUST connect to at least one other Stock — no isolated variables
Think in terms of "if A increases, what happens to B?" to determine same vs opposite polarity
Use meaningful IDs (population, revenue, stress — not n1, n2, n3)
Keep the diagram focused on one system — the title should frame the boundary
Aim for closed loops — a CLD without any feedback loop is just a causal chain and misses the point of systems thinking
Prefer 3–6 variables per loop for clarity — larger loops are hard to trace and verify
Inputs: vgl (required).
create_concept_mapAInspect
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
Start with a Guiding Question (used as the graph title) — it determines what belongs on the map.
List all relevant concepts.
Connect every concept through relations. ALWAYS form readable propositions.
NEVER leave a concept unconnected. Every concept MUST connect to at least one relation.
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
ALWAYS form readable propositions — every Concept -> Relation -> Concept chain MUST read as a natural, falsifiable sentence
NEVER leave a concept unconnected
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"
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.
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.
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.
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).
Use meaningful IDs (student, practice — not n1, n2)
Keep relation labels short (verbs or short phrases)
Use EmphasizedConcept sparingly
Introduce abbreviations — if a concept label uses an abbreviation, spell out the full term first: e.g. "Gross National Product (GNP)", not just "GNP"
Inputs: vgl (required).
create_ibisAInspect
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
Start with a root Question (used as the graph title).
Add Answers (Ideas) that respond to the question.
Add Pro and Con arguments for each answer.
Attach further Questions to any node to drill deeper.
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
ALWAYS start with a root Question — it frames the entire diagram
Follow the structure: Question -> Answer -> Pro/Con
Use Questions to drill down — attach them to any node that needs exploration
Keep labels concise — Questions as questions, Answers as noun phrases, Pros/Cons as short statements
Use meaningful IDs (q1, mainIdea, costCon — not n1, n2, n3)
Each Answer should have at least one Pro or Con to be useful
Avoid orphan nodes — every node must connect to the tree
Inputs: vgl (required).
create_timelineAInspect
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
Choose a title that describes the scope of the timeline.
Decide whether you need TimePoints (axis markers) or whether alignGroup alone suffices.
Add Events for things that happened, each with an
alignGroupmatching its time.Use
sequenceedges between TimePoints to form the visible time axis.Use
influenceedges between Events to show causal or contextual links.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
ALWAYS use
alignGroupon every node to ensure correct time alignment.TimePoints are optional — alignGroup alone suffices for alignment.
Keep TimePoint labels short (dates, phase names).
Use influence edges sparingly — only for meaningful causal or contextual links.
Use meaningful IDs (t1800, battleOfWaterloo — not n1, n2).
Groups are optional — use them when you have distinct parallel tracks.
When you need domain-specific event types, use
vnotation extends Timeline— don't overload the generic Event type.When changing layout direction, always use
vnotation extends Timelinewith alayout:directive — the base Timeline is always left-to-right.
Inputs: vgl (required).
decomposeAInspect
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.
Inputs: vgl (required), node (required).
describe_notationAInspect
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.
Inputs: notation (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Flowcharts, UML/ER diagrams, mind maps, infographics and SOPs as editable, presentable boards
Draw causal loop diagrams in the chat and edit them on a shared link.
Create and revise scientific and educational diagrams with ConceptViz.
Flowcharts that people and agents edit together on one live canvas, exported as Mermaid.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to build and update flowcharts, workflow maps, project plans, and research maps in a shared self-hosted workspace, with notes, sources, revision history, conflict detection, and JSON import/export.310 npm1MIT
- FlicenseNot gradedqualityAmaintenanceEnables agents to create, customize, analyze and export relationship diagrams — theorem dependencies, paper maps, task RACI, org charts, conversation graphs — through 25 MCP tools, with cycle detection, centrality bottleneck reports, dependency closure and Mermaid/DOT/Markdown/JSON interop. Graphs stay local-first in a diff-friendly JSON source of truth and can be refined on a visual canvas.1-
- FlicenseNot gradedqualityAmaintenanceEnables users to turn architecture into a queryable knowledge graph and produce editable, hand-drawn, auto-laid-out diagrams across 25 types, with natural-language revisions and SVG/PNG export. It runs fully offline without API keys.-
- AlicenseNot gradedqualityDmaintenanceA private-by-default, local-first DAG editor that lets you build causal diagrams visually, validate cycles, and save/export as JSON, SVG, or PNG through MCP tools.MIT
Glama MCP Gateway
Add one secure layer between your agents and this server.