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"
      }
    }
  }
}

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