YOKATLAS API MCP Sunucusu

YOKATLAS MCP: Türk Yükseköğretim Atlası için MCP Sunucusu

Bu proje, YÖKATLAS verilerine erişimi kolaylaştıran bir FastMCP sunucusu oluşturur. Bu sayede, YÖKATLAS'tan lisans ve önlisans program arama ve detaylı istatistik getirme işlemleri, Model Context Protocol (MCP) destekleyen LLM (Büyük Dil Modeli) uygulamaları (örneğin Claude Desktop veya 5ire) ve diğer istemciler tarafından araç (tool) olarak kullanılabilir hale gelir.

🎯 Temel Özellikler

• YÖKATLAS tercih kılavuzu JSON API'sine programatik erişim için standart bir MCP arayüzü.
• Aşağıdaki yetenekler:
  • Birleşik Akıllı Arama: Lisans + önlisans tek arama; fuzzy matching ile üniversite/program/il adı çözümlemesi (örn: "boğaziçi" → "BOĞAZİÇİ ÜNİVERSİTESİ")
  • 4 Yıllık İstatistik: Her programa ait kontenjan, yerleşen, taban puanı, başarı sırası, akademik kadro ve KPSS verileri tek seferde (current + 3 history)
  • Net Sihirbazı: Son yerleşen kişinin ders bazında net sayıları (TYT/AYT/YDT), taban puan, OBP ve katsayı
  • Lookup Araçları: Üniversite, program grubu ve il listelerine doğrudan erişim
  • Filtreleme: Puan türü (SAY/SÖZ/EA/DİL/TYT), üniversite türü (DEVLET/VAKIF), başarı sırası aralığı, sayfalama ve sıralama
• Claude Desktop uygulaması ile fastmcp install komutu (veya manuel yapılandırma) kullanılarak kolay entegrasyon.
• YOKATLAS MCP 5ire gibi Claude Desktop haricindeki MCP istemcilerini de destekler.

⚠️ v0.6.0 Breaking Change — YÖK Atlas Nisan 2026'da React tabanlı SPA'ya geçti, eski HTML scraping endpoint'leri ve detaylı atlas verileri (cinsiyet/lise alanı dağılımı, akademisyen ünvan dağılımı, KPSS yıllara göre, vb.) site genelinden kaldırıldı. Bu MCP yeni JSON API'ye karşı yazıldı; sadece resmî API'nin sunduğu temel istatistikler döner.

---

🚀 5 Dakikada Başla (Remote MCP)

✅ Kurulum Gerektirmez! Hemen Kullan!

🔗 Remote MCP Adresi: https://yokatlasmcp.fastmcp.app/mcp

Claude Desktop ile Kullanım

1. Claude Desktop'ı açın
2. Settings → Connectors → Add Custom Connector
3. Bilgileri girin:
   • Name: YOKATLAS MCP
   • URL: https://yokatlasmcp.fastmcp.app/mcp
4. Add butonuna tıklayın
5. Hemen kullanmaya başlayın! 🎉

Google Antigravity ile Kullanım

1. Agent session açın ve editörün yan panelindeki "…" dropdown menüsüne tıklayın
2. MCP Servers seçeneğini seçin - MCP Store açılacak
3. Üstteki Manage MCP Servers butonuna tıklayın
4. View raw config seçeneğine tıklayın
5. mcp_config.json dosyasına aşağıdaki yapılandırmayı ekleyin:

