MCP KQL Server

MCP KQL Server

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

Ejecución de consultas KQL con IA: conversión y ejecución de lenguaje natural a KQL (NL2KQL)

Un servidor de Protocolo de Contexto de Modelo (MCP) que transforma preguntas en lenguaje natural en consultas KQL optimizadas con descubrimiento inteligente de esquemas, caché impulsada por IA e integración perfecta con Azure Data Explorer. Simplemente haz preguntas en lenguaje natural y obtén consultas KQL instantáneas y precisas con resultados conscientes del contexto.

Última versión: v2.1.5 - Inicio de sesión de Azure CLI conforme a políticas y migración al SDK oficial de MCP para Python.

🎬 Demostración

Mira una demostración rápida del MCP KQL Server en acción:

🚀 Características

• execute_kql_query:

  • Lenguaje natural a KQL: Genera consultas KQL a partir de descripciones en lenguaje natural.
  • Ejecución directa de KQL: Ejecuta consultas KQL sin procesar.
  • Múltiples formatos de salida: Compatible con formatos JSON, CSV y tabla.
  • Validación estricta de esquema: Utiliza memoria de esquema descubierta y validación antes de la ejecución.
  • Reparación basada en esquema: Repara columnas no válidas solo cuando un esquema de tabla válido puede demostrar el reemplazo.

• kql_schema_memory:

  • Descubrimiento de esquema: Descubre y almacena en caché esquemas de tablas.
  • Exploración de bases de datos: Enumera todas las tablas dentro de una base de datos.
  • Contexto de IA: Obtén contexto CAG clasificado para tablas, con salida de esquema estricta opcional limitada a la tabla.
  • Informes de análisis: Genera informes con visualizaciones.
  • Gestión de caché: Limpia o actualiza la caché de esquemas.
  • Estadísticas de memoria: Obtén estadísticas sobre el uso de memoria.

📊 Flujo de ejecución de herramientas 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

Flujo de descubrimiento de memoria de esquema

El flujo de memoria de esquema está integrado en la ejecución de consultas, pero ahora reutiliza el esquema en caché existente antes de intentar el descubrimiento en vivo. Si un esquema de tabla ya está disponible en la memoria CAG/esquema, el servidor utilizará ese esquema en caché en lugar de reindexarlo.

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

📋 Requisitos previos

• Python 3.10 o superior
• Azure CLI instalado. El inicio del servidor verifica el token actual y ejecuta az login interactivo simple solo cuando es necesario.
• Acceso a clústeres de Azure Data Explorer

🚀 Instalación con un comando

Instalación rápida (recomendada)

Desde el código fuente

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

Métodos de instalación alternativos

pip install mcp-kql-server

¡Eso es todo! El servidor automáticamente:

• ✅ Configura directorios de memoria en %APPDATA%\KQL_MCP (Windows) o ~/.local/share/KQL_MCP (Linux/Mac)
• ✅ Configura valores predeterminados óptimos para uso en producción
• ✅ Suprime los registros verbosos del SDK de Azure
• ✅ No requiere variables de entorno

📱 Configuración del cliente MCP

Instalación única (cualquier plataforma):

pip install --upgrade mcp-kql-server

Después de la instalación, configura tu cliente MCP para iniciar el servidor mediante el punto de entrada del módulo Python: python -m mcp_kql_server. Esto funciona en todas las plataformas donde Python esté en PATH y no depende de la ubicación del script de consola mcp-kql-server. (El script de consola sigue siendo instalado por pip y permanece compatible para retrocompatibilidad; consulta los fragmentos alternativos a continuación.)

Claude Desktop

Agrega a tu archivo de configuración MCP de Claude Desktop (mcp_settings.json):

Ubicación:

• 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 (con extensión MCP)

Agrega a tu configuración MCP de VSCode:

Ubicación de 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"
      }
    }
  }
}

