iflow-mcp_halilkkaya_mcp-anlatim 0.1.0

AI-based vehicle gallery assistant using Model Context Protocol (MCP)

🚗 MCP Araç Arama Sistemi - AI Tabanlı Araç Galeri Asistanı

Bu proje, Model Context Protocol (MCP) kullanarak AI asistanlarına gerçek zamanlı araç veritabanı erişimi sağlayan kapsamlı bir örnek uygulamadır. Claude, ChatGPT gibi büyük dil modellerinin veritabanlarıyla nasıl etkileşim kurabileceğini gösterir.

🎯 Proje Özeti

MCP (Model Context Protocol), AI modellerinin dış veri kaynaklarına standartlaştırılmış şekilde erişmesini sağlayan devrimsel bir protokoldür. Bu proje, araç galeri senaryosu üzerinden MCP'nin gücünü pratik olarak göstermektedir.

🔥 Temel Özellikler

• 🤖 AI Asistanı: Claude ile doğal dil kullanarak araç arama
• 🗄️ MCP Server: MySQL veritabanına güvenli erişim
• 📊 Gelişmiş Filtreleme: 15+ farklı arama kriteri
• 🌐 Web Entegrasyonu: Tavily API ile güncel araç bilgileri
• 📱 Çoklu Arayüz: Terminal, Streamlit ve web tabanlı
• 🔒 Güvenlik: Parametrized queries ile SQL injection koruması

🏗️ Proje Mimarisi

📦 Dosya Yapısı

mcp-anlatim/
├── 📱 Uygulamalar
│   ├── app.py              # Ana terminal uygulaması (Claude + MCP)
│   ├── appst.py            # Streamlit web uygulaması-mcpsiz (OpenAI + LangChain)
│   └── mcpanlatim.py       # Kapsamlı eğitim ve demo uygulaması
├── 🔧 MCP Server
│   └── dataturkmcp.py      # FastMCP tabanlı araç arama server'ı
├── 🗄️ Veri
│   └── veri.xlsx           # Excel format araç verileri
├── 📋 Yapılandırma
│   ├── requirements.txt    # Python bağımlılıkları
│   └── .env               # Ortam değişkenleri (API anahtarları)
├── 📚 Dokümantasyon
│   ├── README.md          # Bu dosya
│   ├── kaynak.txt         # Kaynaklar ve bağlantılar
│   └── *.png, *.jpeg      # Görsel materyaller
└── 📄 LICENSE             # MIT lisansı

🚀 Hızlı Başlangıç

1️⃣ Kurulum

# Projeyi klonla
git clone https://github.com/halilkkaya/mcp-anlatim.git
cd mcp-anlatim

# Sanal ortam oluştur (önerilen)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# veya
venv\Scripts\activate     # Windows

# Bağımlılıkları yükle
pip install -r requirements.txt

2️⃣ Ortam Değişkenlerini Ayarla

.env dosyası oluşturun:

# AI API Anahtarları
ANTHROPIC_API_KEY=your_claude_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

# Veritabanı Ayarları
MYSQL_HOST=localhost
MYSQL_USER=root
MYSQL_PASSWORD=your_mysql_password
MYSQL_DATABASE=mcp_deneme

# Web Arama API'si
TAVILY_API_KEY=your_tavily_api_key

# MCP Server URL'i
MCP_URL=http://localhost:8000/mcp

3️⃣ Veritabanını Hazırla

# MySQL'de veritabanı oluştur
mysql -u root -p
CREATE DATABASE mcp_deneme;
USE mcp_deneme;

# Araç verilerini import et (varsa)
# Veya SQLite dosyasını kullan: arabalar.db

4️⃣ Uygulamaları Çalıştır

🎓 Eğitim ve Demo (Önerilen)

streamlit run mcpanlatim.py

Kapsamlı MCP anlatımı, tool tanıtımları ve canlı test ortamı

🖥️ Terminal Uygulaması

python app.py

Claude ile terminal tabanlı araç asistanı

🌐 Web Uygulaması

streamlit run appst.py

OpenAI tabanlı web araç danışmanı

⚙️ MCP Server

python dataturkmcp.py

8000 portunda MCP server başlatır

🛠️ MCP Tools (Araçlar)

🔍 araba_ara - Ana Arama Tool'u

Gelişmiş filtreleme seçenekleri ile araç arama:

# Temel filtreleme
araba_ara(
    marka="toyota",           # Araç markası
    model="corolla",          # Model adı  
    min_fiyat=100000,         # Minimum fiyat
    max_fiyat=500000,         # Maksimum fiyat
    il="istanbul"             # Şehir
)

# Gelişmiş özellikler
araba_ara(
    ozel_arama="ekonomik",    # Önceden tanımlı kategoriler
    siralama="fiyat_artan",   # Sıralama tipi
    limit=10,                 # Sonuç sayısı
    detayli=True,             # Detaylı bilgiler
    istatistik=True           # İstatistiksel veriler
)

📋 Tam Parametre Listesi

