jmcarbo/grapher

Grapher MCP Server

A powerful and extensible Model Context Protocol (MCP) server for generating high-quality graphs and diagrams from structured data. Supports multiple rendering backends including Graphviz, D2, Mermaid, SVG, and Excalidraw.

🎯 Features

• Multiple Backend Support: Graphviz, D2, Mermaid, native SVG, and Excalidraw
• Rich Output Formats: SVG, PNG, PDF, DOT, JSON, and native formats
• GraphScript DSL: Powerful domain-specific language for complex graph definitions
• MCP Integration: Seamlessly works with MCP-enabled applications
• Flexible Configuration: JSON-based configuration with environment variable support
• Production Ready: Built-in validation, error handling, and performance monitoring

🚀 Quick Start

Installation

1. Install Go 1.19+

   go version  # Should be 1.19 or higher
   

2. Clone and Build

   git clone https://github.com/jmcarbo/grapher.git
   cd grapher
   go build -o grapher ./cmd/grapher
   

3. Install Backend Dependencies

   # Graphviz (for high-quality graph rendering)
   # macOS
   brew install graphviz
   
   # Ubuntu/Debian
   sudo apt-get install graphviz
   
   # D2 (for modern diagram generation)
   curl -fsSL https://d2lang.com/install.sh | sh -
   

Basic Usage

1. Start the server

   ./grapher
   

2. Use via MCP client

   {
     "method": "tools/call",
     "params": {
       "name": "generate_graph",
       "arguments": {
         "graph": {
           "nodes": [
             {"id": "A", "label": "Start"},
             {"id": "B", "label": "Process"},
             {"id": "C", "label": "End"}
           ],
           "edges": [
             {"from": "A", "to": "B", "label": "begin"},
             {"from": "B", "to": "C", "label": "finish"}
           ],
           "type": "directed",
           "title": "Simple Process Flow"
         },
         "backend": "graphviz",
         "options": {
           "format": "svg",
           "layout": "dot"
         }
       }
     }
   }
   

Example Output

The server will generate beautiful graphs like this simple flowchart:

┌─────────┐    begin    ┌─────────┐    finish   ┌─────────┐
│  Start  │ ──────────→ │ Process │ ─────────→  │   End   │
└─────────┘             └─────────┘             └─────────┘

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───→│  Grapher Server  │───→│    Backends     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │                        │
                              ▼                        ▼
                     ┌─────────────────┐    ┌─────────────────┐
                     │  Graph Parser   │    │   Graphviz      │
                     │  & Validator    │    │   D2            │
                     └─────────────────┘    │   Mermaid       │
                                           │   SVG           │
                                           │   Excalidraw    │
                                           └─────────────────┘

📚 Available Backends

🛠️ MCP Tools

The server provides these MCP tools:

• generate_graph - Generate graphs from node/edge data
• list_backends - List available rendering backends
• get_backend_info - Get detailed backend information
• validate_graph - Validate graph structure without rendering

📖 Documentation

• - Complete MCP tools reference
• - Backend installation and usage
• - Domain-specific language reference
• - Configuration options
• - Production deployment
• - How to contribute

⚙️ Configuration

Create a grapher.json configuration file:

{
  "server": {
    "name": "grapher",
    "version": "1.0.0",
    "timeout": "30s"
  },
  "backends": {
    "graphviz": {
      "enabled": true,
      "path": "dot",
      "timeout": "15s"
    },
    "d2": {
      "enabled": true,
      "path": "d2",
      "timeout": "30s"
    }
  },
  "logging": {
    "level": "info",
    "format": "json"
  }
}

🔧 Command Line Options

# Basic usage
./grapher

# Custom configuration
./grapher -config /path/to/config.json

# List available backends
./grapher -list-backends

# Test a specific backend
./grapher -test-backend graphviz

# Show version
./grapher -version

# Set log level
./grapher -log-level debug

📊 Examples

Simple Directed Graph

{
  "nodes": [
    {"id": "start", "label": "Start"},
    {"id": "end", "label": "End"}
  ],
  "edges": [
    {"from": "start", "to": "end"}
  ],
  "type": "directed"
}

Network Diagram

{
  "nodes": [
    {"id": "web", "label": "Web Server", "attributes": {"shape": "box"}},
    {"id": "db", "label": "Database", "attributes": {"shape": "cylinder"}},
    {"id": "cache", "label": "Redis Cache", "attributes": {"shape": "ellipse"}}
  ],
  "edges": [
    {"from": "web", "to": "db", "label": "queries"},
    {"from": "web", "to": "cache", "label": "cache"}
  ],
  "type": "undirected"
}

Organization Chart

{
  "nodes": [
    {"id": "ceo", "label": "CEO"},
    {"id": "cto", "label": "CTO"},
    {"id": "dev1", "label": "Developer 1"},
    {"id": "dev2", "label": "Developer 2"}
  ],
  "edges": [
    {"from": "ceo", "to": "cto"},
    {"from": "cto", "to": "dev1"},
    {"from": "cto", "to": "dev2"}
  ],
  "type": "tree"
}

🧪 Testing

Run the test suite:

# Unit tests
go test ./...

# Integration tests (requires backends)
go test ./... -tags=integration

# Test specific backend
./grapher -test-backend graphviz

🚦 Status & Health Checks

The server provides health check endpoints and status monitoring:

# Check if server is running
curl http://localhost:8080/health

# Get backend status
./grapher -list-backends

🤝 Contributing

We welcome contributions! See our for details.

Development Setup

1. Fork the repository
2. Install dependencies
3. Run tests
4. Submit pull request

git clone https://github.com/yourusername/grapher.git
cd grapher
go mod download
go test ./...

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Graphviz - Graph visualization software
• D2 - Modern diagram scripting language
• Mermaid - Diagramming and charting tool
• MCP - Model Context Protocol

📞 Support

• Documentation:
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Built with ❤️ for the MCP ecosystem