halilkkaya/mcp-anlatim
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
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
- Fork yapın
- Feature branch oluşturun (
git checkout -b feature/amazing-feature
) - Commit yapın (
git commit -m 'Add amazing feature'
) - Push yapın (
git push origin feature/amazing-feature
) - 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
- 🌐 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