MCP KQL Server

MCP KQL Server

mcp-name: io.github.4R9UN/mcp-kql-server

Execução de Consultas KQL com IA — Conversão e Execução de Linguagem Natural para KQL (NL2KQL)

Um servidor MCP (Model Context Protocol) que transforma perguntas em linguagem natural em consultas KQL otimizadas, com descoberta inteligente de esquemas, cache com IA e integração perfeita com o Azure Data Explorer. Basta fazer perguntas em português simples e obter consultas KQL instantâneas e precisas, com resultados sensíveis ao contexto.

Versão mais recente: v2.1.5 — Login do Azure CLI em conformidade com políticas e migração para o SDK oficial do MCP em Python.

🎬 Demonstração

Assista a uma demonstração rápida do MCP KQL Server em ação:

🚀 Recursos

• execute_kql_query:

  • Linguagem Natural para KQL: Gere consultas KQL a partir de descrições em linguagem natural.
  • Execução Direta de KQL: Execute consultas KQL brutas.
  • Múltiplos Formatos de Saída: Suporta formatos JSON, CSV e tabela.
  • Validação Estrita de Esquema: Usa memória de esquema descoberta e validação antes da execução.
  • Correção Baseada em Esquema: Corrige colunas inválidas somente quando um esquema de tabela válido pode comprovar a substituição.

• kql_schema_memory:

  • Descoberta de Esquema: Descubra e armazene em cache esquemas de tabelas.
  • Exploração de Banco de Dados: Liste todas as tabelas dentro de um banco de dados.
  • Contexto de IA: Obtenha contexto CAG classificado para tabelas, com saída de esquema estrita opcional com escopo de tabela.
  • Relatórios de Análise: Gere relatórios com visualizações.
  • Gerenciamento de Cache: Limpe ou atualize o cache de esquema.
  • Estatísticas de Memória: Obtenha estatísticas sobre o uso de memória.

📊 Fluxo de Execução das Ferramentas MCP

graph TD
    A[👤 User Submits KQL Query] --> B{🔍 Query Validation}
    B -->|❌ Invalid| C[📝 Syntax Error Response]
    B -->|✅ Valid| D[🧠 Load Schema Context]

    D --> E{💾 Schema Cache Available?}
    E -->|✅ Yes| F[⚡ Load from Memory]
    E -->|❌ No| G[🔍 Discover Schema]

    F --> H[🎯 Execute Query]
    G --> I[💾 Cache Schema + AI Context]
    I --> H

    H --> J{🎯 Query Success?}
    J -->|❌ Error| K[🚨 Enhanced Error Message]
    J -->|✅ Success| L[📊 Process Results]

    L --> M[🎨 Generate Visualization]
    M --> N[📤 Return Results + Context]

    K --> O[💡 AI Suggestions]
    O --> N

    style A fill:#4a90e2,stroke:#2c5282,stroke-width:2px,color:#ffffff
    style B fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style C fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ffffff
    style D fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style E fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style F fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
    style G fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style H fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
    style I fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style J fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style K fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#ffffff
    style L fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
    style M fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style N fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff
    style O fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff

Fluxo de Descoberta de Memória de Esquema

O fluxo de memória de esquema é integrado à execução de consultas, mas agora reutiliza o esquema em cache existente antes de tentar a descoberta ao vivo. Se um esquema de tabela já estiver disponível na memória CAG/esquema, o servidor usará esse esquema em cache em vez de reindexá-lo.

graph TD
    A[👤 User Requests Schema Discovery] --> B[🔗 Connect to Cluster]
    B --> C[📂 Enumerate Databases]
    C --> D[📋 Discover Tables]

    D --> E[🔍 Get Table Schemas]
    E --> F[🤖 AI Analysis]
    F --> G[📝 Generate Descriptions]

    G --> H[💾 Store in Memory]
    H --> I[📊 Update Statistics]
    I --> J[✅ Return Summary]

    style A fill:#4a90e2,stroke:#2c5282,stroke-width:2px,color:#ffffff
    style B fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style C fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style D fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
    style E fill:#7c7c7c,stroke:#4a4a4a,stroke-width:2px,color:#ffffff
    style F fill:#e67e22,stroke:#bf6516,stroke-width:2px,color:#ffffff
    style G fill:#8e44ad,stroke:#6a1b99,stroke-width:2px,color:#ffffff
    style H fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#ffffff
    style I fill:#2980b9,stroke:#1f618d,stroke-width:2px,color:#ffffff
    style J fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:#ffffff