Si VS Code registra spawn ...PythonNNN/python.exe ENOENT, la extensión de Python está sustituyendo una ruta de intérprete en caché por "python". Cambia a "py" (Windows) / "python3" (macOS/Linux), o al script de consola "mcp-kql-server" que pip install coloca en PATH. Consulta docs/troubleshooting.md para obtener todos los detalles.

Consejo para Windows: usa py -3 -m mcp_kql_server para que VS Code no necesite una ruta de Python específica del usuario. Si debes usar una ruta completa localmente, mantenla en tu mcp.json privado, no en documentación compartida.

Si el servidor se inicia pero VS Code aún no muestra herramientas, ejecuta MCP: Reset Cached Tools, luego MCP: Reset Trust, y reinicia el servidor desde MCP: List Servers. VS Code almacena la confianza y las herramientas en caché por separado de mcp.json, por lo que un lanzamiento fallido anterior puede mantener el estado vacío antiguo hasta que lo restablezcas.

Modo HTTP compartido para múltiples clientes MCP

Usa HTTP compartido cuando VS Code, GitHub Copilot CLI, agentes u otros clientes MCP deban conectarse a un único proceso persistente del servidor MCP KQL.

Los enlaces HTTP están restringidos a loopback de forma predeterminada porque las llamadas a herramientas se ejecutan con la identidad de Azure CLI del operador. Coloca la autenticación y TLS en un proxy inverso de confianza antes de la exposición remota. El enlace no loopback requiere el reconocimiento explícito de MCP_KQL_ALLOW_UNAUTHENTICATED_REMOTE_HTTP=true.

Inicia el servidor:

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

Configuración del cliente:

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

Configuración en tiempo de ejecución

El modelo de incrustación se carga de forma diferida. Cambiarlo provoca que los esquemas se vuelvan a incrustar al actualizar, y los vectores producidos por otros modelos se ignoran en lugar de mezclarse.

Roo-code o Cline (extensiones de VS Code)

Pregunta o agrega a tu configuración MCP de Roo-code o Cline:

Ubicación de configuración MCP:

• Todas las plataformas: A través de la configuración de la extensión Roo-code o mcp_settings.json

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

Cliente MCP genérico

Para cualquier aplicación compatible con 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

🔧 Inicio rápido

1. Iniciar el servidor MCP (configuración cero)

python -m mcp_kql_server

El inicio del servidor comienza una verificación de token de Azure CLI en segundo plano y ejecuta az login interactivo simple solo cuando es necesario. Las llamadas a herramientas de Kusto nunca inician sesión; esperan a que esa tarea de inicio termine antes de ejecutarse. Para autenticarte manualmente antes de iniciar el servidor, ejecuta:

az login

Para inspeccionar la versión instalada del servidor y los valores predeterminados en tiempo de ejecución:

python -m mcp_kql_server --info --json

El servidor se inicia inmediatamente con:

• 📁 Ruta de memoria creada automáticamente: %APPDATA%\KQL_MCP\cluster_memory
• 🔧 Valores predeterminados optimizados: No se necesitan archivos de configuración
• 🔐 Configuración segura: Utiliza tus credenciales existentes de Azure CLI
• ⚡ Inicio receptivo: El descubrimiento MCP comienza inmediatamente mientras la autenticación se inicializa en segundo plano

3. Uso mediante el cliente MCP

El servidor proporciona dos herramientas principales:

execute_kql_query - Ejecutar consultas KQL o generar KQL a partir de lenguaje natural

kql_schema_memory - Descubrir, actualizar e inspeccionar esquemas de clúster en caché

💡 Ejemplos de uso

Ejecución básica de consultas

Pregunta a tu cliente MCP (como Claude):

"Ejecuta esta consulta KQL contra el clúster de ayuda: cluster('help.kusto.windows.net').database('Samples').StormEvents | take 10 y resume el resultado y dame información de alto nivel"

Consulta analítica compleja

Pregunta a tu cliente MCP:

"Consulta la base de datos Samples en el clúster de ayuda para mostrarme los 10 estados principales por número de eventos de tormenta, incluye visualización"

Descubrimiento de esquema

