Staging

.env.example

@@ -1,37 +1,109 @@
-# Example configuration for text2sql with AI-generated user responses
+# QueryWeaver example environment file
+# Copy this to `.env` and edit values before running the app or the Docker image:
+#
+#   cp .env.example .env
+#   # edit .env
+#
+# Minimal required variables for a basic run (these are left uncommented below):
+# - FASTAPI_SECRET_KEY  (REQUIRED)
+# - FALKORDB_URL       (REQUIRED) — preferred single connection string for FalkorDB
+#
+# Optional (commented) variables are provided as examples; uncomment and set them
+# only if you need the functionality (OAuth, AI keys, local host/port overrides, etc.).
 
-## API Keys for LiteLLM (required for AI functionality)
-# Azure OpenAI
+# -----------------------------
+# Application / Server settings
+# -----------------------------
+# REQUIRED: secret used by FastAPI session middleware — change this before running in production
+FASTAPI_SECRET_KEY=your_super_secret_key_here
+
+# Optional: enable debug/reload when running the app directly
+# FASTAPI_DEBUG=False
+
+# Optional: set application environment (development, staging, production)
+# Default: development
+# APP_ENV=development
+
+# Optional: allow OAuth over HTTP in development (disable in production)
+# OAUTHLIB_INSECURE_TRANSPORT=1
+
+# -----------------------------
+# FalkorDB connection (REQUIRED / preferred)
+# -----------------------------
+# Preferred: single connection URL. Edit to point at your FalkorDB/Redis instance.
+# Example: redis://localhost:6379/0
+FALKORDB_URL=redis://localhost:6379/0  # REQUIRED - change to your FalkorDB URL
+
+# Optional: separate host/port settings for local testing (only used if FALKORDB_URL is not set)
+# FALKORDB_HOST=localhost
+# FALKORDB_PORT=6379
+
+# -----------------------------
+# Optional API / secret tokens
+# -----------------------------
+# API token for internal API access (optional)
+# SECRET_TOKEN=your_secret_token
+# SECRET_TOKEN_ERP=your_erp_token
+
+# -----------------------------
+# AI / LLM configuration (optional)
+# -----------------------------
+# The default is to use Azure OpenAI if all three variables are set.
+# If the OPENAI_API_KEY is set, it will use OpenAI directly.
+
+# Azure OpenAI (example)
 # AZURE_API_KEY=your_azure_api_key
 # AZURE_API_BASE=https://your-resource.openai.azure.com/
 # AZURE_API_VERSION=2023-05-15
 
-# OpenAI
+# OpenAI (example)
 # OPENAI_API_KEY=your_openai_api_key
 
-# Google OAuth for authentication
-GOOGLE_CLIENT_ID=your_google_client_id
-GOOGLE_CLIENT_SECRET=your_google_client_secret
-
-# GitHub OAuth for authentication
-GITHUB_CLIENT_ID=your_github_client_id
-GITHUB_CLIENT_SECRET=your_github_client_secret
+# Optional: override default model names from api/config.py
+# COMPLETION_MODEL=azure/gpt-4.1
+# EMBEDDING_MODEL=azure/text-embedding-ada-002
 
-# FASTAPI configuration
-FASTAPI_SECRET_KEY=your_super_secret_key_here
+# -----------------------------
+# OAuth configuration (optional — uncomment to enable login flows)
+# -----------------------------
+# Google OAuth
+# GOOGLE_CLIENT_ID=your_google_client_id
+# GOOGLE_CLIENT_SECRET=your_google_client_secret
 
-# FalkorDB configuration
-FALKORDB_HOST=localhost
-FALKORDB_PORT=6379
+# GitHub OAuth
+# GITHUB_CLIENT_ID=your_github_client_id
+# GITHUB_CLIENT_SECRET=your_github_client_secret
 
-# Optional tokens for API access
-SECRET_TOKEN=your_secret_token
-SECRET_TOKEN_ERP=your_erp_token
+# If your OAuth app uses a different base URL than the request base (e.g., using 127.0.0.1 vs localhost)
+# you can override the base used for building callback URLs. Example:
+# OAUTH_BASE_URL=http://localhost:5000
 
-# AI Model Configuration (adjust as needed)
-# These are set in api/config.py but can be overridden via environment variables
-# COMPLETION_MODEL=azure/gpt-4.1  # Model used for SQL generation and response formatting
-# EMBEDDING_MODEL=azure/text-embedding-ada-002  # Model used for embeddings
+# -----------------------------
+# Email Configuration (optional - for sending invitation emails)
+# -----------------------------
+# MAIL_SERVER=smtp.mailgun.org
+# MAIL_PORT=587
+# MAIL_USE_TLS=True
+# MAIL_USERNAME=your_mail_username
+# MAIL_PASSWORD=your_mail_password
+# MAIL_DEFAULT_SENDER=noreply@yourdomain.com
+# EMAIL_AUTH_ENABLED=false
 
