Kusto Graph Assistant

A Model Context Protocol (MCP) server that provides comprehensive guidance and best practices for creating and managing Kusto graph models. This tool integrates seamlessly with GitHub Copilot in Visual Studio Code to assist developers in building effective graph-based analytics solutions using Azure Data Explorer (Kusto).

What is KustoGraphAssistant?

Kusto Graph Assistant is an intelligent assistant that helps you:

Design effective graph schemas - Get guidance on structuring nodes, edges, and relationships based on your data patterns
Optimize graph performance - Learn best practices for query optimization and efficient graph model design
Simplify complex schemas - Understand when and how to use property bags, dedicated columns, and schema evolution
Master graph-match queries - Get comprehensive guidance on using the graph-match operator with persistent graphs
Follow KQL best practices - Learn proper syntax, patterns, and performance optimization techniques

Features

The MCP server provides several specialized tools:

🎯 GetGraphModelBestPractices

Comprehensive best practices covering:

Core design principles for graph models
Schema design guidelines and simplification strategies
Performance optimization techniques
Common patterns for identity graphs, network topology, and process flows

📋 GetGraphCommandGuidance

Detailed guidance on KQL commands including:

Graph model creation and management syntax
Query patterns for graph-match operations
Performance tips and debugging strategies
Common mistakes and how to avoid them

🔧 GetSchemaSimplificationGuidance

Specialized guidance on:

Using property bags to reduce schema complexity
ID type consistency (always use strings!)
When to use dedicated properties vs. property bags
Schema evolution strategies

🔍 GetGraphMatchGuidance

Complete reference for graph-match operator:

Pattern notation and syntax
Label checking with WHERE clauses
Variable-length edge patterns
Performance optimization techniques

Prerequisites

.NET 9.0 or later
Visual Studio Code
GitHub Copilot extension for VS Code

Installation and Setup

1. Clone and Build the Project

git clone https://github.com/cosh/KustoGraphAssistant.git
cd KustoGraphAssistant
dotnet build

2. Configure the MCP Server in Visual Studio Code

Configure GitHub Copilot for Visual Studio Code to use your custom MCP server:

If you haven't already, open your project folder in Visual Studio Code.
Create a .vscode folder at the root of your project.

Add an mcp.json file in the .vscode folder with the following content:

{
  "inputs": [],
  "servers": {
    "KustoGraphAssistant": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "${workspaceFolder}/KustoGraphAssistant.csproj"
      ]
    }
  }
}

Save the file.

3. Test the MCP Server

Open GitHub Copilot in Visual Studio Code and switch to agent mode.
Select the Select tools icon to verify your KustoGraphAssistant is available with all tools listed.

Usage Examples

Once configured, you can interact with the assistant through GitHub Copilot:

Getting Started with Graph Models

What are the best practices for designing a graph model for user relationships?

Schema Design Help

How should I structure my graph schema for network topology analysis?

Query Optimization

Show me how to write efficient graph-match queries for finding shortest paths.

Troubleshooting

I'm getting errors with my graph model definition. What are common mistakes to avoid?

Key Design Principles

This assistant emphasizes several important principles:

🔤 Always Use String IDs

Convert all node and edge IDs to string type using tostring()
Prevents type mismatch errors and ensures consistency

📦 Leverage Property Bags

Use pack_all() to automatically capture all properties
Create dedicated typed properties only for frequently filtered fields
Schema definition is optional - start simple!

⚡ Optimize for Performance

Apply filters early in Definition queries
Use specific labels in graph-match WHERE clauses
Limit variable-length path searches appropriately

🎯 Query Pattern Awareness

Design your graph schema based on your query patterns, not just data structure
Use graph-match for pattern matching, graph-shortest-paths for optimal paths
Always include a project clause in graph-match queries

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

License

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

🔄 Data Flow & Integration

sequenceDiagram
    participant User as 👤 Developer
    participant VSCode as 📝 VS Code
    participant Copilot as 🤖 GitHub Copilot
    participant MCP as 🔌 MCP Server
    participant Tools as 🛠️ Graph Tools
    participant ADX as ☁️ Azure Data Explorer

    User->>VSCode: Opens project
    VSCode->>Copilot: Activates assistant
    Copilot->>MCP: Connects via stdio
    MCP->>Tools: Registers tool methods

    User->>Copilot: Asks about graph models
    Copilot->>MCP: Calls appropriate tool
    MCP->>Tools: Executes tool method
    Tools-->>MCP: Returns guidance/examples
    MCP-->>Copilot: JSON response
    Copilot-->>User: Formatted guidance

    User->>Copilot: Requests KQL examples
    Copilot->>MCP: GetGraphCommandGuidance()
    MCP->>Tools: Generates KQL templates
    Tools-->>User: Ready-to-use KQL code

    User->>ADX: Implements suggestions
    ADX-->>User: Creates graph models

🧩 Tool Ecosystem

mindmap
  root((🔗 Kusto Graph Assistant))
    🎯 Best Practices
      Core Principles
      Schema Design
      Performance
      Common Patterns
      Identity Graphs
      Network Topology
      Process Flows
    📋 Command Guidance
      Creation Commands
      Query Patterns
      Management
      Performance Tips
      Common Mistakes
      Debugging
    🔧 Schema Simplification
      Property Bags
      ID Consistency
      Dedicated Properties
      Evolution Strategy
      Query Patterns
    🔍 Graph Match
      Basic Syntax
      Pattern Notation
      Label Checking
      Variable Length
      WHERE Clause
      PROJECT Clause
      Examples
      Performance

🏗️ Technical Architecture

Architecture Highlights

Model Context Protocol (MCP) server - Standardized interface for tool integration
.NET 9.0 console application - Modern, high-performance runtime
Dependency injection with Microsoft.Extensions.Hosting for clean architecture
Stdio transport for seamless VS Code integration
Assembly scanning for automatic tool discovery and registration

Core Tools

GetGraphModelBestPractices - Comprehensive design guidance covering core principles, schema design, performance optimization, and common patterns for identity graphs, network topology, and process flows
GetGraphCommandGuidance - KQL command templates for graph model creation, query patterns, management operations, and debugging strategies
GetSchemaSimplificationGuidance - Schema optimization guidance including property bags, ID consistency, dedicated properties, and evolution strategies
GetGraphMatchGuidance - Query pattern examples covering basic syntax, pattern notation, label checking, variable length paths, and performance optimization

Integration Points

GitHub Copilot in VS Code - Natural language interface for accessing graph modeling guidance
Azure Data Explorer (Kusto) - Target platform for graph model implementation
Graph models and snapshots - Persistent and transient graph storage mechanisms
KQL (Kusto Query Language) - Query language for graph operations and analysis
JSON-based tool responses - Structured data format for tool communication

Key Features

Real-time guidance for graph modeling decisions and best practices
Performance optimization recommendations based on query patterns and data volume
Schema evolution strategies for maintaining and updating graph models over time
Ready-to-use KQL templates for common graph operations and patterns
Best practice enforcement to prevent common mistakes and anti-patterns

Support

If you encounter any issues or have questions:

Check the common patterns and troubleshooting guidance provided by the assistant
Review the KQL documentation for Azure Data Explorer
Submit an issue in this repository

Happy Graph Modeling! 🚀