ChatQL MCP Server

Consulte bancos de dados SQL Server usando linguagem natural com modelos OpenAI GPT.

Documentação

Servidor MCP ChatQL

Um poderoso servidor Model Context Protocol (MCP) que permite consultas em linguagem natural em bancos de dados SQL Server. Transforme suas perguntas em inglês em consultas SQL automaticamente usando os modelos GPT da OpenAI, com reconhecimento inteligente de esquema e otimização de consultas.

🚀 Perfeito para desenvolvedores que usam Cursor AI - Integre diretamente ao seu fluxo de trabalho de desenvolvimento para obter insights instantâneos do banco de dados, exploração de esquema e análise de dados sem sair do seu editor de código.

🗃️ Suporte a Bancos de Dados

Atualmente suportados:

✅ Microsoft SQL Server (2017+)
✅ SQL Server Express
✅ Azure SQL Database

Em breve:

🔄 PostgreSQL (em desenvolvimento)
🔄 MySQL/MariaDB (planejado)
🔄 SQLite (planejado)
🔄 Oracle Database (planejado)

Nota: Esta versão foi projetada especificamente para SQL Server. O suporte para sistemas de banco de dados adicionais está sendo desenvolvido ativamente e estará disponível em versões futuras.

🌟 Recursos

Recursos Principais do Banco de Dados

🗣️ Linguagem Natural para SQL: Converta perguntas em inglês para consultas SQL automaticamente
🧠 Consciente do Esquema: Compreensão inteligente da estrutura do seu banco de dados
🔍 Múltiplos Métodos de Consulta: Linguagem natural, SQL direto e exploração de esquema
📊 Resultados Ricos: Resultados formatados com explicações e análise de consultas
🛡️ Segurança em Primeiro Lugar: Validação de consultas integrada e limitação de resultados
🔒 Modo Somente SELECT: Alterne entre acesso somente leitura e acesso total ao banco de dados

Integração para Desenvolvedores

🔌 Protocolo MCP: Integração nativa com Claude Desktop e Cursor AI
💻 Integração com IDE: Perfeito para fluxos de trabalho de desenvolvimento no Cursor
⚡ Alto Desempenho: Pool de conexões e otimização de consultas
🎯 Registro Profissional: Registro abrangente e tratamento de erros

Perfeito para Equipes de Desenvolvimento

🚀 Prototipagem Rápida: Obtenha insights do banco de dados sem sair do seu editor de código
🔍 Exploração de Esquema: Entenda a estrutura do banco de dados enquanto codifica
🐛 Depuração de Dados: Encontre problemas de dados rapidamente durante o desenvolvimento
📊 Análises Rápidas: Gere relatórios e insights sob demanda
🏗️ Design de Banco de Dados: Entenda relacionamentos e otimize consultas

🚀 Início Rápido

Pré-requisitos

Python 3.8+
SQL Server Express (ou qualquer edição do SQL Server)
ODBC Driver 17 para SQL Server
Chave da API OpenAI (para processamento de linguagem natural)

Instalação

Clone o repositório

git clone https://github.com/SyedRazaHasnain/chatql-mcp.git
cd chatql-mcp

Crie um ambiente virtual

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

Instale as dependências
```
pip install -r requirements.txt
```

Configure o ambiente

cp env.example .env

Edite .env com sua configuração:

# Database Configuration
DB_SERVER=localhost\SQLEXPRESS
DB_DATABASE=your_database_name
DB_USERNAME=               # Leave empty for Windows Auth
DB_PASSWORD=               # Leave empty for Windows Auth
DB_DRIVER=ODBC Driver 17 for SQL Server

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here

Conecte-se ao seu cliente de IA

Escolha seu cliente de IA preferido:
- 🖥️ Claude Desktop - Uso geral e análise de dados
- 💻 Cursor AI - Perfeito para fluxos de trabalho de desenvolvimento (Recomendado para desenvolvedores!)
Não é necessário iniciar o servidor manualmente - seu cliente de IA o iniciará automaticamente!

🛠️ Ferramentas Disponíveis