-# Google Tag Manager (optional)
+# -----------------------------
+# Frontend / analytics (optional)
+# -----------------------------
+# Google Tag Manager ID (optional)
 # GOOGLE_TAG_MANAGER_ID=GTM-XXXXXXX
+
+# -----------------------------
+# Optional MCP (Model Context Protocol) settings
+# -----------------------------
+# Control QueryWeaver's built-in MCP endpoints (default: enabled)
+# Set to "true" to disable mounting the MCP HTTP surface without editing code
+# DISABLE_MCP=false
+
+# Notes
+# -----------------------------
+# - Keep secrets out of source control. Use your local `.env` (ignored by git) or a secrets manager in production.
+# - For Docker runs, pass `--env-file .env` to `docker run` or provide individual `-e` args.
+# - See api/config.py for additional runtime configuration defaults and model overrides.

.github/copilot-instructions.md

@@ -18,18 +18,27 @@ QueryWeaver is an open-source Text2SQL tool that transforms natural language int
 
 ## Essential Build & Validation Commands
 
-**CRITICAL**: Always run these commands in the exact order specified. Many commands will fail if prerequisites are not met.
+Follow this order for a reliable local setup; if you customize the steps, ensure each prerequisite (dependencies, `.env`, Playwright) is completed.
 
-### 1. Initial Setup (Required for all operations)
+### 1. Initial Setup (recommended for new contributors)
 ```bash
 # Install pipenv if not available
 pip install pipenv
 
-# Install all dependencies (ALWAYS run this first)
+# Install dependencies (backend + frontend) and prepare dev tools
+# Recommended: use the Make helper which installs Python deps and frontend deps
 make install
-# OR manually: pipenv sync --dev
 
-# Set up environment file (REQUIRED)
+# Prepare the full development environment (installs Playwright browsers too)
+# This runs `make install` then Playwright install steps.
+make setup-dev
+
+# OR manual steps if you prefer more granular control:
+# pipenv sync --dev
+# pipenv run playwright install chromium
+# pipenv run playwright install-deps
+
+# Set up environment file
 cp .env.example .env
 # Edit .env with required values (see Environment Setup section)
 ```
@@ -50,7 +59,7 @@ pipenv run playwright install-deps
 ### 3. Testing Commands
 ```bash
 # IMPORTANT: Unit tests require FalkorDB running or will fail with connection errors
-# Start FalkorDB for testing (requires Docker)
+# You can start a local test FalkorDB using the included Make helper
 make docker-falkordb
 
 # Run unit tests only (safer, doesn't require browser)
@@ -122,22 +131,28 @@ make clean
 
 ## Environment Setup Requirements
 
-**CRITICAL**: Create `.env` file from `.env.example` and configure these essential variables:
+Create `.env` file from `.env.example` and configure these essential variables:
 
 ```bash
 # REQUIRED for FastAPI to start
 FASTAPI_SECRET_KEY=your_super_secret_key_here
-FASTAPI_DEBUG=False
 
-# REQUIRED for database connection (most functionality)
-FALKORDB_HOST=localhost
-FALKORDB_PORT=6379
+# Optional: set application environment (development, staging, production)
+# Default: development (affects session cookie security for OAuth)
+APP_ENV=development
+
+# REQUIRED for database connection (preferred)
+# Use a single connection string if possible. Example:
+# FALKORDB_URL=redis://localhost:6379/0
+
+# Optional: enable debug/reload when running the app directly
+# FASTAPI_DEBUG=False
 
-# REQUIRED for full functionality (OAuth)
-GOOGLE_CLIENT_ID=your_google_client_id
-GOOGLE_CLIENT_SECRET=your_google_client_secret
-GITHUB_CLIENT_ID=your_github_client_id
-GITHUB_CLIENT_SECRET=your_github_client_secret
+# REQUIRED for full functionality (OAuth, only if you use login flows)
+# GOOGLE_CLIENT_ID=your_google_client_id
+# GOOGLE_CLIENT_SECRET=your_google_client_secret
+# GITHUB_CLIENT_ID=your_github_client_id
+# GITHUB_CLIENT_SECRET=your_github_client_secret
 
 # OPTIONAL: AI model configuration (defaults in api/config.py)
 # AZURE_API_KEY=your_azure_api_key
@@ -147,6 +162,7 @@ GITHUB_CLIENT_SECRET=your_github_client_secret
 **For testing in CI/development**, minimal `.env` setup:
 ```bash
 FASTAPI_SECRET_KEY=test-secret-key
+APP_ENV=development
 FASTAPI_DEBUG=False
 FALKORDB_HOST=localhost
 FALKORDB_PORT=6379
@@ -267,7 +283,7 @@ All workflows follow this pattern:
 - Python 3.12 setup
 - pipenv installation
 - pipenv sync --dev
-- .env file creation with test values
+- .env file creation with test values (use FALKORDB_URL in CI)
 - FalkorDB service startup (for tests requiring DB)
 - Playwright browser installation (for E2E tests)
 ```
