# Text2SQL-MCP

> Doğal dili, çok katmanlı güvenlik validasyonu ile güvenli SQL'e çeviren MCP (Model Context Protocol) sunucusu.

Text2SQL-MCP, LLM tabanlı ajanların PostgreSQL veritabanlarına **sadece okuma (read-only)** erişimle sorgu yapabilmesini sağlar. MCP protokolü üzerinden üç tool sunar:

- `run_query(sql)` — Güvenli SELECT sorgusu çalıştırma (5 katmanlı validasyon).
- `get_schema(tables)` — Veritabanı şema bilgisi.
- `get_table_sample(table, limit)` — Tablodan örnek veri.

Detaylı mimari için [ARCHITECTURE.md](ARCHITECTURE.md) dosyasına bakın.

---

## ✨ Özellikler

- ✅ **5 katmanlı SQL validasyonu** (syntax, statement type, schema cross-check, injection detection, resource guard)
- ✅ **Read-only garantisi** — `llm_reader` kullanıcısı sadece SELECT yetkisine sahip
- ✅ **Defense in depth** — multi-statement tespiti, `statement_timeout`, row limit, LIMIT otomatik ekleme
- ✅ **MCP Protocol** — Claude Desktop, Cursor ve diğer MCP istemcileriyle uyumlu
- ✅ **Chinook DB** — 11 tablolu, 600KB örnek müzik veritabanı (DVD Rental alternatifi)
- ✅ **RAG desteği** — glossary + gold queries + schema ile ChromaDB tabanlı bağlam geri getirme (MMR + threshold)

---

## 📋 Gereksinimler

| Gereksinim | Açıklama |
|-----------|----------|
| **Python 3.11+** | [python.org](https://www.python.org/downloads/) |
| **Docker Desktop** | [docker.com](https://www.docker.com/products/docker-desktop/) |
| **PowerShell 5.1+** | Windows ile birlikte gelir |
| **Google Gemini API Key** | [aistudio.google.com](https://aistudio.google.com/) — ücretsiz kayıt |

---

## ⚡ Windows'ta Hızlı Kurulum (PowerShell)

**Yönetici PowerShell'de** proje kök dizininde şu komutu çalıştırın:

```powershell
.\scripts\setup.ps1
```

Bu script şunları yapar:

1. ✅ Python sanal ortamı (venv) oluşturur
2. ✅ Bağımlılıkları yükler (pip install -r requirements.txt)
3. ✅ `.env` dosyasını oluşturur (`.env.example`'dan kopyalar)
4. ✅ Docker container'ını başlatır (PostgreSQL + Chinook DB otomatik yüklenir)
5. ✅ `data/schema.yaml` şema dosyasını çıkarır
6. ✅ Testleri çalıştırmaya hazır hale gelir

> **⚠️ ÖNEMLİ:** Kurulumdan sonra `.env` dosyasını açıp `GROQ_API_KEY` değerini **mutlaka girin!** API anahtarı olmadan pipeline çalışmaz.

### Adım Adım Kurulum (Manuel)

```powershell
# 1. Python sanal ortamı
python -m venv venv

# 2. Bağımlılıklar
.\venv\Scripts\pip install -r requirements.txt

# 3. Ortam değişkenleri
Copy-Item .env.example -Destination .env
# Şimdi .env dosyasını düzenleyip ANTHROPIC_API_KEY ekleyin!

# 4. PostgreSQL + Chinook DB'yi başlat (Docker)
docker compose up -d

# 5. Şemayı çıkar
.\venv\Scripts\python scripts\extract_schema.py

# 6. Testleri çalıştır
.\venv\Scripts\pytest tests\ -v
```

---

## 🗄️ Kullanılan Veritabanı: Chinook

Bu proje **Chinook müzik veritabanı** ile birlikte gelir. DVD Rental yerine ücretsiz ve açık kaynak bir alternatiftir.

**Chinook tabloları (11 adet):**

| Tablo | Kayıt | Açıklama |
|-------|-------|----------|
| `album` | 347 | Müzik albümleri |
| `artist` | 275 | Sanatçılar |
| `customer` | 59 | Müşteriler |
| `employee` | 8 | Çalışanlar |
| `genre` | 25 | Müzik türleri |
| `invoice` | 412 | Faturalar |
| `invoice_line` | 2240 | Fatura satırları |
| `media_type` | 5 | Medya türleri |
| `playlist` | 18 | Çalma listeleri |
| `playlist_track` | 8715 | Çalma listesi-parça eşleşmesi |
| `track` | 3503 | Müzik parçaları |

> 💡 **İpucu:** Chinook, DVD Rental'a benzer bir e-ticaret yapısına sahiptir (müşteri, fatura, ödeme). Bu sayede aynı türde SQL sorguları (JOIN, aggregation, filtering) çalıştırabilirsiniz.

---

## 🚀 Kullanım

### MCP Server'ı Başlatma

```powershell
# PowerShell
.\scripts\run_server.ps1
```

```bash
# Linux/Mac veya WSL
./scripts/run_server.sh
# veya
make server
```

Server stdio üzerinden MCP protokolü ile konuşur. Claude Desktop, Cursor veya özel bir MCP istemcisi ile entegre edilebilir.

### Pipeline ile Sorgu Çalıştırma (Faz 3)

```python
from pipeline.orchestrator import Orchestrator

pipeline = Orchestrator()
response = pipeline.process("En çok satan 5 sanatçı kimdir?")
print(response.formatted_answer)
```

`Orchestrator` doğal dili alır, RAG bağlamı ile birleştirir, Gemini üzerinde SQL üretir, güven skoru hesaplar ve sonucu markdown olarak formatlar.

### React Frontend (Modern UI)

Tamamen yeniden inşa edilmiş, Linear/Vercel kalitesinde React 19 + Vite + Tailwind v4 arayüz:

```powershell
# Frontend'i geliştirme modunda başlat
cd frontend
npm install   # (ilk seferde, bağımlılıkları yükler)
npm run dev   # http://localhost:5173
```

```powershell
# Production build (backend ile birlikte serve edilir)
cd frontend
npm run build
# Backend, frontend/dist/ klasörünü otomatik serve eder
```

**10 sayfa, karanlık-öncelikli tasarım sistemi ile:**

| Sayfa | Endpoint | İçerik |
|-------|----------|--------|
| **⚡ Query** | `POST /query` | Hero sayfa — doğal dil girişi, pipeline progress animasyonu, typewriter efektli cevap, Gauge güven skoru, SQL CodeBlock, sonuç tablosu |
| **📊 Dashboard** | `GET /dashboard/*` | KPI kartları (animasyonlu count-up), aylık gelir area chart, top artists, tür dağılımı donut |
| **🗄️ Schema** | `GET /schema` | Sol liste + sağ detay, PK/FK rozetleri, bağlantılı navigasyon |
| **📈 Benchmark** | `GET /benchmark/*` | %96 accuracy Gauge, zorluk/kategori bar grafikleri, self-correction highlight |
| **🔄 dbt** | `GET /dbt/*` | Layer gruplı model listesi, upstream/downstream DAG, run/test |
| **🔗 Lineage** | `GET /lineage*` | Pipeline flow görseli, ETL çalıştırma, geçmiş |
| **📡 Streaming** | `GET /streaming/*` | Canlı metrikler (5sn polling), simülatör kontrolü |
| **☁️ Big Data** | `GET /spark/*` | 5 Spark job kartı (RFM, forecast, market-basket) |
| **🔬 Research** | `POST /research/profile` | Tablo profilleri grid |
| **⚙️ Settings** | `GET /settings` | Health status, API/DB konfigürasyonu, hassas değer maskeleme |

> Tüm sayfalarda **skeleton loading, empty state, error state (retry butonlu)** state'leri mevcut.

### Streamlit UI (Legacy)

Eski Streamlit arayüzü hâlâ `ui/` klasöründe mevcut:

```powershell
.\venv\Scripts\streamlit run ui/app.py
```

### Testleri Çalıştırma

```powershell
.\venv\Scripts\pytest tests\ -v
```

### Faydalı Komutlar

| Komut | Açıklama |
|-------|----------|
| `.\scripts\setup.ps1` | Tüm ortamı kurar |
| `.\venv\Scripts\pytest tests\ -v` | Testleri çalıştırır |
| `.\scripts\run_server.ps1` | MCP server'ı başlatır |
| `.\venv\Scripts\python scripts\extract_schema.py` | Şemayı günceller |
| `docker compose up -d` | PostgreSQL'i başlatır |
| `docker compose down` | PostgreSQL'i durdurur |
| `make index` | RAG index'ini oluşturur/günceller |
| `.\venv\Scripts\streamlit run ui/app.py` | Streamlit UI'ı başlatır |
| `.\venv\Scripts\python eval/run_benchmark.py` | Benchmark çalıştırır (sonuçlar `eval/results/`) |
| `.\scripts\teardown.ps1` | Ortamı temizler |

---

## 🔧 Proje Yapısı

```text
text2sql-mcp/
├── .env.example              # Ortam değişkenleri şablonu
├── .github/workflows/ci.yml  # GitHub Actions CI pipeline
├── README.md                 # Bu dosya
├── ARCHITECTURE.md           # Mimari dokümanı
├── docker-compose.yml        # PostgreSQL + Chinook DB
├── requirements.txt          # Python bağımlılıkları
├── data/
│   ├── Chinook_PostgreSql.sql  # Chinook veritabanı dump'ı (otomatik yüklenir)
│   ├── schema.yaml             # Çıkarılan şema (otomatik oluşturulur)
│   ├── glossary.yaml           # Chinook terimleri sözlüğü (RAG)
│   └── gold_queries.yaml       # Soru-SQL örnek çiftleri (RAG)
├── mcp_server/
│   ├── server.py              # MCP Protocol Server (3 tool)
│   └── validators.py          # 5 katmanlı SQL validasyonu
├── scripts/
│   ├── setup.ps1              # PowerShell: Ortam kurulumu (WINDOWS)
│   ├── run_server.ps1         # PowerShell: Server başlatma (WINDOWS)
│   ├── teardown.ps1           # PowerShell: Ortam temizliği (WINDOWS)
│   ├── setup.sh               # Bash: Ortam kurulumu (Linux/Mac/WSL)
│   ├── run_server.sh          # Bash: Server başlatma (Linux/Mac/WSL)
│   ├── teardown.sh            # Bash: Ortam temizliği (Linux/Mac/WSL)
│   ├── setup_db.sh            # Docker init: llm_reader kullanıcısı
│   ├── extract_schema.py      # Şema çıkarıcı
│   └── index_glossary.py      # RAG index oluşturucu
├── tests/
│   ├── test_validators.py     # Validasyon testleri (49 test)
│   ├── test_server.py         # Server handler testleri (24 test)
│   ├── test_extract_schema.py # Schema extractor testleri (3 test)
│   ├── test_glossary_yaml.py  # Glossary YAML testleri (15 test)
│   ├── test_gold_queries_yaml.py # Gold queries YAML testleri (40 test)
│   ├── test_embedder.py       # Embedding wrapper testleri (16 test)
│   ├── test_indexer.py        # ChromaDB indexer testleri (19 test)
│   └── test_retriever.py      # Context retriever testleri (19 test)
├── rag/                       # RAG sistemi (Faz 2)
│   ├── embedder.py            # SentenceTransformers embedding wrapper
│   ├── indexer.py             # ChromaDB index yöneticisi
│   └── retriever.py           # MMR + threshold ile bağlam geri getirme
├── pipeline/                  # NL2SQL pipeline (Faz 3+)
│   ├── orchestrator.py        # 7 adımlı pipeline orkestratörü
│   ├── confidence.py          # Güven skoru hesaplayıcı
│   └── formatter.py           # Markdown response formatter
├── eval/                      # Benchmark sistemi (Faz 5)
│   ├── run_benchmark.py       # Benchmark runner (CLI + kütüphane)
│   ├── metrics.py             # Metrik hesaplayıcı + rapor
│   ├── test_set.yaml          # 25 test sorusu (5 kategori)
│   └── results/               # Benchmark sonuç JSON'ları (otomatik)
├── ui/                        # Streamlit arayüzü (Bonus Faz)
│   ├── app.py                 # Ana giriş — multi-page navigation
│   └── pages/
│       ├── query.py           # 🔍 Sorgu sayfası
│       ├── benchmark.py       # 📊 Benchmark sayfası
│       └── schema.py          # 🗄️ Şema sayfası
```

---

## 🌐 Çevre Değişkenleri

`.env.example` dosyasını `.env` olarak kopyalayıp düzenleyin:

| Değişken | Varsayılan | Zorunlu | Açıklama |
|----------|-----------|---------|----------|
| `POSTGRES_HOST` | `localhost` | ✅ | PostgreSQL sunucu adresi |
| `POSTGRES_PORT` | `5432` | ✅ | PostgreSQL portu |
| `POSTGRES_DB` | `chinook` | ✅ | Veritabanı adı |
| `POSTGRES_USER` | `llm_reader` | ✅ | Read-only kullanıcı |
| `POSTGRES_PASSWORD` | `llm_reader_pass_123` | ✅ | Kullanıcı şifresi |
| `GROQ_API_KEY` | — | ✅ | **Groq/LLM API anahtarı (pipeline için zorunlu)** |
| `QUERY_TIMEOUT_SEC` | `30` | ❌ | Sorgu zaman aşımı (saniye) |
| `MAX_ROWS` | `1000` | ❌ | Maksimum dönen satır sayısı |
| `MAX_RETRIES` | `3` | ❌ | LLM sorgu deneme sayısı |
| `CONFIDENCE_THRESHOLD` | `60` | ❌ | Pipeline güven skoru eşiği |
| `CHROMA_PERSIST_DIR` | `./chroma_data` | ❌ | ChromaDB kalıcı veri dizini (Faz 2) |
| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | ❌ | SentenceTransformers model adı (Faz 2) |
| `LOG_LEVEL` | `INFO` | ❌ | Log seviyesi |

> **GROQ_API_KEY almak için:** [console.groq.com](https://console.groq.com/) adresine gidin, ücretsiz API key oluşturun.

---

## 🔬 Test Durumu

✅ **277/277 test geçiyor** — Validasyon, server handler, schema extractor, RAG (glossary, gold queries, embedder, indexer, retriever), Faz 3 pipeline/agent, Faz 5 benchmark ve Streamlit UI testleri.

Testler `unittest.mock` kullanır, gerçek PostgreSQL bağlantısı **gerektirmez**.

---

## 📅 Fazlar

| Faz | Durum | İçerik |
|-----|-------|--------|
| **Faz 0** | ✅ Tamamlandı | Proje iskeleti, MCP server, 5 katmanlı validasyon |
| **Faz 1** | ✅ Tamamlandı | Şema çıkarma, environment setup, 76/76 test |
| **Faz 2** | ✅ Tamamlandı | RAG sistemi: glossary (32 terim), gold queries (25 çift), ChromaDB index, MMR retriever, 179/179 test |
| **Faz 3** | ✅ Tamamlandı | NL2SQL pipeline + LLM entegrasyonu |
| **Faz 5** | ✅ Tamamlandı | Benchmark sistemi (25 test, metrik hesaplayıcı, CLI runner) |
| **Bonus** | ✅ Tamamlandı | Streamlit UI (Sorgu + Benchmark + Şema sayfaları) |

> **Benchmark sonuçları:** Henüz çalıştırılmayı bekliyor. Çalıştırmak için `python eval/run_benchmark.py` (GROQ_API_KEY + PostgreSQL gerekir). Sonuçlar `eval/results/` altına JSON olarak kaydedilir.

---

## 🔐 Güvenlik Mimarisi

| Katman | Açıklama |
|--------|----------|
| **L1 Syntax** | sqlglot ile SQL parse + multi-statement tespiti |
| **L2 Statement** | Sadece SELECT (ve UNION/INTERSECT/EXCEPT) izinli |
| **L3 Schema** | Sorgudaki tablo/kolonlar schema.yaml ile karşılaştırılır |
| **L4 Injection** | pg_sleep, lo_import, COPY, XP_ vs. pattern eşleştirme |
| **L5 Resource** | LIMIT yoksa otomatik ekle, subquery sınırı |

Ek olarak: `conn.set_session(readonly=True)` + `statement_timeout=30s` + `fetchmany(max_rows=1000)`

---

## 🐳 Docker ile Çalıştırma

```powershell
# Container'ı başlat
docker compose up -d

# Logları izle
docker compose logs -f

# Container'ı durdur
docker compose down

# Tamamen sıfırla (volume dahil)
docker compose down -v
```

---

## 📦 CI/CD

GitHub Actions workflow'u (`.github/workflows/ci.yml`):

- Python 3.11 kurulumu
- pip install -r requirements.txt
- pytest tests/ -v --tb=short
- Lint check (ruff, optional)

---

## 📄 Lisans

MIT