Construindo uma Ferramenta SQL MCP que Permite que LLMs Consultem Bancos de Dados ao Vivo com Wanaku

Assistentes de IA são ótimos em raciocínio, mas eles têm um ponto cego fundamental: suas respostas vêm de dados de treinamento que estão congelados no tempo. Pergunte a uma IA "quais laptops você tem abaixo de $1000?" e você receberá uma resposta que soa plausível — apenas não uma que reflita o que realmente está em seu inventário agora mesmo.

E se a IA pudesse apenas... verificar?

Esse é o problema que o próximo template de serviço sql-tool da Wanaku resolve. Chegando na versão 0.2.0, ele conecta assistentes de IA a bancos de dados relacionais ao vivo através do Protocolo de Contexto do Modelo (MCP), permitindo que eles consultem dados reais em vez de adivinharem a partir de conhecimentos desatualizados.

Espera, o que é a Wanaku? O que é o MCP?

Um contexto rápido se você é novo aqui:

• MCP (Protocolo de Contexto do Modelo) é um protocolo aberto que permite que assistentes de IA usem ferramentas externas, acessem recursos e interajam com serviços de uma maneira padronizada. Pense nisso como uma camada de API universal para IA — em vez de cada cliente de IA precisar de integrações personalizadas, todos podem falar MCP.

• Wanaku é um roteador MCP de código aberto e uma plataforma de gerenciamento de capacidades. Ele atua como a cola entre clientes de IA (como Claude Desktop, Codex ou aplicativos LLM personalizados) e serviços de backend. Você expõe capacidades como ferramentas compatíveis com MCP, e a Wanaku cuida do roteamento, autenticação e descoberta de serviços.

A próxima versão 0.2.0 (PR #1358 aguardando mesclagem) introduz templates de serviço — padrões de capacidade pré-embalados que você pode instanciar com apenas um comando CLI. O template sql-tool é o primeiro desses, e foi projetado para preencher a lacuna entre assistentes de IA e bancos de dados relacionais.

Consultas SQL em Tempo Real vs. RAG Vetorial

Aqui está um cenário que todo desenvolvedor de empresa já viu: você pergunta a um assistente de IA sobre dados operacionais em seu sistema, e ele solta confiantemente uma métrica desatualizada ou completamente fabricada.

A solução clássica é RAG (Geração Aumentada por Recuperação) — você pré-indexa seus dados, os converte em embeddings vetoriais e os armazena em um banco de dados vetorial para a IA pesquisar. Isso funciona maravilhosamente para documentos de texto, wikis e conjuntos de dados estáticos.

A Limitação do RAG

E quanto a dados operacionais ao vivo? Seu inventário em mudança, pedidos de clientes atuais ou métricas de aplicação em tempo real mudam rápido demais para sincronizações vetoriais. Você não quer pré-indexar esses dados — você quer que o LLM os consulte sob demanda via SQL.## A Solução: Expondo Consultas SQL como Ferramentas MCP

O template sql-tool empacota tudo que um desenvolvedor precisa para expor com segurança uma consulta de banco de dados SQL ao vivo como uma ferramenta MCP executável:

• Uma rota Apache Camel que executa consultas seguras contra seu armazenamento de dados alvo.
• Uma definição de ferramenta MCP que clientes de IA compatíveis podem descobrir e chamar dinamicamente.
• Dependências de tempo de execução pré-embaladas (incluindo drivers JDBC, componentes SQL e marshalling JSON).
• Suporte para parametrizar entradas de IA em consultas SQL dinâmicas via expressões Camel Simple.

Você fornece os detalhes de conexão do banco de dados e a sintaxe da consulta base; o gateway Wanaku cuida do resto.

Guia Passo a Passo: Conectando um LLM ao PostgreSQL

Aqui está uma prévia de como instanciar o template SQL uma vez que a 0.2.0 seja lançada. Neste exemplo, temos um banco de dados PostgreSQL contendo um catálogo de produtos ao vivo, e queremos que nosso assistente de IA responda com precisão: "Quais laptops você tem abaixo de $800?"

Passo 1: Implantar o Contêiner do Banco de Dados PostgreSQL

Inicie uma instância local do PostgreSQL usando Podman (os comandos do Docker funcionam da mesma forma aqui):

podman run --rm --name wanaku-postgres \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=wanaku \
  postgres

Carregue seu esquema e dados:

podman exec -i wanaku-postgres psql -U postgres -d postgres < sql-tool-demo.sql

Você pode baixar o script SQL de demonstração no site da Wanaku.

Passo 2: Instanciar o Template de Ferramenta SQL da Wanaku

Agora, exponha seu banco de dados ao vivo para a rede MCP mapeando a entrada da IA para uma consulta SQL dinâmica:

wanaku service template instantiate \
  --name sql-tool \
  --property forage.jdbc.username=postgres \
  --property forage.jdbc.password=wanaku \
  --property sql.query='SELECT name, price FROM products WHERE price < ${body} ORDER BY price' \
  --service-name product-catalog \
  --service-system product-catalog

Note o placeholder ${body} na consulta? Essa é uma expressão Camel Simple. Em tempo de execução, ela é substituída por qualquer entrada que a IA enviar. Então, quando um usuário pergunta "quais laptops estão abaixo de $800?", a IA chama a ferramenta com 800 como entrada, e a consulta se torna:

SELECT name, price FROM products WHERE price < 800 ORDER BY price

Esse é o insight chave: o template SQL não executa consultas estáticas — ele aceita entradas dinâmicas da IA, tornando-o uma verdadeira ferramenta interativa.

Passo 3: Verificar a Implantação do Catálogo

Certifique-se de que seu novo serviço está corretamente registrado no catálogo de capacidades local:

wanaku service catalog list

Você também pode confirmar suas entradas de conectividade de armazenamento de dados ao vivo usando:

wanaku data-store list --plain

Passo 4: Consultando Dados Ao Vivo via Seu Cliente de IA

Apontar qualquer cliente de IA compatível com MCP (como Claude Desktop ou Continue.dev) para seu gateway roteador Wanaku local. O LLM descobrirá automaticamente a capacidade da ferramenta do esquema product-catalog e consultará o banco de dados diretamente.