Skip to main content
Glama

vgraph-mcp

by com.vithanco
OverviewDiscussionsAdmin

create_timeline

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 — an axis marker (date, phase, milestone label). Small gray box. Optional.

  • Event — something that happened. Steel-blue rounded box.

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 — connects TimePoint to TimePoint, forming the time axis (solid gray arrow).

  • influence — connects Event to Event, showing causal or contextual links (dashed arrow, does not distort layout). Can have an optional 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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
vglYesValid VGL code using the Timeline notation. Either `vgraph <id>: Timeline "<title>" { ... }` directly, or a `vnotation <Name> extends Timeline { ... }` block followed by `vgraph <id>: <Name> "<title>" { ... }`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given no annotations, the description takes on the burden and covers behavior thoroughly: it explains the rendering process, output is PNG, core mechanisms like alignGroup, and constraints like 'ALWAYS include alignGroup on every node'. It also discloses extensibility (vnotation) and layout options. Minor gap: it doesn't explicitly state read-only or side effects, but since it's a create/render tool, that's implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very long (over 1000 words) with extensive code examples and detailed syntax. While it's well-structured with headers and examples, it goes beyond what's needed for an agent to understand the tool's purpose and usage. It could be more concise, for example, by linking to full documentation instead of restating all syntax. The 'should be front-loaded' principle is violated since the core concept comes after a fairly long introduction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of VGL and the absence of an output schema, the description is remarkably complete. It covers all aspects needed to successfully call the tool: syntax, node types, edges, groups, layout customization, custom types, and rules. It even provides multiple examples. For a tool that requires specialized domain language, this level of detail is necessary for correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single parameter (vgl). The description adds substantial value by explaining VGL syntax, node types, edges, and examples, going far beyond the schema's one-line description. However, since there's only one parameter and the schema already describes it, the baseline is 3, and the description's extensive syntax guidance adds value but isn't necessary for basic use.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: creating a Timeline diagram as a PNG from VGL code. It specifies the resource (Timeline diagram) and the output format, and differentiates from siblings by focusing on the Timeline notation and time-based visualization, which is distinct from concept maps or IBIS diagrams.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool: when creating a timeline to visualize events over time. It also gives detailed instructions on how to construct timelines, including step-by-step guidance and rules, which indirectly tells users when not to use it (e.g., for non-time-based relationships, use other diagram tools).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All vgraph-mcp toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources