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 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
Docker Desktop	docker.com
PowerShell 5.1+	Windows ile birlikte gelir
Google Gemini API Key	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:

.\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 GEMINI_API_KEY değerini mutlaka girin! API anahtarı olmadan pipeline çalışmaz.

Adım Adım Kurulum (Manuel)

# 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
.\scripts\run_server.ps1

# 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)

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.

Streamlit UI (Bonus Faz)

Pipeline'ı görsel arayüzle kullanın — sorgu, benchmark ve şema keşfi:

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

UI üç sayfa sunar (sidebar navigasyon):

Sayfa	İçerik
🔍 Sorgu	Doğal dil sorusu → SQL + sonuç + güven skoru (renk kodlu). Örnek soru butonları ve sorgu geçmişi.
📊 Benchmark	eval/results/ benchmark JSON'larını görselleştir — metrik kartları, Altair grafikleri, karşılaştırma modu.
🗄️ Şema	Veritabanı şema keşfi — tablolar, kolonlar, PK/FK, index, satır sayısı, örnek veri.

Not: UI için GEMINI_API_KEY ve çalışan PostgreSQL bağlantısı gerekir (sidebar'da durum gösterilir).

Testleri Çalıştırma

.\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ı

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
GEMINI_API_KEY	—	✅	Google Gemini 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

GEMINI_API_KEY almak için: aistudio.google.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 (GEMINI_API_KEY + PostgreSQL gerekir). Sonuçlar eval/results/ altına JSON olarak kaydedilir ve UI'ın Benchmark sayfasından görselleştirilir.

---

🔐 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

# 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