QueryMind

sohv/QueryMind

3.2

If you are the rightful owner of QueryMind and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

QueryMind is a production-ready SQL agent that connects to real-time databases via MCP (Model Context Protocol).

Tools
6
Resources
0
Prompts
0

QueryMind

QueryMind is a production-ready SQL agent that connects to real-time databases via MCP (Model Context Protocol). It uses LLMs to generate SQL from natural language queries and includes robust safety, connection pooling, and monitoring features.

Architecture

User Query → MCP Server → Agent → Schema Retrieval (RAG) → SQL Generation (LLM) → Validation → Execution → Results

QueryMind uses a LangGraph-based workflow that coordinates multiple components:

  • Schema Retriever: ChromaDB-powered RAG for finding relevant database schemas
  • SQL Generator: LLM-based natural language to SQL conversion
  • SQL Validator: Security and syntax validation with injection prevention
  • Query Executor: Safe database execution with connection pooling and monitoring

Quick Start

Prerequisites

  • Python 3.11+
  • PostgreSQL database (local or remote)
  • OpenAI or Anthropic API key

Installation

  1. Clone and install dependencies:
git clone https://github.com/sohv/QueryMind.git
cd QueryMind
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
  1. Configure environment:
cp .env.example .env
# Edit .env with your database and API credentials
  1. Set up your database:
-- create a read-only user for safety (do it as superuser❗️)
CREATE USER querymind_readonly WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE your_database TO querymind_readonly;
GRANT USAGE ON SCHEMA public TO querymind_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO querymind_readonly;
  1. Test the setup:
python -c "from sql_agent.agent import Agent; from sql_agent.config import AgentConfig; agent = Agent(AgentConfig.from_env()); print('✅ Setup successful!')"

Usage

As MCP Server (Recommended)

Start the MCP server for AI agent integration:

mcp run sql_agent/mcp_server.py:app

For an interactive UI for testing the server locally, run:

 mcp dev sql_agent/mcp_server.py:app

Available MCP tools:

  • run_nl_query - Full pipeline for natural language queries
  • list_tables - Get all database tables
  • get_schema - Get table schema details
  • execute_query - Execute raw SQL (validated)
  • health_check - Monitor system health
  • refresh_schemas - Update schema embeddings

Direct Python Usage

from sql_agent.agent import Agent
from sql_agent.config import AgentConfig

# Initialize agent
config = AgentConfig.from_env()
agent = Agent(config)

# Simple query
result = agent.run("Show me the top 10 customers by order value")
print(result)

# Structured response for APIs
response = agent.run_structured("What products were ordered last month?")
print(f"SQL: {response['sql']}")
print(f"Results: {response['results']}")

FastAPI Server

Start the web API:

python -m sql_agent.api

Make requests:

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Find customers who ordered more than $1000 worth of products"}'

Configuration

Environment Variables

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/database

# LLM API Keys (set one or both)
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...

# Production Settings
DB_POOL_MIN=1
DB_POOL_MAX=10
ENABLE_QUERY_COST_ANALYSIS=true
LOG_ALL_QUERIES=false

# Query Safety Limits
MAX_QUERY_TIMEOUT=30
MAX_RESULT_ROWS=1000
MAX_RETRY_ATTEMPTS=2

Production Database Setup

Create a dedicated read-only user for maximum security:

-- PostgreSQL setup
CREATE USER querymind_readonly WITH PASSWORD 'secure_random_password';
GRANT CONNECT ON DATABASE production_db TO querymind_readonly;
GRANT USAGE ON SCHEMA public TO querymind_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO querymind_readonly;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO querymind_readonly;

-- For future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public 
GRANT SELECT ON TABLES TO querymind_readonly;

Docker Deployment

Development

docker-compose up -d

Production

# docker-compose.prod.yml
version: '3.8'
services:
  querymind:
    build: .
    environment:
      - DATABASE_URL=postgresql://readonly:${DB_PASSWORD}@db:5432/production
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - DB_POOL_MAX=20
      - ENABLE_QUERY_COST_ANALYSIS=true
    restart: unless-stopped
    
  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=production
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  postgres_data:

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Run the test suite: python -m pytest
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. Open a Pull Request

Support

  • Issues: Report bugs and request features via GitHub Issues
  • Documentation: Check the docs/ folder for detailed component documentation
  • Queries: For any further queries, reach out to me via this form