📋 Pré-requisitos

• Python 3.10 ou superior
• Azure CLI instalado. A inicialização do servidor verifica o token atual e executa az login interativo simples somente quando necessário.
• Acesso ao(s) cluster(s) do Azure Data Explorer

🚀 Instalação em Um Comando

Instalação Rápida (Recomendada)

A partir do Código-Fonte

git clone https://github.com/4R9UN/mcp-kql-server.git && cd mcp-kql-server && pip install -e .

Métodos Alternativos de Instalação

pip install mcp-kql-server

Pronto! O servidor automaticamente:

• ✅ Configura diretórios de memória em %APPDATA%\KQL_MCP (Windows) ou ~/.local/share/KQL_MCP (Linux/Mac)
• ✅ Define padrões ideais para uso em produção
• ✅ Suprime logs verbosos do SDK do Azure
• ✅ Nenhuma variável de ambiente necessária

📱 Configuração do Cliente MCP

Instalação única (qualquer plataforma):

pip install --upgrade mcp-kql-server

Após a instalação, configure seu cliente MCP para iniciar o servidor via ponto de entrada do módulo Python: python -m mcp_kql_server. Isso funciona em todas as plataformas onde o Python está em PATH e não depende da localização do script de console mcp-kql-server. (O script de console ainda é instalado pelo pip e permanece suportado para compatibilidade reversa — veja os trechos alternativos abaixo.)

Claude Desktop

Adicione ao seu arquivo de configurações MCP do Claude Desktop (mcp_settings.json):

Localização:

• Windows: %APPDATA%\Claude\mcp_settings.json
• macOS: ~/Library/Application Support/Claude/mcp_settings.json
• Linux: ~/.config/Claude/mcp_settings.json

{
  "mcpServers": {
    "mcpKqlServer": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mcp_kql_server"]
    }
  }
}

{
  "mcpServers": {
    "mcpKqlServer": {
      "type": "stdio",
      "command": "py",
      "args": ["-3", "-m", "mcp_kql_server"]
    }
  }
}

VSCode (com Extensão MCP)

Adicione à sua configuração MCP do VSCode:

Localização do Settings.json:

• Windows: %APPDATA%\Code\User\mcp.json
• macOS: ~/Library/Application Support/Code/User/mcp.json
• Linux: ~/.config/Code/User/mcp.json

{
  "servers": {
    "mcpKqlServer": {
      "type": "stdio",
      "command": "py",
      "args": ["-3", "-m", "mcp_kql_server", "--transport", "stdio"],
      "timeout": 300000,
      "env": {
        "FASTMCP_TRANSPORT": "stdio",
        "MCP_KQL_AUTH_ON_STARTUP": "true",
        "MCP_KQL_CHECK_FOR_UPDATES": "false",
        "MCP_KQL_SKIP_STARTUP_VERSION_CHECK": "1",
        "MCP_KQL_AUTH_CHECK_TIMEOUT_SECONDS": "10",
        "MCP_KQL_AUTH_LOGIN_TIMEOUT_SECONDS": "120",
        "MCP_KQL_SQLITE_BUSY_TIMEOUT_MS": "30000"
      }
    }
  }
}

Se o VS Code registrar spawn ...PythonNNN/python.exe ENOENT, a extensão Python está substituindo um caminho de interpretador em cache para "python". Mude para "py" (Windows) / "python3" (macOS/Linux), ou para o script de console "mcp-kql-server" que o pip install coloca em PATH. Consulte docs/troubleshooting.md para detalhes completos.

Dica para Windows: use py -3 -m mcp_kql_server para que o VS Code não precise de um caminho Python específico do usuário. Se precisar usar um caminho completo localmente, mantenha-o em seu mcp.json privado, não em documentação compartilhada.

Se o servidor iniciar mas o VS Code ainda não mostrar ferramentas, execute MCP: Reset Cached Tools, depois MCP: Reset Trust, e reinicie o servidor a partir de MCP: List Servers. O VS Code armazena confiança e ferramentas em cache separadamente de mcp.json, então uma falha anterior de inicialização pode manter o estado vazio antigo até que você o redefina.

Modo HTTP Compartilhado para Múltiplos Clientes MCP

