flowchart TD
    User([User Natural Language Query]) --> Orchestrator[Orchestrator Agent]
    Orchestrator --> Text2SQL[Text-to-SQL Agent]
    
    subgraph MCP ["Model Context Protocol (MCP) Server"]
        MCPServer[MCP Postgres / Hive Tools]
        DBSchema[get_db_schema]
        DBExec[execute_sql_query]
        DBVal[validate_sql_syntax]
    end
    
    subgraph Infrastructure ["Database Layer"]
        DB[(PostgreSQL / Hive Analytics DB)]
    end
    
    Text2SQL <-->|Tool Calls| MCPServer
    MCPServer <--> Infrastructure
    
    Text2SQL --> UAT[UAT / User Validation Agent]
    
    UAT -->|Syntax Error / Policy Violation| Text2SQL
    UAT -->|APPROVED & Validated| Narrative[Executive Narrative Agent]
    
    Narrative --> Output([Executive Business Report & Tabular Data])

mcp-text2sql-agent/
├── config/
│   ├── settings.py              # Application settings & environment loader
│   └── __init__.py
├── mcp_server/
│   ├── db_adapter.py            # PostgreSQL & Hive DB connection adapter
│   ├── server.py                # MCP Server tool registry & invocation handlers
│   └── __init__.py
├── src/
│   └── agents/
│       ├── state.py             # LangGraph state schema definition
│       ├── llm_factory.py       # Anthropic Claude & offline mock LLM provider
│       ├── orchestrator.py      # Master dispatch & dynamic router node
│       ├── text2sql_agent.py    # Text-to-SQL generation node
│       ├── uat_agent.py         # User validation & execution node
│       ├── narrative_agent.py   # Executive narrative synthesis node
│       └── graph.py             # LangGraph StateGraph assembly
├── docker/
│   ├── Dockerfile               # Multi-stage production build
│   └── init_db.sql              # Enterprise analytics sample database seed script
├── k8s/
│   ├── configmap.yaml           # Staging environment config map
│   ├── deployment.yaml          # Kubernetes deployment spec (2 replicas)
│   └── service.yaml             # Kubernetes cluster service spec
├── tests/
│   ├── test_mcp_server.py       # Unit tests for MCP server tools
│   ├── test_agents.py          # Unit tests for individual agent nodes
│   └── test_graph_workflow.py  # Integration tests for end-to-end workflow
├── main.py                      # CLI runner & interactive agent shell
├── docker-compose.yml           # Local staging container stack
├── pyproject.toml               # Build & pytest configuration
├── requirements.txt             # Python dependencies
└── README.md                    # Project documentation

git clone https://github.com/your-username/mcp-text2sql-agent.git
cd mcp-text2sql-agent

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install requirements
pip install -r requirements.txt

cp .env.example .env

ANTHROPIC_API_KEY=your_anthropic_api_key_here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
DB_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=analytics_db

python main.py --query "Show top 3 revenue generating product categories in Q3 2025"

python main.py --interactive

docker-compose up --build

kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

# Verify deployment status
kubectl get pods -n analytics-staging

python -m pytest tests/ -v

SELECT p.category, SUM(oi.quantity * oi.unit_price) AS total_revenue
FROM products p
JOIN order_items oi ON p.product_id = oi.product_id
JOIN orders o ON oi.order_id = o.order_id
WHERE o.status = 'COMPLETED'
GROUP BY p.category
ORDER BY total_revenue DESC
LIMIT 3;