qmcp Server

Un servidor MCP para integrar y consultar bases de datos q/kdb+.

GitHub
8
Prueba este MCPPatrocinado

Documentación

Servidor qmcp

Un servidor de Model Context Protocol (MCP) para integración con q/kdb+.

MCP es un protocolo abierto creado por Anthropic que permite a los sistemas de IA interactuar con herramientas externas y fuentes de datos. Aunque actualmente es compatible con Claude (Desktop y CLI), el estándar abierto permite que otros LLMs lo adopten en el futuro.

Prueba de Concepto de Código Abierto

Este repositorio contiene una prueba de concepto de código abierto que demuestra el enfoque central de qmcp. La herramienta de traducción Qython (disponible en github.com/gabiteodoru/qython) cubre aproximadamente el 5% del lenguaje q y se proporciona para evaluación y experimentación.

Resultados de Producción: La implementación completa de Qython logra una tasa de fallos del 0.6% en los benchmarks de HumanEval, con una mejora de confiabilidad de 10x en comparación con el desarrollo nativo en q. Consulte la evaluación completa: Tasa de Fallos del 0.6%: Resolviendo la Generación de Código LLM para q/kdb+

Licenciamiento Comercial: Para acceder a la implementación completa de Qython con cobertura integral del lenguaje, contacte a gabiteodoru@gmail.com

Características

  • Conéctese a servidores q/kdb+
  • Ejecute consultas y comandos q
  • Gestión de conexiones persistentes
  • Manejo inteligente de consultas asíncronas con tiempos de espera configurables
  • Cancelación programática de consultas (equivalente a Ctrl+C)
  • Manejo elegante de consultas de larga duración
  • NUEVO: Traductor de lenguaje Qython (Alpha Experimental)

Usuarios de Windows: Recomendación de WSL

⚠️ Importante para usuarios de Windows: Para un funcionamiento óptimo, se recomienda encarecidamente ejecutar tanto el servidor MCP como su sesión q dentro de WSL (Subsistema de Windows para Linux). Esto garantiza que el servidor pueda interrumpir bucles infinitos y consultas descontroladas que los LLMs podrían generar accidentalmente.

Ejecutar el servidor MCP en Windows (fuera de WSL) deshabilita la funcionalidad de interrupción de consultas basada en SIGINT, que es crítica para escapar de consultas problemáticas durante sesiones de desarrollo asistidas por IA.

Arquitectura y Filosofía de Diseño

Objetivos Previstos

qmcp está diseñado para proporcionar a los asistentes de codificación de IA acceso controlado a bases de datos q/kdb+ para flujos de trabajo de desarrollo y depuración:

  1. Enfocado al Desarrollo: Optimizado para herramientas de codificación que trabajan con servidores q de depuración/desarrollo
  2. Control de Consultas: La IA puede interrumpir consultas de larga duración (equivalente al Ctrl+C del desarrollador)
  3. Comportamiento Predecible: La ejecución secuencial previene conflictos de recursos durante el desarrollo
  4. Tiempos de Espera Configurables: Temporización personalizable para diferentes escenarios de desarrollo

Lógica de Diseño

La arquitectura del servidor toma decisiones deliberadas para flujos de trabajo de desarrollo asistidos por IA:

Modelo de Conexión Única

  • Por qué: Simplifica la depuración del desarrollo - una conexión, estado claro
  • Beneficio: Coincide con el flujo de trabajo típico del desarrollador con una sola sesión q
  • Implementación: Una conexión persistente por sesión MCP

Ejecución Secuencial de Consultas

  • Por qué: Los entornos de desarrollo no necesitan soporte de consultas concurrentes
  • Beneficio: Uso predecible de recursos, depuración más fácil, previene interferencia entre consultas
  • Implementación: Se rechazan nuevas consultas mientras otra está en ejecución

Cambio Inteligente a Asíncrono con Tiempos de Espera Configurables