Use HTTP compartilhado quando o VS Code, GitHub Copilot CLI, agentes ou outros clientes MCP precisarem se conectar a um único processo persistente do servidor MCP KQL.

Os binds HTTP são restritos ao loopback por padrão porque as chamadas de ferramentas executam com a identidade do Azure CLI do operador. Coloque autenticação e TLS em um proxy reverso confiável antes da exposição remota. Bind fora do loopback requer o reconhecimento explícito MCP_KQL_ALLOW_UNAUTHENTICATED_REMOTE_HTTP=true.

Inicie o servidor:

python -m mcp_kql_server --transport http --host 127.0.0.1 --port 8000 --http-path /mcp --stateless-http

Configuração do cliente:

{
  "servers": {
    "mcpKqlServer": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Configurações de Tempo de Execução

O modelo de incorporação é carregado de forma preguiçosa. Alterá-lo faz com que os esquemas sejam reincorporados na atualização, e vetores produzidos por outros modelos são ignorados em vez de misturados.

Roo-code ou Cline (Extensões do VS Code)

Pergunte ou adicione às suas configurações MCP do Roo-code ou Cline:

Localização das Configurações MCP:

• Todas as plataformas: Através das configurações da extensão Roo-code ou mcp_settings.json

{
  "mcp-kql-server": {
    "type": "stdio",
    "command": "python",
    "args": ["-m", "mcp_kql_server"],
    "alwaysAllow": []
  }
}

Cliente MCP Genérico

Para qualquer aplicativo compatível com MCP:

# Preferred: invoke as a Python module (cross-platform)
python -m mcp_kql_server

# Platform-stable launchers (recommended if `python` is ambiguous on PATH)
py -3 -m mcp_kql_server     # Windows
python3 -m mcp_kql_server   # macOS / Linux

# Equivalent console script installed by pip
mcp-kql-server

# Shared HTTP mode for multiple clients
python -m mcp_kql_server --transport http --host 127.0.0.1 --port 8000 --http-path /mcp --stateless-http

# Server provides these tools:
# - execute_kql_query: Execute KQL or generate KQL from natural language
# - kql_schema_memory: Discover, cache, and inspect cluster schemas

🔧 Início Rápido

1. Inicie o Servidor MCP (Configuração zero)

python -m mcp_kql_server

A inicialização do servidor começa com uma verificação de token do Azure CLI em segundo plano e executa az login interativo simples somente quando necessário. Chamadas de ferramentas Kusto nunca iniciam login; elas aguardam essa tarefa de inicialização antes de executar. Para autenticar manualmente antes de iniciar o servidor, execute:

az login

Para inspecionar a versão instalada do servidor e os padrões de tempo de execução:

python -m mcp_kql_server --info --json

O servidor inicia imediatamente com:

• 📁 Caminho de memória criado automaticamente: %APPDATA%\KQL_MCP\cluster_memory
• 🔧 Padrões otimizados: Nenhum arquivo de configuração necessário
• 🔐 Configuração segura: Usa suas credenciais existentes do Azure CLI
• ⚡ Inicialização responsiva: A descoberta MCP inicia imediatamente enquanto a autenticação é inicializada em segundo plano

3. Uso via Cliente MCP

O servidor fornece duas ferramentas principais:

execute_kql_query - Execute consultas KQL ou gere KQL a partir de linguagem natural

kql_schema_memory - Descubra, atualize e inspecione esquemas de cluster em cache

💡 Exemplos de Uso

Execução Básica de Consulta

Pergunte ao seu cliente MCP (como o Claude):

"Execute esta consulta KQL no cluster help: cluster('help.kusto.windows.net').database('Samples').StormEvents | take 10 e resuma o resultado e me dê insights de alto nível"

Consulta Analítica Complexa

Pergunte ao seu cliente MCP:

"Consulte o banco de dados Samples no cluster help para me mostrar os 10 principais estados por contagem de eventos de tempestade, incluindo visualização"

Descoberta de Esquema

Pergunte ao seu cliente MCP:

"Descubra e armazene em cache o esquema do cluster help.kusto.windows.net e depois me diga quais bancos de dados e tabelas estão disponíveis"

Exploração de Dados com Contexto

Pergunte ao seu cliente MCP:

"Usando a tabela StormEvents no banco de dados Samples no cluster help, mostre-me todos os eventos de tornado de 2007 com estimativas de danos acima de US$ 1 milhão"

Análise Baseada em Tempo

Pergunte ao seu cliente MCP:

"Analise eventos de tempestade por mês para o ano de 2007 na tabela StormEvents, agrupe por tipo de evento e mostre como visualização"

🎯 Principais Benefícios

Para Analistas de Dados

• ⚡ Desenvolvimento de Consultas Mais Rápido: Autocompletar e sugestões com IA
• 🎨 Visualizações Ricas: Tabelas markdown instantâneas para exploração de dados
• 🧠 Consciência de Contexto: Entenda sua estrutura de dados sem documentação

Para Equipes de DevOps

• 🔄 Descoberta Automatizada de Esquema: Mantenha informações de esquema atualizadas
• 💾 Cache Inteligente: Reduza chamadas de API e melhore o desempenho
• 🔐 Autenticação Segura: Aproveite as credenciais existentes do Azure CLI

Para Aplicações de IA

• 🤖 Assistência Inteligente de Consultas: Descrições e sugestões de tabelas geradas por IA
• 📊 Acesso Estruturado a Dados: Respostas limpas e tipadas para processamento downstream
• 🎯 Respostas Sensíveis ao Contexto: Metadados ricos para melhor tomada de decisão da IA

🏗️ Arquitetura

%%{init: {'theme':'dark', 'themeVariables': {
  'primaryColor':'#1a1a2e',
  'primaryTextColor':'#00d9ff',
  'primaryBorderColor':'#00d9ff',
  'secondaryColor':'#16213e',
  'secondaryTextColor':'#c77dff',
  'secondaryBorderColor':'#c77dff',
  'tertiaryColor':'#0f3460',
  'tertiaryTextColor':'#ffaa00',
  'tertiaryBorderColor':'#ffaa00',
  'lineColor':'#00d9ff',
  'textColor':'#ffffff',
  'mainBkg':'#0a0e27',
  'nodeBorder':'#00d9ff',
  'clusterBkg':'#16213e',
  'clusterBorder':'#9d4edd',
  'titleColor':'#00ffff',
  'edgeLabelBackground':'#1a1a2e',
  'fontFamily':'Inter, Segoe UI, sans-serif',
  'fontSize':'16px',
  'flowchart':{'nodeSpacing':60, 'rankSpacing':80, 'curve':'basis', 'padding':20}
}}}%%
graph LR
    Client["🖥️ MCP Client<br/><b>Claude / AI / Custom</b><br/>─────────<br/>Natural Language<br/>Interface"]

    subgraph Server["🚀 MCP KQL Server"]
        direction TB
        FastMCP["⚡ FastMCP<br/>Framework<br/>─────────<br/>MCP Protocol<br/>Handler"]
        NL2KQL["🧠 NL2KQL<br/>Engine<br/>─────────<br/>AI Query<br/>Generation"]
        Executor["⚙️ Query<br/>Executor<br/>─────────<br/>Validation &<br/>Execution"]
        Memory["💾 Schema<br/>Memory<br/>─────────<br/>AI Cache"]

        FastMCP --> NL2KQL
        NL2KQL --> Executor
        Executor --> Memory
        Memory --> Executor
    end

    subgraph Azure["☁️ Azure Services"]
        direction TB
        ADX["📊 Azure Data<br/>Explorer<br/>─────────<br/><b>Kusto Cluster</b><br/>KQL Engine"]
        Auth["🔐 Azure<br/>Identity<br/>─────────<br/>Interactive<br/>CLI Auth"]
    end

    %% Client to Server
    Client ==>|"📡 MCP Protocol<br/>stdio or streamable HTTP"| FastMCP

    %% Server to Azure
    Executor ==>|"🔍 Execute KQL<br/>Query & Analyze"| ADX
    Executor -->|"🔐 Authenticate"| Auth
    Memory -.->|"📥 Fetch Schema<br/>On Demand"| ADX

    %% Styling - Using cyberpunk palette
    style Client fill:#1a1a2e,stroke:#00d9ff,stroke-width:4px,color:#00ffff
    style FastMCP fill:#16213e,stroke:#c77dff,stroke-width:3px,color:#c77dff
    style NL2KQL fill:#1a1a40,stroke:#ffaa00,stroke-width:3px,color:#ffaa00
    style Executor fill:#16213e,stroke:#9d4edd,stroke-width:3px,color:#9d4edd
    style Memory fill:#0f3460,stroke:#00d9ff,stroke-width:3px,color:#00d9ff
    style ADX fill:#1a1a2e,stroke:#ff6600,stroke-width:4px,color:#ff6600
    style Auth fill:#16213e,stroke:#00ffff,stroke-width:2px,color:#00ffff

    style Server fill:#0a0e27,stroke:#9d4edd,stroke-width:3px,stroke-dasharray: 5 5
    style Azure fill:#0a0e27,stroke:#ff6600,stroke-width:3px,stroke-dasharray: 5 5

Relatório Gerado pelo MCP-KQL-Server | ⭐ Marque este repositório com estrela no GitHub

🚀 Implantação em Produção

Pronto para implantar o MCP KQL Server no Azure para uso em produção? Fornecemos automação abrangente de implantação para Azure Container Apps com segurança e escalabilidade de nível empresarial.

🌟 Recursos

• ✅ Computação Serverless: Azure Container Apps com autoescalabilidade
• ✅ Identidade Gerenciada: Autenticação sem senha com Azure AD
• ✅ Infraestrutura como Código: Modelos Bicep para implantações reproduzíveis
• ✅ Monitoramento: Log Analytics e Application Insights integrados
• ✅ Seguro por Padrão: Isolamento de rede, RBAC e acesso com privilégios mínimos
• ✅ Implantação em Um Comando: Scripts automatizados em PowerShell e Bash

📖 Guia de Implantação

Para instruções completas de implantação, detalhes de arquitetura e solução de problemas:

👉 Ver Guia de Implantação em Produção

O guia inclui:

• 🏗️ Diagramas detalhados de arquitetura
• ⚙️ Instruções passo a passo de implantação (PowerShell e Bash)
• 🔒 Melhores práticas de configuração de segurança
• 🐛 Solução de problemas comuns
• 📦 Detalhes de conteinerização Docker

Implantação Rápida

# PowerShell (Windows)
cd deployment
.\deploy.ps1 -SubscriptionId "YOUR_SUB_ID" -ResourceGroupName "mcp-kql-prod-rg" -ClusterUrl "https://yourcluster.region.kusto.windows.net"

# Bash (Linux/Mac/WSL)
cd deployment
./deploy.sh --subscription "YOUR_SUB_ID" --resource-group "mcp-kql-prod-rg" --cluster-url "https://yourcluster.region.kusto.windows.net"

📁 Estrutura do Projeto

mcp-kql-server/
├── mcp_kql_server/
│   ├── __init__.py          # Package initialization
│   ├── mcp_server.py        # Main MCP server implementation
│   ├── execute_kql.py       # KQL query execution logic
│   ├── memory.py            # Advanced memory management
│   ├── kql_auth.py          # Azure authentication
│   ├── utils.py             # Utility functions
│   └── constants.py         # Configuration constants
├── docs/                    # Documentation
├── Example/                 # Usage examples
├── pyproject.toml          # Project configuration
└── README.md               # This file

🔒 Segurança

• Autenticação Azure CLI: Reutiliza um token existente ou inicia login interativo no navegador
• Sem Armazenamento de Credenciais: O servidor não armazena tokens de autenticação
• Memória Local: Cache de esquema armazenado localmente, não transmitido

🐛 Solução de Problemas

Problemas Comuns

1. Erros de Autenticação

   # Re-authenticate with Azure CLI
   az login --tenant your-tenant-id
   

2. Problemas de Memória

   # The memory cache is now managed automatically. If you suspect issues,
   # you can clear the cache directory, and it will be rebuilt on the next query.
   # Windows:
   rmdir /s /q "%APPDATA%\KQL_MCP\unified_memory.json"
   
   # macOS/Linux:
   rm -rf ~/.local/share/KQL_MCP/cluster_memory
   

3. Tempos de Conexão Excedidos

   • Verifique o formato do URI do cluster
   • Confirme a conectividade de rede
   • Valide as permissões do Azure

🤝 Contribuições

Aceitamos contribuições! Fique à vontade para contribuir.

📞 Suporte

• Problemas: Issues no GitHub
• Pacote PyPI: Página do Projeto no PyPI
• Autor: Arjun Trivedi
• Certificado: MCPHub

🌟 Histórico de Estrelas

mcp-name: io.github.4R9UN/mcp-kql-server

Boas consultas! 🎉