{"id":30307339,"url":"https://github.com/cosh/kustographassistant","last_synced_at":"2026-04-13T09:32:04.334Z","repository":{"id":304666732,"uuid":"1019515468","full_name":"cosh/KustoGraphAssistant","owner":"cosh","description":"A Model Context Protocol (MCP) server that provides comprehensive guidance and best practices for creating and managing Kusto graph models in Azure Data Explorer.","archived":false,"fork":false,"pushed_at":"2025-07-16T06:28:56.000Z","size":23,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-17T10:45:42.789Z","etag":null,"topics":["azure","azure-data-explorer","best-practices","csharp","data-analytics","dotnet","github-copilot","graph-analytics","graph-models","kql","kusto","mcp-server","model-context-protocol","query-optimization","visual-studio-code"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cosh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-14T12:53:46.000Z","updated_at":"2025-07-17T13:38:41.000Z","dependencies_parsed_at":"2025-07-14T16:58:30.904Z","dependency_job_id":"f6b0683c-bdf1-46e6-80f8-88c1faff4881","html_url":"https://github.com/cosh/KustoGraphAssistant","commit_stats":null,"previous_names":["cosh/kustographassistant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cosh/KustoGraphAssistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosh%2FKustoGraphAssistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosh%2FKustoGraphAssistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosh%2FKustoGraphAssistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosh%2FKustoGraphAssistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cosh","download_url":"https://codeload.github.com/cosh/KustoGraphAssistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosh%2FKustoGraphAssistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31746294,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure","azure-data-explorer","best-practices","csharp","data-analytics","dotnet","github-copilot","graph-analytics","graph-models","kql","kusto","mcp-server","model-context-protocol","query-optimization","visual-studio-code"],"created_at":"2025-08-17T10:45:26.257Z","updated_at":"2026-04-13T09:32:04.327Z","avatar_url":"https://github.com/cosh.png","language":"C#","readme":"# Kusto Graph Assistant\n\n[![Build MCP Server](https://github.com/cosh/KustoGraphAssistant/actions/workflows/build.yml/badge.svg)](https://github.com/cosh/KustoGraphAssistant/actions/workflows/build.yml)\n\nA 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).\n\n## What is KustoGraphAssistant?\n\nKusto Graph Assistant is an intelligent assistant that helps you:\n\n- **Design effective graph schemas** - Get guidance on structuring nodes, edges, and relationships based on your data patterns\n- **Optimize graph performance** - Learn best practices for query optimization and efficient graph model design\n- **Simplify complex schemas** - Understand when and how to use property bags, dedicated columns, and schema evolution\n- **Master graph-match queries** - Get comprehensive guidance on using the graph-match operator with persistent graphs\n- **Follow KQL best practices** - Learn proper syntax, patterns, and performance optimization techniques\n\n## Features\n\nThe MCP server provides several specialized tools:\n\n### 🎯 GetGraphModelBestPractices\n\nComprehensive best practices covering:\n\n- Core design principles for graph models\n- Schema design guidelines and simplification strategies\n- Performance optimization techniques\n- Common patterns for identity graphs, network topology, and process flows\n\n### 📋 GetGraphCommandGuidance\n\nDetailed guidance on KQL commands including:\n\n- Graph model creation and management syntax\n- Query patterns for graph-match operations\n- Performance tips and debugging strategies\n- Common mistakes and how to avoid them\n\n### 🔧 GetSchemaSimplificationGuidance\n\nSpecialized guidance on:\n\n- Using property bags to reduce schema complexity\n- ID type consistency (always use strings!)\n- When to use dedicated properties vs. property bags\n- Schema evolution strategies\n\n### 🔍 GetGraphMatchGuidance\n\nComplete reference for graph-match operator:\n\n- Pattern notation and syntax\n- Label checking with WHERE clauses\n- Variable-length edge patterns\n- Performance optimization techniques\n\n## Prerequisites\n\n- .NET 9.0 or later\n- Visual Studio Code\n- GitHub Copilot extension for VS Code\n\n## Installation and Setup\n\n### 1. Clone and Build the Project\n\n```bash\ngit clone https://github.com/cosh/KustoGraphAssistant.git\ncd KustoGraphAssistant\ndotnet build\n```\n\n### 2. Configure the MCP Server in Visual Studio Code\n\nConfigure GitHub Copilot for Visual Studio Code to use your custom MCP server:\n\n1. If you haven't already, open your project folder in Visual Studio Code.\n2. Create a `.vscode` folder at the root of your project.\n3. Add an `mcp.json` file in the `.vscode` folder with the following content:\n\n   ```json\n   {\n     \"inputs\": [],\n     \"servers\": {\n       \"KustoGraphAssistant\": {\n         \"type\": \"stdio\",\n         \"command\": \"dotnet\",\n         \"args\": [\n           \"run\",\n           \"--project\",\n           \"${workspaceFolder}/KustoGraphAssistant.csproj\"\n         ]\n       }\n     }\n   }\n   ```\n\n4. Save the file.\n\n### 3. Test the MCP Server\n\n1. Open GitHub Copilot in Visual Studio Code and switch to agent mode.\n2. Select the **Select tools** icon to verify your **KustoGraphAssistant** is available with all tools listed.\n\n## Usage Examples\n\nOnce configured, you can interact with the assistant through GitHub Copilot:\n\n### Getting Started with Graph Models\n\n```text\nWhat are the best practices for designing a graph model for user relationships?\n```\n\n### Schema Design Help\n\n```text\nHow should I structure my graph schema for network topology analysis?\n```\n\n### Query Optimization\n\n```text\nShow me how to write efficient graph-match queries for finding shortest paths.\n```\n\n### Troubleshooting\n\n```text\nI'm getting errors with my graph model definition. What are common mistakes to avoid?\n```\n\n## Key Design Principles\n\nThis assistant emphasizes several important principles:\n\n### 🔤 Always Use String IDs\n\n- Convert all node and edge IDs to string type using `tostring()`\n- Prevents type mismatch errors and ensures consistency\n\n### 📦 Leverage Property Bags\n\n- Use `pack_all()` to automatically capture all properties\n- Create dedicated typed properties only for frequently filtered fields\n- Schema definition is optional - start simple!\n\n### ⚡ Optimize for Performance\n\n- Apply filters early in Definition queries\n- Use specific labels in graph-match WHERE clauses\n- Limit variable-length path searches appropriately\n\n### 🎯 Query Pattern Awareness\n\n- Design your graph schema based on your query patterns, not just data structure\n- Use graph-match for pattern matching, graph-shortest-paths for optimal paths\n- Always include a project clause in graph-match queries\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues, feature requests, or pull requests.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔄 Data Flow \u0026 Integration\n\n```mermaid\nsequenceDiagram\n    participant User as 👤 Developer\n    participant VSCode as 📝 VS Code\n    participant Copilot as 🤖 GitHub Copilot\n    participant MCP as 🔌 MCP Server\n    participant Tools as 🛠️ Graph Tools\n    participant ADX as ☁️ Azure Data Explorer\n\n    User-\u003e\u003eVSCode: Opens project\n    VSCode-\u003e\u003eCopilot: Activates assistant\n    Copilot-\u003e\u003eMCP: Connects via stdio\n    MCP-\u003e\u003eTools: Registers tool methods\n\n    User-\u003e\u003eCopilot: Asks about graph models\n    Copilot-\u003e\u003eMCP: Calls appropriate tool\n    MCP-\u003e\u003eTools: Executes tool method\n    Tools--\u003e\u003eMCP: Returns guidance/examples\n    MCP--\u003e\u003eCopilot: JSON response\n    Copilot--\u003e\u003eUser: Formatted guidance\n\n    User-\u003e\u003eCopilot: Requests KQL examples\n    Copilot-\u003e\u003eMCP: GetGraphCommandGuidance()\n    MCP-\u003e\u003eTools: Generates KQL templates\n    Tools--\u003e\u003eUser: Ready-to-use KQL code\n\n    User-\u003e\u003eADX: Implements suggestions\n    ADX--\u003e\u003eUser: Creates graph models\n```\n\n## 🧩 Tool Ecosystem\n\n```mermaid\nmindmap\n  root((🔗 Kusto Graph Assistant))\n    🎯 Best Practices\n      Core Principles\n      Schema Design\n      Performance\n      Common Patterns\n      Identity Graphs\n      Network Topology\n      Process Flows\n    📋 Command Guidance\n      Creation Commands\n      Query Patterns\n      Management\n      Performance Tips\n      Common Mistakes\n      Debugging\n    🔧 Schema Simplification\n      Property Bags\n      ID Consistency\n      Dedicated Properties\n      Evolution Strategy\n      Query Patterns\n    🔍 Graph Match\n      Basic Syntax\n      Pattern Notation\n      Label Checking\n      Variable Length\n      WHERE Clause\n      PROJECT Clause\n      Examples\n      Performance\n```\n\n## 🏗️ Technical Architecture\n\n### Architecture Highlights\n\n- **Model Context Protocol (MCP) server** - Standardized interface for tool integration\n- **.NET 9.0 console application** - Modern, high-performance runtime\n- **Dependency injection** with Microsoft.Extensions.Hosting for clean architecture\n- **Stdio transport** for seamless VS Code integration\n- **Assembly scanning** for automatic tool discovery and registration\n\n### Core Tools\n\n- **GetGraphModelBestPractices** - Comprehensive design guidance covering core principles, schema design, performance optimization, and common patterns for identity graphs, network topology, and process flows\n- **GetGraphCommandGuidance** - KQL command templates for graph model creation, query patterns, management operations, and debugging strategies\n- **GetSchemaSimplificationGuidance** - Schema optimization guidance including property bags, ID consistency, dedicated properties, and evolution strategies\n- **GetGraphMatchGuidance** - Query pattern examples covering basic syntax, pattern notation, label checking, variable length paths, and performance optimization\n\n### Integration Points\n\n- **GitHub Copilot in VS Code** - Natural language interface for accessing graph modeling guidance\n- **Azure Data Explorer (Kusto)** - Target platform for graph model implementation\n- **Graph models and snapshots** - Persistent and transient graph storage mechanisms\n- **KQL (Kusto Query Language)** - Query language for graph operations and analysis\n- **JSON-based tool responses** - Structured data format for tool communication\n\n### Key Features\n\n- **Real-time guidance** for graph modeling decisions and best practices\n- **Performance optimization recommendations** based on query patterns and data volume\n- **Schema evolution strategies** for maintaining and updating graph models over time\n- **Ready-to-use KQL templates** for common graph operations and patterns\n- **Best practice enforcement** to prevent common mistakes and anti-patterns\n\n## Support\n\nIf you encounter any issues or have questions:\n\n1. Check the common patterns and troubleshooting guidance provided by the assistant\n2. Review the KQL documentation for Azure Data Explorer\n3. Submit an issue in this repository\n\n---\n\n**Happy Graph Modeling!** 🚀\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosh%2Fkustographassistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcosh%2Fkustographassistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosh%2Fkustographassistant/lists"}