Fast Query (< async switch timeout)  →  Return result immediately
Slow Query (> async switch timeout)  →  Switch to async mode
                                     →  Auto-interrupt after interrupt timeout (if configured)
  • Por qué: Mantiene las sesiones de codificación de IA receptivas mientras permite consultas de desarrollo complejas
  • Beneficio: Retroalimentación inmediata para consultas rápidas, seguimiento de progreso para análisis
  • Personalización: Todos los tiempos de espera configurables a través de herramientas MCP

Interrupción de Consultas Controlada por IA

  • Por qué: Las herramientas de codificación de IA necesitan la capacidad de cancelar consultas descontroladas (como el Ctrl+C del desarrollador)
  • Cómo: El servidor MCP localiza el proceso q por puerto y envía SIGINT después de un tiempo de espera configurable
  • Beneficio: Previene que las sesiones de desarrollo se bloqueen con consultas problemáticas
  • Limitaciones: La funcionalidad SIGINT está deshabilitada cuando:
    • El servidor MCP se ejecuta en Windows (fuera de WSL)
    • El servidor MCP y la sesión q se ejecutan en lados opuestos de la división WSL/Windows

Gestión de Procesos Orientada al Desarrollo

  • Por qué: Las herramientas de codificación trabajan con servidores q de desarrollo gestionados por el usuario
  • Beneficio: El desarrollador controla el ciclo de vida del servidor q, la IA controla la ejecución de consultas
  • Diseño: El servidor MCP proporciona capacidad de interrupción de consultas sin gestión del ciclo de vida del servidor

Por Qué Este Diseño Tiene Sentido para Herramientas de Codificación

  1. Flujo de Trabajo de Desarrollo: Coincide con cómo los desarrolladores interactúan con q - sesión única, consultas iterativas
  2. Seguridad de IA: Previene que la IA abrume los entornos de desarrollo con solicitudes concurrentes
  3. Amigable para Depuración: La ejecución secuencial facilita el rastreo de problemas
  4. Receptivo: El manejo asíncrono previene que las sesiones de codificación de IA se bloqueen
  5. Configurable: Los tiempos de espera pueden ajustarse para diferentes escenarios de desarrollo

Esta arquitectura proporciona a los asistentes de codificación de IA acceso efectivo a q/kdb+ mientras mantiene el entorno predecible y controlado que los flujos de trabajo de desarrollo requieren.

Requisitos

  • Python 3.8+
  • Acceso a un servidor q/kdb+
  • uv (para instalación ligera) o pip (para instalación completa)

Inicio Rápido

Para usuarios primerizos, la forma más rápida de comenzar:

  1. Inicie un servidor q: 
    q -p 5001
  2. Agregue qmcp a Claude CLI: 
    claude mcp add qmcp "uv run qmcp/server.py"
  3. Comience a usar Claude CLI: 
    claude
    Luego interactúe con qmcp: 
    > connect to port 5001 and compute 2+2

● qmcp:connect_to_q (MCP)(host: "5001")
  ⎿  true

● qmcp:query_q (MCP)(command: "2+2")
  ⎿  4

Instalación

Instalación Ligera (solo Claude CLI)

Ejecute directamente con uv (no requiere instalación con pip, puede ser más lento al inicio; mejor para probarlo inicialmente):

claude mcp add qmcp "uv run qmcp/server.py"

Instalación Completa

Opción 1: pip (recomendado para uso global)

pip install qmcp

Nota: Considere usar un entorno virtual para evitar conflictos de dependencias:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install qmcp

Opción 2: uv (para uso específico de proyectos)

# One-time execution (downloads dependencies each time)
uv run qmcp

# Or for frequent use, sync dependencies first
uv sync
uv run qmcp
Agregar a Claude CLI

Después de la instalación completa, agregue el servidor a Claude CLI:

claude mcp add qmcp qmcp
Agregar a Claude Desktop

Agregue a su archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "qmcp": {
      "command": "qmcp"
    }
  }
}

Para instalación basada en uv:

{
  "mcpServers": {
    "qmcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/qmcp",
        "run",
        "qmcp"
      ]
    }
  }
}