{
  "mcpServers": {
    "yokatlas-mcp": {
      "serverUrl": "https://yokatlasmcp.fastmcp.app/mcp/",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
}

💡 İpucu: Remote MCP sayesinde Python, uv veya herhangi bir kurulum yapmadan doğrudan Claude Desktop üzerinden YÖKATLAS verilerine erişebilirsiniz!

---

🚀 Claude Haricindeki Modellerle Kullanmak İçin Çok Kolay Kurulum (Örnek: 5ire için)

Bu bölüm, YOKATLAS MCP aracını 5ire gibi Claude Desktop dışındaki MCP istemcileriyle kullanmak isteyenler içindir.

• Python Kurulumu: Sisteminizde Python 3.12 kurulu olmalıdır. Kurulum sırasında "Add Python to PATH" (Python'ı PATH'e ekle) seçeneğini işaretlemeyi unutmayın. Buradan indirebilirsiniz.

• Git Kurulumu (Windows): Bilgisayarınıza git yazılımını indirip kurun. "Git for Windows/x64 Setup" seçeneğini indirmelisiniz.

• uv Kurulumu:

  • Windows Kullanıcıları (PowerShell): Bir CMD ekranı açın ve bu kodu çalıştırın: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • Mac/Linux Kullanıcıları (Terminal): Bir Terminal ekranı açın ve bu kodu çalıştırın: curl -LsSf https://astral.sh/uv/install.sh | sh

• Microsoft Visual C++ Redistributable (Windows): Bazı Python paketlerinin doğru çalışması için gereklidir. Buradan indirip kurun.

• İşletim sisteminize uygun 5ire MCP istemcisini indirip kurun.

• 5ire'ı açın. Workspace -> Providers menüsünden kullanmak istediğiniz LLM servisinin API anahtarını girin.

• Tools menüsüne girin. +Local veya New yazan butona basın.

  • Tool Key: yokatlasmcp
  • Name: YOKATLAS MCP
  • Command:

    uvx --from git+https://github.com/saidsurucu/yokatlas-mcp yokatlas-mcp
    

  • Save butonuna basarak kaydedin.

• Şimdi Tools altında YOKATLAS MCP'yi görüyor olmalısınız. Üstüne geldiğinizde sağda çıkan butona tıklayıp etkinleştirin (yeşil ışık yanmalı).

• Artık YOKATLAS MCP ile konuşabilirsiniz.

---

⚙️ Claude Desktop Manuel Kurulumu

1. Ön Gereksinimler: Python, uv, (Windows için) Microsoft Visual C++ Redistributable'ın sisteminizde kurulu olduğundan emin olun. Detaylı bilgi için yukarıdaki "5ire için Kurulum" bölümündeki ilgili adımlara bakabilirsiniz.

2. Claude Desktop Settings -> Developer -> Edit Config.

3. Açılan claude_desktop_config.json dosyasına mcpServers altına ekleyin:

   {
     "mcpServers": {
       "YOKATLAS MCP": {
         "command": "uvx",
         "args": [
           "--from", "git+https://github.com/saidsurucu/yokatlas-mcp",
           "yokatlas-mcp"
         ]
       }
     }
   }
   

4. Claude Desktop'ı kapatıp yeniden başlatın.

---

🛠️ Kullanılabilir Araçlar (MCP Tools)

Bu FastMCP sunucusu LLM modelleri için aşağıdaki araçları sunar:

🔍 Arama

• search_programs: Lisans + önlisans birleşik arama (akıllı fuzzy matching).

  • Parametreler:
    • degree_type: 'bachelor' (lisans) veya 'associate' (önlisans). Boş bırakılırsa ikisi de döner.
    • puan_turu: SAY, SÖZ/SOZ, EA, DİL/DIL, TYT (ASCII varyantlar otomatik normalize edilir).
    • universite, program, il: Smart fuzzy match (örn. "boğaziçi", "bilgisayar", "ankara").
    • universite_turu: DEVLET veya VAKIF.
    • kilavuz_kodu: int — tek programa filtre (eski "atlas detayı" use-case'i için).
    • min_basari_sirasi, max_basari_sirasi: Başarı sırası aralığı.
    • page, size, sort_by, direction: Sayfalama ve sıralama (default: basariSirasi ASC, size=20, max size=500).
  • Döndürülen Veri: Her sonuç 4 yıllık istatistikleri (current + history) içerir: kontenjan, yerleşen, taban puanı, başarı sırası, KPSS skorları, akademik kadro sayıları.

• search_netler: Net Sihirbazı — son yerleşen kişinin ders bazında net sayıları.

  • Parametreler:
    • universite, program: Smart fuzzy match (tekil değer, liste değil). program çözümlendiğinde, puan_turu açıkça belirtilmemişse eşleşen program grubundan otomatik doldurulur.
    • puan_turu: SAY, SÖZ/SOZ, EA, DİL/DIL, TYT.
    • universite_turu: DEVLET veya VAKIF.
    • yil: Belirli bir yıla filtrele (örn. 2024).
    • katsayi: Puan hesaplamasında kullanılan katsayıya göre filtrele.
    • page, size: Sayfalama (default: size=20, max size=500).
  • Döndürülen Veri: puan_turu'ye göre değişen net alanları (TYT her zaman var; SAY/SÖZ/EA/DİL kendi AYT/YDT alanlarını ekler), ayrıca katsayi, taban_puan, obp.

📚 Lookup Araçları

• list_universities: YÖKATLAS'taki tüm üniversiteleri (universite_id, universite_adi) listeler.
• list_program_groups: Tüm program gruplarını (birim_grup_id, birim_grup_adi, puan_turu) listeler — geçerli program filtre değerlerini keşfetmek için kullanın.
• list_cities: 81 ili (il_kodu, il_adi) listeler.

🔄 v0.5 → v0.6 Migration

Eski API'den geçenler için kısaca:

Eski (v0.5)	Yeni (v0.6)
search_bachelor_degree_programs	search_programs(degree_type='bachelor', ...)
search_associate_degree_programs	search_programs(degree_type='associate', ...)
get_bachelor_degree_atlas_details(yop_kodu, year)	search_programs(kilavuz_kodu=N) (4 yıllık veri search içinde)
get_associate_degree_atlas_details(yop_kodu, year)	search_programs(kilavuz_kodu=N)
score_type	puan_turu (TYT eklendi)
fee_type / education_type / availability	Kaldırıldı (yeni API'de doğrudan karşılığı yok)
yop_kodu (str)	kilavuz_kodu (int)

---

📜 Lisans

Bu proje MIT Lisansı altında lisanslanmıştır. Detaylar için LICENSE dosyasına bakınız.