@@ -307,6 +323,45 @@ Before submitting any changes, run these validation steps:
 - `tests/e2e/README.md`: Comprehensive E2E testing documentation
 - `setup_e2e_tests.sh`: Automated test environment setup script
 
+### MCP (Model Context Protocol)
+
+QueryWeaver optionally exposes an MCP HTTP surface (mounted at `/mcp`) to allow external MCP clients to call QueryWeaver's Text2SQL operations. Key points for coding agents and reviewers:
+
+- Runtime toggle: the built-in MCP endpoints can be disabled with the env var `DISABLE_MCP=true`. Default behavior is enabled.
+- Client config: consumers typically use an `mcp.json` (or client-specific config) that points to the MCP URL, for example:
+
+```json
+{
+   "servers": {
+      "queryweaver": { 
+         "type": "http", 
+         "url": "http://127.0.0.1:5000/mcp", 
+         "headers": { 
+            "Authorization": "Bearer your_token_here" 
+         } 
+      }
+   },
+   "inputs": []
+}
+```
+
+- Tools and examples: projects like GitMCP show common client configurations for Cursor, VSCode, and other MCP-capable tools; use those patterns for guidance when writing docs or adding examples in this repo.
+- Security: avoid embedding bearer tokens in repo files. Prefer runtime injection via env files or secret managers. If you need to demonstrate a token in tests, use mocked tokens and don't commit them.
+
+Example: generate `mcp.json` from an environment token (pseudo):
+
+```bash
+export MQW_TOKEN="secret-token"
+cat > mcp.json <<EOF
+{
+   "servers": {"queryweaver": {"type":"http","url":"http://127.0.0.1:5000/mcp","headers":{"Authorization":"Bearer ${MQW_TOKEN}"}}},
+   "inputs": []
+}
+EOF
+```
+
+If you change MCP wiring or add integrations, update `README.md` and `.env.example` accordingly and add tests that run with MCP enabled/disabled to cover both code paths.
+
 ## Trust These Instructions
 
 These instructions have been validated by running all commands and testing the complete workflow. Only search for additional information if:

.github/wordlist.txt

@@ -43,4 +43,33 @@ frontend
 Frontend
 js
 npm
-deps
+deps
+backend
+Backend
+dropdown
+cryptographically
+SHA
+auth
+lookups
+http
+Quickstart
+MCP
+QueryWeaver's
+dev
+FastAPI
+
+ai
+https
+queryweaver
+json
+JSON
+openapi
+OpenAPI
+CLI
+namespace
+namespaced
+
+CSRF
+LLM
+OpenAI
+OpenAI's

.github/workflows/e2e-tests.yml

@@ -2,9 +2,9 @@ name: E2E Tests
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ main, staging ]
   pull_request:
-    branches: [ main, develop ]
+    branches: [ main, staging ]
 
 permissions:
   contents: read

.github/workflows/tests.yml

@@ -2,9 +2,9 @@ name: Tests
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ main, staging ]
   pull_request:
-    branches: [ main, develop ]
+    branches: [ main, staging ]
 
 permissions:
   contents: read
@@ -63,7 +63,6 @@ jobs:
 
   e2e-tests:
     runs-on: ubuntu-latest
-    needs: unit-tests
 
     services:
       falkordb:

.gitignore

@@ -19,3 +19,4 @@ tmp_*
 node_modules/
 /app/public/js/*
 .jinja_cache/
+demo_tokens.py

Makefile

@@ -8,7 +8,7 @@ help: ## Show this help message
 
 install: ## Install dependencies
 	pipenv sync --dev
-	npm install ./app
+	npm install --prefix ./app
 
 
 setup-dev: install ## Set up development environment

Pipfile

@@ -6,7 +6,7 @@ name = "pypi"
 [packages]
 fastapi = "~=0.116.1"
 uvicorn = "~=0.35.0"
-litellm = "~=1.75.9"
+litellm = "~=1.76.0"
 falkordb = "~=1.2.0"
 psycopg2-binary = "~=2.9.9"
 pymysql = "~=1.1.0"
@@ -16,6 +16,7 @@ jsonschema = "~=4.25.0"
 tqdm = "~=4.67.1"
 python-multipart = "~=0.0.10"
 jinja2 = "~=3.1.4"
+fastapi-mcp = "~=0.4.0"
 graphiti-core = {ref = "staging", git = "git+https://github.com/FalkorDB/graphiti.git"}
 
 [dev-packages]