Uso

Iniciando el Servidor MCP

Después de la instalación completa:

qmcp

Con instalación ligera: El servidor se inicia automáticamente cuando Claude CLI lo usa (no se necesita inicio manual).

Variables de Entorno

  • Q_DEFAULT_HOST - Información de conexión predeterminada en formato: host, host:port, o host:port:user:passwd

Lógica de Respaldo de Conexión

La herramienta connect_to_q(host) utiliza lógica de respaldo flexible:

  1. Cadena de conexión completa (tiene dos puntos): Úsela directamente, ignore Q_DEFAULT_HOST
    • connect_to_q("myhost:5001:user:pass")
  2. Solo número de puerto: Combine con Q_DEFAULT_HOST o use localhost
    • connect_to_q(5001) → Usa la configuración de Q_DEFAULT_HOST con el puerto 5001
  3. Sin parámetros: Use Q_DEFAULT_HOST directamente
    • connect_to_q() → Usa Q_DEFAULT_HOST tal cual
  4. Solo nombre de host: Úselo como nombre de host con Q_DEFAULT_HOST puerto/autenticación o puerto predeterminado
    • connect_to_q("myhost") → Combina con la configuración de Q_DEFAULT_HOST

Estado de Estabilidad de Herramientas

Herramientas Listas para Producción:

  • connect_to_q - Gestión de conexión estable con lógica de respaldo
  • query_q - Ejecute consultas con control inteligente de tiempo de espera asíncrono
  • set_timeout_switch_to_async - Configure cuándo las consultas cambian a modo asíncrono
  • set_timeout_interrupt_q - Configure cuándo enviar SIGINT para cancelar consultas
  • set_timeout_connection - Configure el tiempo de espera de conexión
  • get_timeout_settings - Vea la configuración actual de tiempos de espera
  • get_current_task_status - Verifique el estado de la consulta asíncrona en ejecución
  • get_current_task_result - Recupere el resultado de la consulta asíncrona completada
  • interrupt_current_query - Envíe SIGINT para interrumpir consultas en ejecución

Herramientas Experimentales (Alpha):

  • translate_qython_to_q - ⚠️ EXPERIMENTAL: Traductor de sintaxis similar a Python a q
    • Qython soporta: do n times:, converge(), partial(), reduce(), arange()
    • Asume importaciones: from functools import partial, from numpy import arange
    • Fomenta operaciones vectorizadas, estilo numpy sobre bucles básicos de Python
    • Vocabulario limitado, puede producir código incorrecto
    • Por favor verifique toda la salida antes de usar
  • translate_q_to_qython - ⚠️ EXPERIMENTAL: Traductor de código Q a similar a Python con desambiguación de IA
    • Usa ParseQ para convertir expresiones q en código legible y bien documentado similar a Python
    • Analiza el AST de q, aplana llamadas anidadas y usa IA para desambiguar operadores sobrecargados
    • Requiere conexión q primero - ejecute la herramienta connect_to_q antes de usar (usa el propio analizador de q)
    • Impacto en Espacios de Nombres: Crea variables y funciones en el espacio de nombres .parseq de su sesión q
    • Conectado directamente a Claude Code CLI - a diferencia de otras herramientas que funcionan con cualquier LLM compatible con MCP, esta herramienta llama específicamente a Claude Code CLI para la desambiguación de IA
    • Puede producir traducciones incorrectas, especialmente para expresiones complejas
    • Por favor verifique toda la salida antes de usar
    • Reporte errores en GitHub Issues

Limitaciones Conocidas

Al usar el servidor MCP, tenga en cuenta estas limitaciones:

Limitaciones de Interrupción de Consultas (SIGINT)

  • Plataforma Windows: La interrupción de consultas está deshabilitada cuando el servidor MCP se ejecuta en Windows (fuera de WSL)
  • Configuración Multiplataforma: La interrupción de consultas está deshabilitada cuando el servidor MCP y la sesión q se ejecutan en lados opuestos de la división WSL/Windows
  • Impacto: El LLM no puede escapar automáticamente de bucles infinitos ni cancelar consultas descontroladas en estas configuraciones

