ikas MCP Server

English Version 🇬🇧

ikas e-ticaret platformu için MCP (Model Context Protocol) sunucusu. Bu sunucu, AI asistanlarına ikas mağaza verilerinize (müşteriler, siparişler, ürünler ve analizler) doğrudan erişim sağlar.

Özellikler

Müşteri Yönetimi

• get_customer - ID, e-posta veya telefon ile müşteri detaylarını getir
• list_customers - Filtreleme seçenekleriyle müşterileri listele
• search_customers - E-posta, telefon veya isimle müşteri ara
• get_customer_analytics - VIP durumu dahil kapsamlı analiz

Sipariş Yönetimi

• get_order - Detaylı sipariş bilgisi
• list_orders - Tarih ve durum filtresiyle siparişleri listele
• get_customer_orders - Belirli bir müşterinin tüm siparişleri
• search_orders - Numara, e-posta veya duruma göre sipariş ara
• get_order_status - Sipariş teslimat durumunu takip et

Ürün Kataloğu

• list_products - Kategori ve durum filtresiyle ürünleri listele
• search_products - İsim, SKU veya açıklamaya göre ara
• get_product_inventory - Stok seviyeleri ve düşük stok uyarıları
• get_product_variants - Tüm varyantları seçenekleriyle görüntüle

Analizler

• get_revenue_analytics - Gün/hafta/ay bazında gelir raporları
• get_vip_customers - Seviyeye göre VIP müşterileri belirle
• get_abandoned_carts - Terk edilmiş sepet kurtarma fırsatları
• get_campaign_performance - Pazarlama kampanyası metrikleri

Envanter Yönetimi 🆕

• list_inventory - Envanter öğelerini filtrelerle listele
• get_low_stock_items - Düşük stok veya stokta olmayan ürünleri getir
• get_inventory_movements - Envanter hareket geçmişini görüntüle
• update_inventory - Stok seviyelerini güncelle (mutation gerektirir)
• get_inventory_valuation - Toplam envanter değerlemesi ve en değerli ürünler

Pazarlama ve Promosyonlar 🆕

• list_marketing_campaigns - Pazarlama kampanyalarını performans metrikleriyle listele
• list_promotions - Aktif promosyonları ve indirim kodlarını görüntüle
• get_campaign_analytics - Belirli bir kampanyanın detaylı analizini al
• list_coupons - Tüm kuponları kullanım istatistikleriyle listele
• create_coupon - Yeni indirim kuponu oluştur (mutation gerektirir)
• get_marketing_dashboard - Kapsamlı pazarlama panosu

Finansal Analizler 🆕

• list_transactions - Finansal işlemleri filtreleme seçenekleriyle listele
• get_financial_summary - Detaylı finansal özet ve döküm
• get_tax_report - Bölgesel ve ürün bazında vergi raporu
• get_revenue_report - Çeşitli boyutlara göre gruplandırılmış gelir raporu
• get_cashflow_analysis - Son 30 günlük nakit akışı analizi

Otomasyon ve Müşteri Hizmetleri 🆕

• list_support_tickets - Müşteri destek biletlerini listele
• get_ticket_details - Destek bileti detaylarını görüntüle
• get_customer_service_stats - Müşteri hizmetleri performans istatistikleri
• suggest_automations - Veri desenlerine dayalı otomasyon önerileri
• create_automation_rule - Yeni otomasyon kuralı oluştur (mutation gerektirir)

Sayfalama Desteği

Sunucu, ikas API'nin hem cursor tabanlı hem de sayfa tabanlı sayfalama sistemlerini destekler. Büyük veri setlerini işlerken, sunucu otomatik olarak tüm sayfaları getirir ve tek bir yanıtta birleştirir.

Özellikler:

• Otomatik sayfalama: Tüm veriler otomatik olarak getirilir
• İki sayfalama türü desteği:
  • Cursor tabanlı (müşteriler, siparişler gibi)
  • Sayfa tabanlı (ürünler, envanter gibi)
• Tam veri setleri: Test scriptleri gibi tüm verileri tek seferde alabilirsiniz
• Performans optimizasyonu: Büyük veri setleri için verimli işleme

Kullanım:

Sayfalama otomatik olarak yönetilir. Herhangi bir liste fonksiyonunu çağırdığınızda, sunucu:

1. İlk sayfayı getirir
2. Daha fazla sayfa varsa, otomatik olarak sonraki sayfaları alır
3. Tüm sonuçları birleştirerek size sunar

Bu sayede, binlerce müşteri, sipariş veya ürün olsa bile tüm verilere erişebilirsiniz.

Kurulum

1. Repository'yi klonlayın:

git clone <repository-url>
cd ikas-mcp-server

2. Bağımlılıkları yükleyin:

npm install

3. TypeScript kodunu derleyin:

npm run build

4. Örnek .env dosyasından kendi dosyanızı oluşturun:

