Graph-Tools

dromologue/Graph-Tools

3.2

If you are the rightful owner of Graph-Tools and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Graph Tools is a comprehensive Ruby-based graph analysis toolkit with web visualizations and an MCP server for AI-powered graph analysis.

Tools

  1. analyze_relationships

    Extract relationships from structured data and create visualizations.

  2. create_adjacency_matrix

    Build matrices from relationship pairs.

  3. calculate_centrality

    Compute network centrality measures (degree, betweenness, closeness, eigenvector).

  4. analyze_network_structure

    Comprehensive network analysis combining relationship extraction and centrality.

Graph Tools - Interactive Graph Analysis Toolkit

A comprehensive Ruby-based graph analysis toolkit with web visualizations and MCP server for AI-powered graph analysis.

šŸš€ Features

Core Graph Operations

  • Adjacency Matrix Support - Load from CSV, JSON, or TXT files
  • Graph Algorithms - DFS, BFS, neighbor finding with visual feedback
  • Multiple Export Formats - CSV matrices, JSON, interactive HTML
  • Command Line Interface - Full-featured CLI for batch operations

Interactive Visualizations

  • Enhanced Graph Visualizer - D3.js force-directed layouts with real-time interactions
  • Algorithm Visualization - Visual highlighting for DFS/BFS traversals
  • Interactive Editing - Add/remove nodes and edges with drag-and-drop
  • Matrix Export - Custom filename support for adjacency matrix downloads
  • Graph Statistics - Real-time node count, edge count, and density calculations

AI Integration

  • MCP Server - HTTP REST API and Claude Desktop MCP server
  • Automatic Visualization - Generate interactive graphs from structured data
  • Smart Data Processing - Extract relationships from various data formats
  • Centrality Analysis - Calculate degree, betweenness, closeness, eigenvector centrality

šŸ“¦ Installation

Prerequisites

  • Ruby 2.7+ - Core graph operations
  • Node.js 16+ - MCP server functionality
  • Modern web browser - For interactive visualizations

Setup

git clone https://github.com/dromologue/Graph-Tools.git
cd Graph-Tools

# For local CLI usage
gem install

# Install MCP server dependencies
cd mcp-graph-server
npm install
cd ..

# For web application
npm install

šŸ”§ Usage

Command Line Interface

# Basic graph visualization
ruby graph_cli.rb matrix.csv

# With custom vertex labels
ruby graph_cli.rb -v "A,B,C,D" matrix.csv

# Run graph algorithms
ruby graph_cli.rb --dfs A --bfs B matrix.csv

# Export to web visualization
ruby graph_cli.rb -d matrix.csv

# Export to JSON
ruby graph_cli.rb -j output.json matrix.csv

Interactive Visualizer

Local Usage:

  1. Open Files/enhanced-graph-visualizer.html in your browser
  2. Load sample data or create your own graph
  3. Run DFS/BFS operations with visual highlighting
  4. Export matrices with custom filenames

Web Application:

  1. Run npm start and visit http://localhost:3000
  2. Upload matrix files via drag-and-drop
  3. Try sample data for quick testing
  4. Get real-time analysis results

MCP Server Integration

HTTP REST API Mode
cd mcp-graph-server
npm run api
# Server runs on http://localhost:3001
Claude Desktop Mode
  1. Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
  "mcpServers": {
    "graph-server": {
      "command": "node",
      "args": ["/path/to/Graph-Tools/mcp-graph-server/api-server.js"],
      "env": {
        "SERVER_MODE": "mcp"
      }
    }
  }
}
  1. Use natural language in Claude Desktop:
Analyze these relationships and create a graph visualization:
[
  {"id": "Alice", "friends": ["Bob", "Carol"]},
  {"id": "Bob", "friends": ["Alice", "David"]},
  {"id": "Carol", "friends": ["Alice"]},
  {"id": "David", "friends": ["Bob"]}
]

šŸ“ Project Structure

