qmcp Server

Um servidor MCP para integrar e consultar bancos de dados q/kdb+.

GitHub
8
Experimente este MCPPatrocinado

Documentação

Servidor qmcp

Um servidor Model Context Protocol (MCP) para integração com q/kdb+.

MCP é um protocolo aberto criado pela Anthropic que permite que sistemas de IA interajam com ferramentas externas e fontes de dados. Embora atualmente suportado pelo Claude (Desktop e CLI), o padrão aberto permite que outros LLMs o adotem no futuro.

Prova de Conceito de Código Aberto

Este repositório contém uma prova de conceito de código aberto demonstrando a abordagem central do qmcp. A ferramenta de tradução Qython (disponível em github.com/gabiteodoru/qython) cobre aproximadamente 5% da linguagem q e é fornecida para avaliação e experimentação.

Resultados de Produção: A implementação completa do Qython alcança uma taxa de falha de 0,6% nos benchmarks HumanEval, com melhoria de 10x na confiabilidade em relação ao desenvolvimento nativo em q. Veja a avaliação completa: Taxa de Falha de 0,6%: Resolvendo Geração de Código LLM para q/kdb+

Licenciamento Comercial: Para acesso à implementação completa do Qython com cobertura abrangente da linguagem, entre em contato pelo e-mail gabiteodoru@gmail.com

Recursos

  • Conectar a servidores q/kdb+
  • Executar consultas e comandos q
  • Gerenciamento de conexão persistente
  • Tratamento inteligente de consultas assíncronas com timeouts configuráveis
  • Cancelamento programático de consultas (equivalente a Ctrl+C)
  • Tratamento adequado de consultas de longa duração
  • NOVO: Tradutor de linguagem Qython (Alpha Experimental)

Usuários Windows: Recomendação WSL

⚠️ Importante para usuários Windows: Para funcionalidade ideal, é altamente recomendado executar tanto o servidor MCP quanto sua sessão q dentro do WSL (Subsistema Windows para Linux). Isso garante que o servidor possa interromper loops infinitos e consultas descontroladas que LLMs possam gerar acidentalmente.

Executar o servidor MCP no Windows (fora do WSL) desativa a funcionalidade de interrupção de consultas baseada em SIGINT, que é crítica para escapar de consultas problemáticas durante sessões de desenvolvimento assistidas por IA.

Arquitetura e Filosofia de Design

Objetivos Pretendidos

O qmcp é projetado para fornecer a assistentes de codificação de IA acesso controlado a bancos de dados q/kdb+ para fluxos de trabalho de desenvolvimento e depuração:

  1. Focado em Desenvolvimento: Otimizado para ferramentas de codificação que trabalham com servidores q de depuração/desenvolvimento
  2. Controle de Consultas: A IA pode interromper consultas de longa duração (equivalente ao Ctrl+C do desenvolvedor)
  3. Comportamento Previsível: Execução sequencial previne conflitos de recursos durante o desenvolvimento
  4. Timeouts Configuráveis: Temporização personalizável para diferentes cenários de desenvolvimento

Lógica de Design

A arquitetura do servidor faz escolhas deliberadas para fluxos de trabalho de desenvolvimento assistidos por IA:

Modelo de Conexão Única

  • Por quê: Simplifica a depuração de desenvolvimento - uma conexão, estado claro
  • Benefício: Corresponde ao fluxo de trabalho típico do desenvolvedor com sessão q única
  • Implementação: Uma conexão persistente por sessão MCP

Execução Sequencial de Consultas

  • Por quê: Ambientes de desenvolvimento não precisam de suporte a consultas concorrentes
  • Benefício: Uso previsível de recursos, depuração mais fácil, previne interferência entre consultas
  • Implementação: Novas consultas são rejeitadas enquanto outra está em execução

Alternância Inteligente Assíncrona com Timeouts Configuráveis

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ê: Mantém sessões de codificação de IA responsivas enquanto permite consultas de desenvolvimento complexas
  • Benefício: Feedback imediato para consultas rápidas, acompanhamento de progresso para análises
  • Personalização: Todos os timeouts configuráveis via ferramentas MCP

Interrupção de Consultas Controlada por IA

  • Por quê: Ferramentas de codificação de IA precisam da capacidade de cancelar consultas descontroladas (como o Ctrl+C do desenvolvedor)
  • Como: O servidor MCP localiza o processo q pela porta e envia SIGINT após timeout configurável
  • Benefício: Previne que sessões de desenvolvimento travem em consultas problemáticas
  • Limitações: Funcionalidade SIGINT desativada quando:
    • O servidor MCP roda no Windows (fora do WSL)
    • O servidor MCP e a sessão q rodam em lados opostos da divisão WSL/Windows