cp .env.example .env

5. .env dosyasında ikas kimlik bilgilerinizi yapılandırın:

IKAS_STORE_NAME=magazanizin-adi
IKAS_CLIENT_ID=client-id-niz
IKAS_CLIENT_SECRET=client-secret-iniz

Claude Desktop ile Kullanım

1. Claude Desktop yapılandırma dosyanızı açın:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

2. ikas MCP sunucu yapılandırmasını ekleyin:

{
  "mcpServers": {
    "ikas": {
      "command": "node",
      "args": ["/mutlak/yol/ikas-mcp-server/build/index.js"],
      "env": {
        "IKAS_STORE_NAME": "magazanizin-adi",
        "IKAS_CLIENT_ID": "client-id-niz",
        "IKAS_CLIENT_SECRET": "client-secret-iniz"
      }
    }
  }
}

3. Claude Desktop'ı yeniden başlatın

VIP Müşteri Seviyeleri

Varsayılan VIP Seviyeleri

Sunucu varsayılan olarak şu VIP seviyelerini kullanır:

• SILVER: ₺3.000+ toplam harcama, 2+ sipariş
• GOLD: ₺6.000+ toplam harcama, 3+ sipariş
• PLATINUM: ₺12.000+ toplam harcama, 5+ sipariş

Özel VIP Yapılandırması

VIP seviyelerini özelleştirmek için .env dosyanıza VIP_TIERS değişkenini ekleyin:

VIP_TIERS='[
  {
    "name": "BRONZE",
    "minSpend": 1000,
    "minOrders": 1,
    "benefits": ["3% indirim", "₺300 üzeri ücretsiz kargo"],
    "color": "#CD7F32",
    "icon": "🥉"
  },
  {
    "name": "SILVER",
    "minSpend": 3000,
    "minOrders": 2,
    "benefits": ["5% indirim", "Satışlara erken erişim", "₺500 üzeri ücretsiz kargo"],
    "color": "#C0C0C0",
    "icon": "🥈"
  },
  {
    "name": "GOLD",
    "minSpend": 6000,
    "minOrders": 3,
    "benefits": ["10% indirim", "Öncelikli destek", "Tüm siparişlerde ücretsiz kargo"],
    "color": "#FFD700",
    "icon": "🥇"
  },
  {
    "name": "PLATINUM",
    "minSpend": 12000,
    "minOrders": 5,
    "benefits": ["15% indirim", "Özel müşteri temsilcisi", "Ücretsiz hızlı kargo", "VIP ürünlere erişim"],
    "color": "#E5E4E2",
    "icon": "💎"
  }
]'

VIP Yapılandırma Parametreleri:

• name: Seviye adı (zorunlu)
• minSpend: Minimum harcama tutarı (zorunlu)
• minOrders: Minimum sipariş sayısı (zorunlu)
• benefits: Avantajlar listesi (zorunlu)
• color: Seviye rengi (isteğe bağlı, hex formatında)
• icon: Seviye ikonu (isteğe bağlı, emoji)

Geliştirme

Geliştirme Modunda Çalıştırma

npm run dev

MCP Inspector ile Test

npx @modelcontextprotocol/inspector node build/index.js

Tip Kontrolü

npm run typecheck

Linting

npm run lint

API Hız Limitleri

ikas API'sinin hız limitleri vardır. Sunucu şunları uygular:

• Otomatik token yenileme (4 saatlik süre)
• Başarısız istekler için yeniden deneme mantığı
• Düzgün hata işleme ve kullanıcı dostu mesajlar

Güvenlik Notları

• .env dosyanızı asla commit etmeyin
• Kimlik bilgilerini güvenli bir şekilde saklayın
• Production için ortam değişkenlerini kullanın
• OAuth tokenları yalnızca bellekte önbelleğe alınır

Sorun Giderme

Kimlik Doğrulama Hataları

• Mağaza adınızın tam olarak eşleştiğini doğrulayın (.myikas.com olmadan)
• Client ID ve secret'ın doğru olduğunu kontrol edin
• Uygulamanızın ikas admin'de uygun izinlere sahip olduğundan emin olun

Bağlantı Sorunları

• İnternet bağlantınızı kontrol edin
• API endpoint'inin erişilebilir olduğunu doğrulayın
• Claude Desktop günlüklerinde hata mesajlarını arayın

Eksik Veri

• Marketplace siparişleri için bazı alanlar null olabilir
• Müşteri ID'leri filtreleme ve yanıt verileri arasında farklılık gösterir
• En iyi sonuçlar için uygun arama yöntemlerini kullanın

Katkıda Bulunma

1. Repository'yi fork edin
2. Özellik dalı oluşturun
3. Değişikliklerinizi yapın
4. Testleri ve linting'i çalıştırın
5. Pull request gönderin

Lisans

MIT Lisansı - detaylar için LICENSE dosyasına bakın

Star History