Skip to main content
Glama
Sign In

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 — 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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "vgl": "<vgl>"
    },
    "name": "create_timeline"
  }
}

Input 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.3/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden and discloses substantial behavioral detail: output is a PNG image, default layout is left-to-right, alignGroup controls placement, and edge/group rendering styles are explained. It does not cover operational aspects such as file storage, overwrite behavior, auth, or error handling, but the rendering semantics are unusually well documented.

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

Conciseness4/5

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

The description is long but well structured with clear headings, examples, and rules, and the purpose is front-loaded. Some redundancy exists between the core concept, examples, and rules, but the length is largely justified by the complexity of the VGL Timeline notation.

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 absence of annotations and output schema, the description is remarkably complete for correct invocation. It covers purpose, syntax, required patterns, optional features, layout customization, and domain-specific extensions, leaving little ambiguity about how to construct the vgl argument.

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

Parameters5/5

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

Although the single vgl parameter has 100% schema description coverage, the description adds deep semantic meaning far beyond the schema. It explains the VGL syntax, node types, alignGroup, edges, groups, layout direction changes, custom vnotation extensions, and provides two complete examples.

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 begins with a specific verb and resource: 'Create a Timeline diagram as PNG image.' The tool is clearly distinguishable from siblings such as create_cld, create_concept_map, and create_ibis because it explicitly targets Timeline diagrams and the Timeline notation.

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

Usage Guidelines3/5

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

The description provides extensive guidance on how to build a Timeline, including when to use TimePoints, groups, and influence edges. However, it does not explicitly say when to choose create_timeline over sibling diagram tools, nor does it name alternatives or exclusions.

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