Quando conectado via MCP, o servidor fornece estas ferramentas poderosas:

1. `execute_natural_language_query`

Transforme linguagem natural em SQL e execute consultas.

Exemplo:

Query: "Show me the top 10 customers by total order value"

2. `execute_direct_sql_query`

Execute consultas SQL diretamente com validação de segurança.

Exemplo:

SELECT TOP 10 CustomerName, SUM(OrderValue) as Total
FROM Customers c JOIN Orders o ON c.ID = o.CustomerID
GROUP BY CustomerName ORDER BY Total DESC

3. `get_table_information`

Obtenha informações detalhadas do esquema para qualquer tabela.

4. `list_database_tables`

Explore todas as tabelas disponíveis no seu banco de dados.

5. `get_table_sample_data`

Visualize dados de amostra de qualquer tabela.

6. `toggle_select_only_mode` 🔒

Alterne entre o modo somente SELECT (somente leitura) e acesso total ao banco de dados.

Exemplo:

Enable SELECT-only mode: {"enabled": true}
Enable full access: {"enabled": false}

7. `get_security_mode_status` 🔒

Verifique o modo de segurança atual e as permissões disponíveis.

📋 Exemplos de Consultas

Aqui estão alguns exemplos de consultas em linguagem natural que você pode experimentar:

💻 Fluxos de Trabalho de Desenvolvimento (Perfeito para Cursor)

"Mostre-me todas as tabelas do banco de dados e seus relacionamentos"
"Quais colunas existem na tabela de usuários?"
"Forneça dados de amostra da tabela de produtos para testes"
"Encontre usuários criados na última semana para depuração"
"Existem restrições de chave estrangeira que eu deva conhecer?"
"Mostre-me o esquema da tabela de pedidos"

📊 Inteligência de Negócios

"Quais são nossos 5 produtos mais vendidos este mês?"
"Mostre-me clientes que não fizeram pedidos nos últimos 90 dias"
"Qual é o valor médio do pedido por região?"

🔍 Exploração de Dados

"Quantos registros existem na tabela de clientes?"
"Quais são as diferentes categorias de produtos que temos?"
"Mostre-me todos os pedidos feitos ontem"

📈 Análises

"Qual é a tendência de receita mensal deste ano?"
"Qual representante de vendas tem o melhor desempenho?"
"Encontre registros de clientes duplicados"

🐛 Depuração e Solução de Problemas

"Encontre registros órfãos na tabela order_items"
"Mostre-me usuários com endereços de e-mail ausentes"
"Quais são os códigos de erro mais comuns na nossa tabela de logs?"
"Encontre produtos que nunca foram pedidos"

⚙️ Opções de Configuração

Configurações do Banco de Dados

DB_SERVER=localhost\SQLEXPRESS    # SQL Server instance
DB_DATABASE=YourDatabase          # Target database
DB_USERNAME=                      # Username (optional for Windows Auth)
DB_PASSWORD=                      # Password (optional for Windows Auth)
DB_DRIVER=ODBC Driver 17 for SQL Server

Configurações da OpenAI

OPENAI_API_KEY=sk-...            # Your OpenAI API key
OPENAI_MODEL=gpt-4               # Model to use
OPENAI_MAX_TOKENS=2000           # Max tokens per request

Configurações do Servidor

MCP_SERVER_NAME=chatql-mcp-server
MCP_SERVER_VERSION=1.0.0
LOG_LEVEL=INFO                   # DEBUG, INFO, WARNING, ERROR
MAX_QUERY_RESULTS=100            # Limit query results
QUERY_TIMEOUT=30                 # Query timeout in seconds

Configurações de Segurança

SELECT_ONLY_MODE=false           # Start in SELECT-only mode
ALLOW_MODE_TOGGLE=true           # Allow clients to toggle modes

🔧 Conectando com Clientes de IA

Clientes MCP Suportados

Este servidor funciona com qualquer cliente compatível com MCP:

✅ Claude Desktop - Aplicativo desktop oficial da Anthropic
✅ Cursor AI - Editor de código com IA (Perfeito para desenvolvimento!)
✅ Outros Clientes MCP - Qualquer aplicativo que suporte o protocolo MCP