Pregunta a tu cliente MCP:

"Descubre y almacena en caché el esquema del clúster help.kusto.windows.net, luego dime qué bases de datos y tablas están disponibles"

Exploración de datos con contexto

Pregunta a tu cliente MCP:

"Usando la tabla StormEvents en la base de datos Samples del clúster de ayuda, muéstrame todos los eventos de tornado de 2007 con daños estimados superiores a $1M"

Análisis basado en tiempo

Pregunta a tu cliente MCP:

"Analiza los eventos de tormenta por mes para el año 2007 en la tabla StormEvents, agrupa por tipo de evento y muestra como visualización"

🎯 Beneficios clave

Para analistas de datos

• ⚡ Desarrollo de consultas más rápido: Autocompletado y sugerencias impulsados por IA
• 🎨 Visualizaciones enriquecidas: Tablas markdown instantáneas para exploración de datos
• 🧠 Conciencia de contexto: Comprende tu estructura de datos sin documentación

Para equipos de DevOps

• 🔄 Descubrimiento automatizado de esquemas: Mantén la información de esquema actualizada
• 💾 Caché inteligente: Reduce llamadas a la API y mejora el rendimiento
• 🔐 Autenticación segura: Aprovecha las credenciales existentes de Azure CLI

Para aplicaciones de IA

• 🤖 Asistencia inteligente de consultas: Descripciones y sugerencias de tablas generadas por IA
• 📊 Acceso estructurado a datos: Respuestas limpias y tipadas para procesamiento posterior
• 🎯 Respuestas conscientes del contexto: Metadatos enriquecidos para una mejor toma de decisiones de IA

🏗️ Arquitectura

%%{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

Informe generado por MCP-KQL-Server | ⭐ Marca este repositorio con una estrella en GitHub

🚀 Despliegue en producción

¿Listo para desplegar MCP KQL Server en Azure para uso en producción? Proporcionamos automatización integral de despliegue para Azure Container Apps con seguridad y escalabilidad de nivel empresarial.

🌟 Características

• ✅ Computación sin servidor: Azure Container Apps con autoescalado
• ✅ Identidad administrada: Autenticación sin contraseña con Azure AD
• ✅ Infraestructura como código: Plantillas Bicep para despliegues reproducibles
• ✅ Monitoreo: Log Analytics e Application Insights integrados
• ✅ Seguro por diseño: Aislamiento de red, RBAC y acceso de privilegio mínimo
• ✅ Despliegue con un comando: Scripts automatizados de PowerShell y Bash

📖 Guía de despliegue

Para instrucciones completas de implementación, detalles de arquitectura y solución de problemas:

👉 Ver Guía de Implementación en Producción

La guía incluye:

• 🏗️ Diagramas detallados de arquitectura
• ⚙️ Instrucciones de implementación paso a paso (PowerShell y Bash)
• 🔒 Mejores prácticas de configuración de seguridad
• 🐛 Solución de problemas comunes
• 📦 Detalles de contenedorización con Docker

Implementación 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"

📁 Estructura del Proyecto

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

🔒 Seguridad

• Autenticación de Azure CLI: Reutiliza un token existente o inicia sesión interactiva en el navegador
• Sin Almacenamiento de Credenciales: El servidor no almacena tokens de autenticación
• Memoria Local: La caché de esquema se almacena localmente, no se transmite

🐛 Solución de Problemas

Problemas Comunes

1. Errores de Autenticación

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

2. Problemas de Memoria

   # 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. Tiempos de Espera de Conexión

   • Verifique el formato del URI del clúster
   • Verifique la conectividad de red
   • Confirme los permisos de Azure

🤝 Contribuciones

¡Agradecemos las contribuciones! Por favor, contribuya.

📞 Soporte

• Problemas: Problemas de GitHub
• Paquete PyPI: Página del Proyecto en PyPI
• Autor: Arjun Trivedi
• Certificado: MCPHub

🌟 Historial de Estrellas

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

¡Felices Consultas! 🎉