Graph-Tools/
ā”œā”€ā”€ graph.rb                           # Core Graph class
ā”œā”€ā”€ graph_cli.rb                       # Command line interface
ā”œā”€ā”€ server.js                          # Web application server
ā”œā”€ā”€ Files/                             # Visualization files directory
ā”‚   ā””ā”€ā”€ enhanced-graph-visualizer.html # Interactive D3.js visualizer
ā”œā”€ā”€ public/                            # Web application files
ā”‚   ā”œā”€ā”€ index.html                     # Main web interface
ā”‚   ā””ā”€ā”€ mcp-documentation.html         # API documentation
ā”œā”€ā”€ mcp-graph-server/                  # MCP server
ā”‚   ā”œā”€ā”€ api-server.js                  # Dual-mode MCP/HTTP server
ā”‚   ā”œā”€ā”€ index.js                       # Original MCP server
ā”‚   ā”œā”€ā”€ package.json                   # Node.js dependencies
ā”‚   ā”œā”€ā”€ claude-config-example.json     # Claude Desktop config example
ā”‚   ā””ā”€ā”€ data/                          # Generated files (matrices, visualizations)
ā”œā”€ā”€ Gemfile                            # Ruby dependencies
ā”œā”€ā”€ package.json                       # Node.js web server dependencies
ā””ā”€ā”€ README.md                          # This file

API Endpoints

The MCP server provides both MCP protocol and HTTP REST API:

  • POST /api/analyze-relationships - Extract relationships from data
  • POST /api/create-adjacency-matrix - Build matrices from relationship pairs
  • POST /api/calculate-centrality - Compute network centrality measures
  • POST /api/analyze-network-structure - Comprehensive network analysis
  • GET /health - Health check endpoint

See /mcp-documentation.html for complete API documentation with examples.

Quick Start

1. Create a Graph Visually

# Open the Enhanced Graph Visualizer
open "Files/enhanced-graph-visualizer.html"

In the enhanced visualizer:

  • Add vertices by typing names and clicking "Add Node"
  • Click two nodes to select them, then click "Add Edge"
  • Drag nodes to reposition them
  • Run DFS/BFS operations and see visual highlights
  • Export as CSV matrix when done

2. Analyze Your Graph

# Basic analysis
ruby graph_cli.rb your_graph.csv

# With custom vertex names  
ruby graph_cli.rb -v "Alice,Bob,Carol,David" your_graph.csv

# Specific operations
ruby graph_cli.rb -v "Alice,Bob,Carol,David" --dfs Alice your_graph.csv
ruby graph_cli.rb -v "Alice,Bob,Carol,David" --bfs Bob your_graph.csv
ruby graph_cli.rb -v "Alice,Bob,Carol,David" --neighbors Carol your_graph.csv

3. Export for Visualization

# Export for D3.js editor (interactive)
ruby graph_cli.rb -v "Alice,Bob,Carol,David" -d your_graph.csv

# Export JSON for programmatic use
ruby graph_cli.rb -v "Alice,Bob,Carol,David" -j output.json your_graph.csv

Command Reference

CLI Options

ruby graph_cli.rb [options] matrix_file

Options:
  -v, --vertices LABELS    # Comma-separated vertex labels
  -f, --format FORMAT      # Output format (text, matrix, json)
  -j, --export-json FILE   # Export to JSON file
  -d, --d3                # Export for D3.js visualization
  --dfs VERTEX            # Perform DFS traversal
  --bfs VERTEX            # Perform BFS traversal  
  --neighbors VERTEX      # Show neighbors
  --path FROM,TO          # Check edge existence

Supported File Formats

  • CSV: 0,1,0\n1,0,1\n0,1,0
  • TXT: 0 1 0\n1 0 1\n0 1 0 (space-separated)
  • JSON: {"matrix": [[0,1,0],[1,0,1],[0,1,0]]}

MCP Server Tools

The MCP server provides these tools for AI assistants:

  • analyze_relationships - Extract relationships from structured data and create visualizations
  • create_adjacency_matrix - Build matrices from relationship pairs
  • calculate_centrality - Compute network centrality measures (degree, betweenness, closeness, eigenvector)
  • analyze_network_structure - Comprehensive network analysis combining relationship extraction and centrality

Performance

  • Graph creation: Sub-second for graphs up to 100 nodes
  • DFS/BFS: Linear time complexity O(V + E)
  • Visualization: Handles 50+ nodes smoothly in D3.js
  • File formats: All formats (CSV, JSON, TXT) supported efficiently
  • HTTP API: Fast response times for network analysis

Error Handling

The tools provide comprehensive error handling for:

  • Invalid matrix formats
  • Non-existent vertices in operations
  • Malformed input files
  • Missing dependencies
  • API validation errors

Contributing

The codebase follows clean architecture principles with separation of concerns:

  • Core graph operations in Ruby
  • Web interface with modern JavaScript
  • MCP server for AI integration
  • Comprehensive API documentation