Como Funciona a Conexão MCP

Seu servidor ChatQL usa o Model Context Protocol (MCP) com comunicação stdio:

O cliente lê sua configuração → Encontra os detalhes do seu servidor
O cliente inicia seu servidor → Executa python server.py como um subprocesso
Comunica via stdin/stdout → Mensagens JSON por fluxos padrão
Seu servidor permanece em execução → Processa solicitações até o cliente fechar

1. Encontre o Arquivo de Configuração do Claude Desktop

Para usuários Windows (Passo a Passo):

Pressione Windows Key + R (abre a caixa de diálogo Executar)
Digite: %APPDATA% e pressione Enter
Procure a pasta "Claude" e clique duas vezes nela
Encontre o arquivo: claude_desktop_config.json
- Se o arquivo não existir, crie-o clicando com o botão direito → Novo → Documento de Texto
- Nomeie-o exatamente como: claude_desktop_config.json (não .txt!)

Para usuários Mac:

Pressione Cmd + Shift + G (abre Ir para Pasta)
Digite: ~/Library/Application Support/Claude/
Encontre ou crie: claude_desktop_config.json

2. Edite o Arquivo de Configuração

Abra o arquivo com o Bloco de Notas (Windows) ou TextEdit (Mac) e adicione isto:

{
  "mcpServers": {
    "chatql-mcp": {
      "command": "python",
      "args": ["C:/Users/YourUsername/Desktop/mcp/server.py"],
      "env": {
        "DB_SERVER": "localhost\\SQLEXPRESS",
        "DB_DATABASE": "YourDatabase",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

🚨 CRÍTICO: Substitua estes pelos SEUS valores reais:

C:/Users/YourUsername/Desktop/mcp/server.py → Seu caminho completo real para server.py
YourDatabase → Seu nome real do banco de dados
your-openai-api-key → Sua chave real da API OpenAI

💡 Como encontrar o caminho do seu server.py:

Navegue até sua pasta do projeto (onde você salvou o ChatQL)
Clique com o botão direito em server.py
Clique em "Propriedades" (Windows) ou "Obter Informações" (Mac)
Copie o caminho completo e cole-o na configuração

3. Inicie o Claude Desktop

Salve seu arquivo de configuração (Ctrl+S)
Feche o Claude Desktop completamente (clique com o botão direito no ícone da bandeja do sistema → Sair)
Reabra o Claude Desktop (ele lerá sua nova configuração)
Procure pelas ferramentas MCP na interface do Claude

4. Teste Sua Conexão

Depois que o Claude Desktop reiniciar, tente estas consultas de teste:

Consultas em Linguagem Natural:

"Quais tabelas estão disponíveis no meu banco de dados?"
"Mostre-me dados de amostra da tabela de clientes"
"Quantos registros existem em cada tabela?"

SQL Direto:

"Execute este SQL: SELECT TOP 5 * FROM SuaTabela"
"Obtenha as informações do esquema para a tabela de pedidos"

5. Indicadores de Sucesso

Quando o Claude conectar com sucesso, você verá:

🔧 Ferramentas MCP listadas no painel de ferramentas do Claude
📊 Respostas ricas do banco de dados com tabelas formatadas
⚡ Execução rápida de consultas do seu banco de dados
🛡️ Validações de segurança bloqueando consultas perigosas

Se a conexão falhar, verifique:

✅ O caminho do arquivo está correto na sua configuração
✅ O Python está no seu PATH
✅ Todas as dependências instaladas (pip install -r requirements.txt)
✅ A conexão com o banco de dados funciona (verifique seu arquivo .env)

🎯 Integração com Cursor AI (Desenvolvedores)

Por que Usar o ChatQL com o Cursor?

Transforme seu fluxo de trabalho de desenvolvimento conectando seu banco de dados diretamente ao Cursor AI:

🔍 Exploração Instantânea de Esquema - "Mostre-me todas as tabelas neste banco de dados"
📊 Análise Rápida de Dados - "Quais são os tipos de usuário mais comuns no nosso sistema?"
🐛 Depure Problemas de Dados - "Encontre usuários que têm pedidos mas não têm endereço de e-mail"
🏗️ Ajuda com Design de Banco de Dados - "Mostre-me o relacionamento entre as tabelas de usuários e pedidos"
⚡ Prototipagem Rápida - Obtenha dados de amostra para testes sem escrever SQL

Configurando com o Cursor

1. Configure o Cursor para MCP

Crie ou edite seu arquivo de configurações do Cursor:

Windows: %APPDATA%\Cursor\User\settings.json Mac: ~/Library/Application Support/Cursor/User/settings.json Linux: ~/.config/Cursor/User/settings.json

Adicione a configuração MCP:

{
  "mcp.servers": {
    "chatql-mcp": {
      "command": "python",
      "args": ["C:/path/to/your/project/server.py"],
      "env": {
        "DB_SERVER": "localhost\\SQLEXPRESS",
        "DB_DATABASE": "YourDatabase",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

2. Exemplos de Fluxos de Trabalho de Desenvolvimento

🔍 Exploração do Banco de Dados Durante o Desenvolvimento

Developer: "What tables do I have available?"
ChatQL: Shows all database tables with schemas

Developer: "Show me the structure of the users table"
ChatQL: Displays columns, data types, constraints, relationships

Developer: "Give me sample data from the orders table"
ChatQL: Returns formatted sample records

🐛 Depuração de Problemas de Dados

Developer: "Find all users created in the last 7 days"
ChatQL: Converts to SQL and shows recent users

Developer: "Are there any orphaned records in order_items?"
ChatQL: Checks for referential integrity issues

Developer: "Show me users with duplicate email addresses"
ChatQL: Finds and displays duplicate data

📊 Análises Rápidas para Recursos

Developer: "What's the distribution of user roles in our system?"
ChatQL: Groups and counts user roles

Developer: "Show me the average order value by month"
ChatQL: Generates time-based analytics

Developer: "Which products have never been ordered?"
ChatQL: Finds unused inventory

3. Benefícios Específicos do Cursor

🎯 Consciente do Contexto: O Cursor pode ver seu código e a estrutura do banco de dados simultaneamente
⚡ Extremamente Rápido: Sem alternância entre ferramentas de banco de dados e seu editor
🧠 Consultas Inteligentes: O Cursor entende o contexto do seu código para melhores perguntas
🔄 Desenvolvimento Iterativo: Faça perguntas de acompanhamento com base nos resultados das consultas
📝 Geração de Código: Gere código relacionado ao banco de dados com base em insights do esquema

4. Exemplo de Sessão de Desenvolvimento

# Working on a user dashboard feature
Developer: "Show me the user table structure"
ChatQL: Returns user schema with all fields

Developer: "What's the relationship between users and their orders?"
ChatQL: Shows JOIN relationships and foreign keys

Developer: "Give me sample data for testing the dashboard"
ChatQL: Returns realistic test data

Developer: "How many users registered each month this year?"
ChatQL: Generates registration analytics

# Cursor can now suggest code based on this database knowledge!

Outros Clientes MCP

Este servidor segue o protocolo MCP padrão e funciona com qualquer cliente compatível com MCP.

🛡️ Segurança e Proteção

Proteções Integradas

Validação de Consultas: Operações perigosas (DROP, TRUNCATE) são bloqueadas
Limitação de Resultados: Limites automáticos evitam esgotamento de memória
Consultas Parametrizadas: Proteção contra injeção de SQL
Pool de Conexões: Conexões de banco de dados seguras e eficientes
Modo Somente SELECT: Modo somente leitura alternável para maior segurança

🔒 Modo Somente SELECT

Um recurso de segurança poderoso que permite restringir operações do banco de dados a consultas somente leitura:

Como Funciona

Ativado: Apenas consultas SELECT são permitidas; todas as operações INSERT, UPDATE, DELETE, CREATE, DROP, ALTER são bloqueadas
Desativado: Todas as operações SQL são permitidas (com validações de segurança padrão)
Alternância: Pode ser ativado/desativado pelo cliente usando a ferramenta toggle_select_only_mode

Casos de Uso

🔍 Exploração de Dados: Navegação segura pelo conteúdo do banco de dados sem risco de modificação
📊 Relatórios e Análises: Gere relatórios com risco zero de corrupção de dados
👥 Colaboração em Equipe: Permita que membros da equipe explorem dados com segurança
🧪 Desenvolvimento: Teste consultas sem afetar dados de produção
📚 Aprendizado: Perfeito para aprender SQL sem riscos de modificação do banco de dados

Integração com o Cliente

No Claude Desktop ou Cursor:

# Enable SELECT-only mode
Ask: "Enable SELECT-only mode for safety"

# Check current status
Ask: "What is the current security mode?"

# Disable SELECT-only mode
Ask: "Disable SELECT-only mode to allow full access"

Opções de Configuração:

# Start server in SELECT-only mode
SELECT_ONLY_MODE=true

# Disable mode toggle (force current mode)
ALLOW_MODE_TOGGLE=false

Indicadores de Segurança

🔒 RESTRITO: Modo somente SELECT ativo
✅ SEM RESTRIÇÕES: Modo de acesso total ativo
❌ BLOQUEADO: Operação bloqueada pelo modo de segurança

Melhores Práticas

Comece com o modo somente SELECT ativado para novos ambientes
Use contas de banco de dados somente leitura quando possível
Nunca exponha o servidor à internet
Armazene credenciais com segurança usando variáveis de ambiente
Alterne regularmente chaves de API e senhas de banco de dados

🚨 Solução de Problemas

Problemas de Conexão com o Banco de Dados

Erro: "Nome da fonte de dados não encontrado"

# Install ODBC Driver 17 for SQL Server
# Download from Microsoft's official website

Erro: "Falha no login"

Verifique suas credenciais em .env
Para Autenticação do Windows, deixe usuário/senha vazios
Garanta que o SQL Server permita seu método de autenticação

Erro: "Erro do provedor Named Pipes"

Verifique se o SQL Server está em execução
Confira o nome do servidor (geralmente localhost\SQLEXPRESS)
Habilite TCP/IP no SQL Server Configuration Manager

Problemas com a API da OpenAI

Erro: "Chave da API da OpenAI não configurada"

Defina OPENAI_API_KEY no seu arquivo .env
Obtenha uma chave de API em https://platform.openai.com/

Erro: Limite de requisições

O servidor lida com limites de requisições de forma graciosa
Considere atualizar seu plano da OpenAI para limites maiores

🧪 Desenvolvimento

Executando Testes

# Tests coming soon!
python -m pytest

Estilo de Código

# Format code
black .

# Check style
flake8 .

# Type checking
mypy .

🏷️ Gerenciamento de Versão

Este projeto usa um sistema de versionamento centralizado com ferramentas automatizadas para contribuidores.

Comandos Rápidos de Versão

# Check current version
python version_manager.py current

# Bump version for bug fixes (1.0.0 → 1.0.1)
python version_manager.py bump patch

# Bump version for new features (1.0.1 → 1.1.0)
python version_manager.py bump minor

# Bump version for breaking changes (1.1.0 → 2.0.0)
python version_manager.py bump major

Diretrizes de Versionamento Semântico

PATCH (1.0.1) - Correções de bugs, patches de segurança
MINOR (1.1.0) - Novos recursos, adições de suporte a bancos de dados
MAJOR (2.0.0) - Mudanças que quebram compatibilidade, modificações na API

Fluxo Completo de Lançamento

Faça suas alterações e teste minuciosamente
Atualize o CHANGELOG.md com suas alterações em [Unreleased]

Aumente a versão usando o tipo apropriado:

python version_manager.py bump minor -m "Added PostgreSQL support"

Envie as alterações incluindo tags:
```
git push origin master --tags
```

Detalhes do Sistema de Versão

✅ Fonte única de verdade: __version__.py
✅ Tagging automático no git: Cria tags anotadas (v1.0.0, v1.1.0, etc.)
✅ Auto-commit: Faz commit das alterações de versão com mensagens adequadas
✅ Sem atualizações manuais: Todos os arquivos sincronizam automaticamente com a versão central

Opções Avançadas

# Set specific version
python version_manager.py set 1.2.3

# Skip git operations (for testing)
python version_manager.py bump patch --no-commit --no-tag

# Create tag with custom message
python version_manager.py tag -m "Hotfix release"

Nota para Contribuidores: Sempre use o script do gerenciador de versão em vez de editar manualmente os números de versão. Isso garante consistência em todos os arquivos do projeto.

🤝 Contribuindo

Aceitamos contribuições! Consulte CONTRIBUTING.md para detalhes sobre:

Configuração do ambiente de desenvolvimento
Padrões de código e melhores práticas
Processo de pull request

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Construído com o Model Context Protocol (MCP)
Desenvolvido com Modelos GPT da OpenAI
Usa SQLAlchemy para conectividade com bancos de dados

📞 Suporte

🐛 Encontrou um bug? Abra uma issue
💡 Tem uma solicitação de recurso? Inicie uma discussão
📧 Precisa de ajuda? Consulte nosso guia de solução de problemas

Feito com ❤️ por Raza Hasnain

ChatQL MCP Server

Documentação

Servidor MCP ChatQL

🗃️ Suporte a Bancos de Dados

🌟 Recursos

Recursos Principais do Banco de Dados

Integração para Desenvolvedores

Perfeito para Equipes de Desenvolvimento

🚀 Início Rápido

Pré-requisitos

Instalação

🛠️ Ferramentas Disponíveis

1. execute_natural_language_query

2. execute_direct_sql_query

3. get_table_information

4. list_database_tables

5. get_table_sample_data

6. toggle_select_only_mode 🔒

7. get_security_mode_status 🔒

📋 Exemplos de Consultas

💻 Fluxos de Trabalho de Desenvolvimento (Perfeito para Cursor)

📊 Inteligência de Negócios

🔍 Exploração de Dados

📈 Análises

🐛 Depuração e Solução de Problemas

⚙️ Opções de Configuração

Configurações do Banco de Dados

Configurações da OpenAI

Configurações do Servidor

Configurações de Segurança

🔧 Conectando com Clientes de IA

Clientes MCP Suportados

Como Funciona a Conexão MCP

1. Encontre o Arquivo de Configuração do Claude Desktop

2. Edite o Arquivo de Configuração

3. Inicie o Claude Desktop

4. Teste Sua Conexão

Consultas em Linguagem Natural:

SQL Direto:

5. Indicadores de Sucesso

🎯 Integração com Cursor AI (Desenvolvedores)

Por que Usar o ChatQL com o Cursor?

Configurando com o Cursor

1. Configure o Cursor para MCP

2. Exemplos de Fluxos de Trabalho de Desenvolvimento

🔍 Exploração do Banco de Dados Durante o Desenvolvimento

🐛 Depuração de Problemas de Dados

📊 Análises Rápidas para Recursos

3. Benefícios Específicos do Cursor

4. Exemplo de Sessão de Desenvolvimento

Outros Clientes MCP

🛡️ Segurança e Proteção

Proteções Integradas

🔒 Modo Somente SELECT

Como Funciona

Casos de Uso

Integração com o Cliente

Indicadores de Segurança

Melhores Práticas

🚨 Solução de Problemas

Problemas de Conexão com o Banco de Dados

Problemas com a API da OpenAI

🧪 Desenvolvimento

Executando Testes

Estilo de Código

🏷️ Gerenciamento de Versão

Comandos Rápidos de Versão

Diretrizes de Versionamento Semântico

Fluxo Completo de Lançamento

Detalhes do Sistema de Versão

Opções Avançadas

🤝 Contribuindo

📄 Licença

🙏 Agradecimentos

📞 Suporte

1. `execute_natural_language_query`

2. `execute_direct_sql_query`

3. `get_table_information`

4. `list_database_tables`

5. `get_table_sample_data`

6. `toggle_select_only_mode` 🔒

7. `get_security_mode_status` 🔒