Gerenciamento de Processos Orientado ao Desenvolvimento

  • Por quê: Ferramentas de codificação trabalham com servidores q de desenvolvimento gerenciados pelo usuário
  • Benefício: O desenvolvedor controla o ciclo de vida do servidor q, a IA controla a execução de consultas
  • Design: O servidor MCP fornece capacidade de interrupção de consultas sem gerenciamento do ciclo de vida do servidor

Por Que Este Design Faz Sentido para Ferramentas de Codificação

  1. Fluxo de Trabalho de Desenvolvimento: Corresponde a como desenvolvedores interagem com q - sessão única, consultas iterativas
  2. Segurança da IA: Previne que a IA sobrecarregue ambientes de desenvolvimento com solicitações concorrentes
  3. Adequado para Depuração: Execução sequencial facilita o rastreamento de problemas
  4. Responsivo: Tratamento assíncrono previne bloqueio de sessões de codificação de IA
  5. Configurável: Timeouts podem ser ajustados para diferentes cenários de desenvolvimento

Esta arquitetura fornece a assistentes de codificação de IA acesso eficaz ao q/kdb+ enquanto mantém o ambiente previsível e controlado que os fluxos de trabalho de desenvolvimento exigem.

Requisitos

  • Python 3.8+
  • Acesso a um servidor q/kdb+
  • uv (para instalação leve) ou pip (para instalação completa)

Início Rápido

Para usuários de primeira viagem, a maneira mais rápida de começar:

  1. Inicie um servidor q: 
    q -p 5001
  2. Adicione qmcp ao Claude CLI: 
    claude mcp add qmcp "uv run qmcp/server.py"
  3. Comece a usar o Claude CLI: 
    claude
    Em seguida, interaja com 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

Instalação

Instalação Leve (somente Claude CLI)

Execute diretamente com uv (sem necessidade de instalação via pip, pode ser mais lento na inicialização; melhor para experimentar inicialmente):

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

Instalação Completa

Opção 1: pip (recomendado para uso global)

pip install qmcp

Nota: Considere usar um ambiente virtual para evitar conflitos de dependências:

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

Opção 2: uv (para uso específico de projeto)

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

# Or for frequent use, sync dependencies first
uv sync
uv run qmcp
Adicionando ao Claude CLI

Após a instalação completa, adicione o servidor ao Claude CLI:

claude mcp add qmcp qmcp
Adicionando ao Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop:

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

Para instalação baseada em uv:

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

Uso

Iniciando o Servidor MCP

Após instalação completa:

qmcp

Com instalação leve: O servidor inicia automaticamente quando o Claude CLI o utiliza (sem necessidade de início manual).

Variáveis de Ambiente

  • Q_DEFAULT_HOST - Informações de conexão padrão no formato: host, host:port, ou host:port:user:passwd

Lógica de Fallback de Conexão

A ferramenta connect_to_q(host) usa lógica de fallback flexível:

  1. String de conexão completa (tem dois-pontos): Use diretamente, ignore Q_DEFAULT_HOST
    • connect_to_q("myhost:5001:user:pass")
  2. Somente número de porta: Combine com Q_DEFAULT_HOST ou use localhost
    • connect_to_q(5001) → Usa configurações de Q_DEFAULT_HOST com porta 5001
  3. Sem parâmetros: Use Q_DEFAULT_HOST diretamente
    • connect_to_q() → Usa Q_DEFAULT_HOST como está
  4. Somente nome de host: Use como nome de host com porta/autenticação Q_DEFAULT_HOST ou porta padrão
    • connect_to_q("myhost") → Combina com configurações de Q_DEFAULT_HOST

Status de Estabilidade das Ferramentas

Ferramentas Prontas para Produção:

  • connect_to_q - Gerenciamento estável de conexão com lógica de fallback
  • query_q - Executa consultas com controle inteligente de timeout assíncrono
  • set_timeout_switch_to_async - Configura quando consultas alternam para modo assíncrono
  • set_timeout_interrupt_q - Configura quando enviar SIGINT para cancelar consultas
  • set_timeout_connection - Configura timeout de conexão
  • get_timeout_settings - Visualiza configuração atual de timeout
  • get_current_task_status - Verifica status de consulta assíncrona em execução
  • get_current_task_result - Recupera resultado de consulta assíncrona concluída
  • interrupt_current_query - Envia SIGINT para interromper consultas em execução