Limitaciones de Conversión de Datos

  • Tablas con clave: Operaciones como 1!table pueden fallar durante la conversión a pandas
  • Distinción entre cadena y símbolo: Las cadenas y símbolos de q pueden aparecer idénticos en la salida
  • Ambigüedad de tipos: Use los comandos meta y type de q para determinar los tipos de datos reales cuando la precisión sea importante
  • Conversión a pandas: Algunas estructuras de datos específicas de q pueden no convertirse correctamente a DataFrames de pandas

Para verificación de tipos, use:

meta table           / Check table column types and structure
type variable        / Check variable type

Comunicación de Puertos WSL2 (Usuarios de Windows)

Omita esta sección si no está en Windows.

Dado que Claude CLI es solo WSL en Windows, pero es posible que desee usar IDEs o herramientas de Windows para conectarse a su servidor q, necesita una comunicación de puertos adecuada entre WSL2 y Windows.

Configuración de WSL2 para Comunicación de Puertos

Configuración del Archivo .wslconfig

Ubicación: C:\Users\{YourUsername}\.wslconfig

Agregue la configuración de red reflejada:

# Mirrored networking mode for seamless port communication
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

Reinicie WSL2

Ejecute desde Windows PowerShell/CMD (NO desde dentro de WSL):

wsl --shutdown
# Wait a few seconds, then start WSL again

Verifique la Configuración

Compruebe si la red reflejada está activa:

ip addr show
cat /etc/resolv.conf

Pruebe la Comunicación de Puertos

Pruebe WSL2 → Windows (localhost):

# In WSL2, start a server
python3 -m http.server 8000

# In Windows browser or PowerShell
curl http://localhost:8000

Pruebe Windows → WSL2 (localhost):

# In Windows PowerShell
python -m http.server 8001

# In WSL2
curl http://localhost:8001

Qué Proporciona la Red Reflejada

  • ✅ Comunicación directa con localhost en ambas direcciones
  • ✅ Sin necesidad de reenvío de puertos manual
  • ✅ Mejor compatibilidad con VPN
  • ✅ Red simplificada (Windows y WSL2 comparten interfaces de red)
  • ✅ Reglas de firewall manejadas automáticamente

⚠️ Caso Especial del Puerto 5000

Problema: El puerto 5000 tiene soporte limitado de red reflejada debido al enlace de servicios de Windows.

Causa Raíz:

  • El servicio svchost de Windows se enlaza a 127.0.0.1:5000 (solo localhost)
  • Los enlaces solo-localhost no se reflejan completamente entre Windows y WSL2
  • Esto crea una excepción a la funcionalidad general de red reflejada

Matriz de Comunicación del Puerto 5000:

  • ✅ Windows ↔ Windows: Funciona (mismo localhost)
  • ❌ WSL2 ↔ Windows: Fallo (diferente interpretación de localhost)
  • ✅ WSL2 ↔ WSL2: Funciona (mismo entorno)

Soluciones para el Puerto 5000:

  1. Use puertos diferentes: 5001, 5002, etc. (recomendado)
  2. Detenga el servicio de Windows: Si no es necesario
  3. Reenvío de puertos tradicional: Para casos de uso específicos

Servicios Comunes Que Pueden Tener Enlace Solo-Localhost

  • Servidores de desarrollo Flask (127.0.0.1:5000 predeterminado)
  • Servicio de Host de Dispositivos UPnP
  • Uso compartido de red de Windows Media Player
  • Varias herramientas de desarrollo

Limitaciones Conocidas de la Red Reflejada

  1. Servicios solo-localhost: No se reflejan completamente (como se confirmó con el puerto 5000)
  2. mDNS no funciona en modo reflejado
  3. Algunas configuraciones de Docker pueden tener problemas
  4. Requiere Windows 11 22H2+ (compilación 22621+)