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:

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

Web Application:

Run npm start and visit http://localhost:3000
Upload matrix files via drag-and-drop
Try sample data for quick testing
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

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

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