Ferramentas Experimentais (Alpha):

  • translate_qython_to_q - ⚠️ EXPERIMENTAL: Tradutor de sintaxe semelhante a Python para q
    • Qython suporta: do n times:, converge(), partial(), reduce(), arange()
    • Assume importações: from functools import partial, from numpy import arange
    • Incentiva operações vetorizadas, estilo numpy em vez de loops Python básicos
    • Vocabulário limitado, pode produzir código incorreto
    • Por favor, verifique toda a saída antes do uso
  • translate_q_to_qython - ⚠️ EXPERIMENTAL: Tradutor de código Q para Python-like com desambiguação por IA
    • Usa ParseQ para converter expressões q em código legível e bem documentado semelhante a Python
    • Analisa AST de q, achata chamadas aninhadas e usa IA para desambiguar operadores sobrecarregados
    • Requer conexão q primeiro - execute a ferramenta connect_to_q antes de usar (usa o próprio parser do q)
    • Impacto no Namespace: Cria variáveis e funções no namespace .parseq da sua sessão q
    • Fixado ao Claude Code CLI - diferente de outras ferramentas que funcionam com qualquer LLM compatível com MCP, esta ferramenta especificamente chama o Claude Code CLI para desambiguação por IA
    • Pode produzir traduções incorretas, especialmente para expressões complexas
    • Por favor, verifique toda a saída antes do uso
    • Reporte bugs em GitHub Issues

Limitações Conhecidas

Ao usar o servidor MCP, esteja ciente destas limitações:

Limitações de Interrupção de Consultas (SIGINT)

  • Plataforma Windows: Interrupção de consultas desativada quando o servidor MCP roda no Windows (fora do WSL)
  • Configuração Multiplataforma: Interrupção de consultas desativada quando o servidor MCP e a sessão q rodam em lados opostos da divisão WSL/Windows
  • Impacto: O LLM não pode escapar automaticamente de loops infinitos ou cancelar consultas descontroladas nessas configurações

Limitações de Conversão de Dados

  • Tabelas com chave: Operações como 1!table podem falhar durante a conversão para pandas
  • Distinção String vs Symbol: Strings e símbolos q podem parecer idênticos na saída
  • Ambiguidade de tipos: Use os comandos meta e type do q para determinar os tipos de dados reais quando a precisão for importante
  • Conversão pandas: Algumas estruturas de dados específicas do q podem não ser convertidas adequadamente para DataFrames pandas

Para verificação de tipos, use:

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

Comunicação de Porta WSL2 (Usuários Windows)

Pule esta seção se você não estiver no Windows.

Como o Claude CLI é exclusivo do WSL no Windows, mas você pode querer usar IDEs ou ferramentas do Windows para conectar ao seu servidor q, você precisa de comunicação de porta adequada entre WSL2 e Windows.

Configuração WSL2 para Comunicação de Porta

Configuração do Arquivo .wslconfig

Localização: C:\Users\{YourUsername}\.wslconfig

Adicione configuração de rede espelhada:

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

Reinicie o WSL2

Execute a partir do Windows PowerShell/CMD (NÃO de dentro do WSL):

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

Verifique a Configuração

Verifique se a rede espelhada está ativa:

ip addr show
cat /etc/resolv.conf

Teste a Comunicação de Porta

Teste WSL2 → Windows (localhost):

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

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

Teste Windows → WSL2 (localhost):

# In Windows PowerShell
python -m http.server 8001

# In WSL2
curl http://localhost:8001

O Que a Rede Espelhada Fornece

  • ✅ Comunicação direta com localhost em ambas as direções
  • ✅ Sem necessidade de encaminhamento manual de portas
  • ✅ Melhor compatibilidade com VPN
  • ✅ Rede simplificada (Windows e WSL2 compartilham interfaces de rede)
  • ✅ Regras de firewall tratadas automaticamente

⚠️ Caso Especial da Porta 5000

Problema: A porta 5000 tem suporte limitado de rede espelhada devido à vinculação de serviços do Windows.

Causa Raiz:

  • O serviço svchost do Windows vincula-se a 127.0.0.1:5000 (somente localhost)
  • Vinculações somente localhost não são totalmente espelhadas entre Windows e WSL2
  • Isso cria uma exceção à funcionalidade geral de rede espelhada

Matriz de Comunicação da Porta 5000:

  • ✅ Windows ↔ Windows: Funciona (mesmo localhost)
  • ❌ WSL2 ↔ Windows: Falha (interpretação diferente de localhost)
  • ✅ WSL2 ↔ WSL2: Funciona (mesmo ambiente)

Soluções para a Porta 5000:

  1. Use portas diferentes: 5001, 5002, etc. (recomendado)
  2. Pare o serviço do Windows: Se não for necessário
  3. Encaminhamento tradicional de portas: Para casos de uso específicos

Serviços Comuns Que Podem Ter Vinculação Somente Localhost

  • Servidores de desenvolvimento Flask (padrão 127.0.0.1:5000)
  • Serviço de Host de Dispositivos UPnP
  • Compartilhamento de Rede do Windows Media Player
  • Várias ferramentas de desenvolvimento

Limitações Conhecidas da Rede Espelhada

  1. Serviços somente localhost: Não totalmente espelhados (como confirmado com a porta 5000)
  2. mDNS não funciona no modo espelhado
  3. Algumas configurações do Docker podem ter problemas
  4. Requer Windows 11 22H2+ (build 22621+)