mcp-anlatim

halilkkaya/mcp-anlatim

3.3

If you are the rightful owner of mcp-anlatim and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Model Context Protocol (MCP) is a revolutionary protocol that standardizes AI models' access to external data sources, enabling real-time interactions with databases.

🚗 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
ParametreTipAçıklamaÖrnek
markastr/listAraç markası"toyota" veya ["ford", "bmw"]
modelstrModel adı"focus", "corolla"
min_fiyat/max_fiyatintFiyat aralığı50000, 200000
min_yil/max_yilintModel yılı2015, 2023
min_km/max_kmintKilometre aralığı0, 100000
ilstrŞehir"istanbul", "ankara"
yakitstrYakıt türü"benzin", "dizel", "hibrit"
vitesstrVites türü"manuel", "otomatik"
durumstrAraç durumu"yeni", "mükemmel", "iyi"
tipstrAraç tipi"sedan", "suv", "hatchback"
renkstrAraç rengi"beyaz", "siyah", "gri"
ozel_aramastrÖzel kategoriler"ekonomik", "lüks", "aile", "spor"
siralamastrSıralama"fiyat_artan", "yil_yeni", "km_az"
limitintSonuç sayısı5 (varsayılan)
detayliboolDetaylı bilgiTrue/False
benzer_araclarboolBenzer önerilerTrue/False
istatistikboolİstatistiksel veriTrue/False

🔧 Diğer Tools

ToolAçıklamaKullanım
sql_sorgusu_calistirÖzel SQL sorgularıGelişmiş analiz
tablolari_listeleVeritabanı tablolarıYapı keşfi
tablo_yapisi_gosterTablo şemasıSütun bilgileri
web_aramaTavily 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ı

🛠️ Teknik Detaylar

🔧 Kullanılan Teknolojiler

KategoriTeknolojiVersiyon
AI ModelsAnthropic Claude3.5 Haiku
OpenAI GPT3.5 Turbo
MCP FrameworkFastMCPLatest
DatabaseMySQL8.0+
Web FrameworkStreamlitLatest
ML FrameworkLangChainLatest
Search APITavilyv1

⚙️ Sistem Gereksinimleri

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

🔧 API Anahtarları

ServisNeden GerekliÜcretsiz Limitler
AnthropicClaude AI model$5 kredi
OpenAIGPT model$5 kredi
TavilyWeb 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 dosyasına bakın.

👨‍💻 Geliştirici

Halil Kaya

🙏 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