Parametre	Tip	Açıklama	Örnek
marka	str/list	Araç markası	"toyota" veya ["ford", "bmw"]
model	str	Model adı	"focus", "corolla"
min_fiyat/max_fiyat	int	Fiyat aralığı	50000, 200000
min_yil/max_yil	int	Model yılı	2015, 2023
min_km/max_km	int	Kilometre aralığı	0, 100000
il	str	Şehir	"istanbul", "ankara"
yakit	str	Yakıt türü	"benzin", "dizel", "hibrit"
vites	str	Vites türü	"manuel", "otomatik"
durum	str	Araç durumu	"yeni", "mükemmel", "iyi"
tip	str	Araç tipi	"sedan", "suv", "hatchback"
renk	str	Araç rengi	"beyaz", "siyah", "gri"
ozel_arama	str	Özel kategoriler	"ekonomik", "lüks", "aile", "spor"
siralama	str	Sıralama	"fiyat_artan", "yil_yeni", "km_az"
limit	int	Sonuç sayısı	5 (varsayılan)
detayli	bool	Detaylı bilgi	True/False
benzer_araclar	bool	Benzer öneriler	True/False
istatistik	bool	İstatistiksel veri	True/False

🔧 Diğer Tools

Tool	Açıklama	Kullanım
sql_sorgusu_calistir	Özel SQL sorguları	Gelişmiş analiz
tablolari_listele	Veritabanı tabloları	Yapı keşfi
tablo_yapisi_goster	Tablo şeması	Sütun bilgileri
web_arama	Tavily API araması	Güncel bilgiler

💡 Örnek Kullanım Senaryoları

🏠 Aile Aracı Arama

araba_ara(
    ozel_arama="aile",
    min_fiyat=100000,
    max_fiyat=300000,
    yakit="dizel",
    siralama="fiyat_artan"
)

⚡ Ekonomik Araç Bulma

araba_ara(
    ozel_arama="ekonomik",
    max_fiyat=150000,
    yakit=["hibrit", "dizel"],
    limit=10
)

🏎️ Lüks Spor Araç

araba_ara(
    marka=["bmw", "mercedes", "audi"],
    tip="coupe",
    ozel_arama="lüks",
    min_yil=2020,
    detayli=True
)

📊 Pazar Analizi

araba_ara(
    marka="toyota",
    istatistik=True,
    benzer_araclar=True,
    limit=20
)

🤖 AI Asistan Örnekleri

💬 Doğal Dil Sorguları

Kullanıcı: "Aileme uygun, ekonomik bir araç arıyorum"
AI: araba_ara(ozel_arama="aile", yakit="dizel", siralama="fiyat_artan")

Kullanıcı: "BMW veya Mercedes, 2020 sonrası, coupe"  
AI: araba_ara(marka=["bmw", "mercedes"], tip="coupe", min_yil=2020)

Kullanıcı: "İstanbul'da 200 bin TL altı Toyota araçlar"
AI: araba_ara(marka="toyota", il="istanbul", max_fiyat=200000)

🔒 Güvenlik Özellikleri

• 🛡️ SQL Injection Koruması: Parametrized queries
• 🔐 API Anahtarı Güvenliği: Ortam değişkenleri
• 🚫 Erişim Kontrolü: Aktif kayıt filtreleme
• ⚠️ Hata Yönetimi: Güvenli hata mesajları
• 🔍 Input Validation: Parametre doğrulama

📈 Performans Optimizasyonları

• 📊 Veritabanı İndeksleri: Hızlı sorgular
• 🔗 Connection Pooling: Kaynak yönetimi
• 📝 Query Logging: Performans takibi
• ⚡ Caching: Yanıt hızlandırma

🎓 MCP Öğrenme Kaynakları

• 📺 YouTube: MCP Server Anlatımı
• 📚 HuggingFace: MCP Kursu

🛠️ Teknik Detaylar

🔧 Kullanılan Teknolojiler

Kategori	Teknoloji	Versiyon
AI Models	Anthropic Claude	3.5 Haiku
	OpenAI GPT	3.5 Turbo
MCP Framework	FastMCP	Latest
Database	MySQL	8.0+
Web Framework	Streamlit	Latest
ML Framework	LangChain	Latest
Search API	Tavily	v1

⚙️ Sistem Gereksinimleri

• Python: 3.8+
• RAM: 2GB+ (önerilen 4GB)
• Disk: 1GB boş alan
• Network: İnternet bağlantısı (API'lar için)

🔧 API Anahtarları

Servis	Neden Gerekli	Ücretsiz Limitler
Anthropic	Claude AI model	$5 kredi
OpenAI	GPT model	$5 kredi
Tavily	Web araması	1000 arama/ay

📋 Kurulum Sorun Giderme

❌ Yaygın Sorunlar

1. ModuleNotFoundError

pip install -r requirements.txt

2. Database Connection Error

# MySQL servisinin çalıştığından emin olun
# .env dosyasındaki credentials'ları kontrol edin

3. API Key Errors

# .env dosyasındaki API anahtarlarını kontrol edin
# Anahtarların geçerli olduğundan emin olun

4. Port Already in Use

# MCP server için farklı port kullanın
python dataturkmcp.py --port 8001

🤝 Katkıda Bulunma

1. Fork yapın
2. Feature branch oluşturun (git checkout -b feature/amazing-feature)
3. Commit yapın (git commit -m 'Add amazing feature')
4. Push yapın (git push origin feature/amazing-feature)
5. Pull Request açın

📄 Lisans

Bu proje MIT lisansı altında yayınlanmıştır. Detaylar için LICENSE dosyasına bakın.

👨‍💻 Geliştirici

Halil Kaya

• 🌐 GitHub: @halilkkaya

🙏 Teşekkürler

• Anthropic - Claude AI modeli
• OpenAI - GPT modelleri
• FastMCP - MCP framework
• Tavily - Web arama API'si
• Streamlit - Web arayüzü

---

⭐ Bu projeyi beğendiyseniz yıldız vermeyi unutmayın!

📧 Sorularınız için: Issues bölümünü kullanın

🔄 Güncellemeler için: Repository'yi watch edin