<p align="center"><img src="docs/img/banner.svg" alt="iu-mcp"></p>

# iu-mcp

**Resmî olmayan**, açık kaynaklı bir [Model Context Protocol (MCP)](https://modelcontextprotocol.io) sunucusu. İstanbul Üniversitesi öğrencileri Claude'a okul hakkında soru sorar; cevaplar üniversitenin kendi herkese açık sayfalarından gelir ve her cevapta kaynak bağlantısı vardır.

> **İstanbul Üniversitesi ile bağlantısı yoktur.** Bağımsız bir öğrenci projesidir; üniversite tarafından onaylanmamış, işletilmemiştir ve üniversite logosu kullanmaz. Önemli tarihleri her cevaptaki resmî bağlantıdan doğrula.

Türkçe · [English](README.en.md)

## Ne yapar

Sekiz araç. Claude soruna göre doğru olanı kendisi seçer.

| Araç | Ne cevaplar | Kaynak (herkese açık, giriş yok) |
|---|---|---|
| `akademik_takvim` | Dönem başı/sonu, final ve bütünleme haftaları, ders ekleme-bırakma, bir sonraki önemli tarihe kaç gün kaldığı | 2026-2027 resmî önlisans/lisans takvim PDF'i, [ogrenci.istanbul.edu.tr](https://ogrenci.istanbul.edu.tr/tr/content/akademik-takvim/onlisans-lisans) |
| `yemekhane_menusu` | Günün (ya da 7 güne kadar) kahvaltı, öğle, akşam ve vegan menüsü | [sks.istanbul.edu.tr/yemek-listesi](https://sks.istanbul.edu.tr/yemek-listesi) |
| `duyurular_listesi` | 9 fakültenin öğrenci duyuruları, duyurular, haberler, etkinlikler (varsayılan BBTF) | fakülte siteleri |
| `ders_programi` | Güncel dönemin program ve sınıf bazında ders programı bağlantıları, fakültenin duyurduğu önemli notlar (hangi dersler AKSİS yerine web programına göre takip edilir) | fakülte sitesi |
| `fakulte_sayfasi` | Staj kuralları, SSS, Erasmus anlaşmaları, değişim programları… fakülte sitesindeki bilgi sayfaları. Konu vermezsen mevcut sayfa listesini döner | fakülte siteleri (9 fakülte) |
| `ders_bilgisi` | Ders kodu/adıyla AKTS, öğretim üyesi, amaç, haftalık konular, not dağılımı | [ebs.istanbul.edu.tr](https://ebs.istanbul.edu.tr) (varsayılan: Bilgisayar Mühendisliği) |
| `mufredat` | Hangi sınıfta hangi dersler, AKTS toplamı | EBS |
| `gno_hesapla` | Harf notlarından dönem ve genel not ortalaması (AKTS ağırlıklı, özel ölçek verilebilir). Tamamen çevrimdışı | yok |

Ayrıca `haftalik_ozet` prompt'u: tek tıkla haftalık özet (yaklaşan tarihler, duyurular, bugünün menüsü).

**Bilerek yok:** giriş isteyen hiçbir sistem (OBS, AKSİS). Sunucu öğrenci kimlik bilgisi istemez ve alamaz.

## Nasıl çalışır

<p align="center"><img src="docs/img/mimari.svg" alt="Mimari"></p>

Sunucu bilgisayarında yerel çalışır (stdio). Claude bir araç çağırır, sunucu ilgili herkese açık sayfayı okur, ayrıştırır ve düzenli bir sonuç döner.

## Kurulum

Python 3.10+ gerekir.

```bash
git clone https://github.com/haliksuveyt/iu-mcp.git
cd iu-mcp
python -m venv .venv
.venv/Scripts/pip install -e .      # Windows; macOS/Linux: .venv/bin/pip install -e .
```

## Claude'a bağlama

**Claude Code** (bu klasörden proje kapsamında; `.mcp.json` hazır) ya da genel:

```bash
claude mcp add iu-mcp -- /tam/yol/iu-mcp/.venv/Scripts/python.exe -m iu_mcp.server
```

**Claude Desktop**: `claude_desktop_config.json` dosyasına ekle (Ayarlar → Geliştirici → Yapılandırmayı düzenle), sonra uygulamayı yeniden başlat:

```json
{
  "mcpServers": {
    "iu-mcp": {
      "command": "C:\\yol\\iu-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "iu_mcp.server"]
    }
  }
}
```

Windows'ta `python.exe` yolunu tam yaz.

## Örnek sorular

- "Güz finaline kaç gün kaldı, hangi tarihler?"
- "Yarın öğle yemekhanede ne var? Vegan seçenek?"
- "Fakültenin bu haftaki öğrenci duyuruları neler?"
- "CMPE3111 izlencesi: AKTS, haftalık konular, not dağılımı."
- "Bahar döneminde ders ekleme-bırakma son günü ne zaman?"
- "Bilgisayar Mühendisliği 2. sınıf ders programı nerede?"
- "Zorunlu staj kuralları neler: kaç gün, AKTS şartı, hangi formlar?"
- "6, 4 ve 5 AKTS'lik derslerden AA, BB, CC aldım; 90 AKTS'de GNO'm 2,40'tı. Şimdi kaç oldu?"

Gerçek bir oturum kaydı: [docs/ornek-oturum.md](docs/ornek-oturum.md).

## Kurallar ve sınırlar

- Yalnızca herkese açık sayfalar ve o sayfaların kendi kullandığı herkese açık JSON uç noktaları okunur.
- `robots.txt`'e uyulur; sunucunun kendi `User-Agent`'ı vardır; aynı siteye 0,5 saniyede en fazla 1 istek gider.
- Yanıtlar bellekte önbelleğe alınır: takvim ve izlence 24 saat, menü 6 saat, fakülte sayfaları 1 saat, duyurular 15 dakika.
- Site kapalıysa araç tahmin yürütmek yerine açık bir hata mesajı döner.
- **Takvim** yalnızca 2026-2027 önlisans/lisans içindir (Tıp, Diş, Hukuk, Eczacılık, AUZEF, Konservatuvar hariç). PDF metin olarak okunur; etiketinden kopuk tarih satırları tahmin edilmeden atlanır. Ara sınav tarihlerini üniversite değil birimler belirler, takvimde yalnız ilan son günü vardır. Yeni yıl PDF'i çıkınca `IU_MCP_TAKVIM_PDF` ile değiştirilebilir.
- **Ders programı** tabloları fakültenin kendi paylaşım bağlantılarıdır; araç bağlantıları ve notları getirir, tablo içeriğini okumaz. Şu an BBTF sayfa düzenini tanır.
- **Duyurular** varsayılan olarak BBTF'den gelir; `fakulte` ile iktisat, edebiyat, hukuk, fen, işletme, siyasal, iletişim, mimarlık da seçilir. Hepsi aynı CMS'i kullanır; yeni fakülte eklemek `FACULTIES` içinde tek satırdır.
- **GNO**: varsayılan ölçek 4'lük yaygın tablodur (AA 4,0 … FF 0). Yönetmeliğindeki katsayılar farklıysa `olcek` ile ver. Resmî ortalama her zaman OBS'dedir.
- Yemekhane menüsü SKS'nin yayımladığıdır; hafta sonu ve tatilde sık sık boştur. Besin değeri yok.
- Site tasarımı değişirse bir ayrıştırıcı bozulabilir; testler bunu yakalar.

## Geliştirme

```bash
.venv/Scripts/pip install -e ".[dev]"
.venv/Scripts/python -m pytest                    # kayıtlı yanıtlar + canlı duman testleri
IU_MCP_OFFLINE=1 .venv/Scripts/python -m pytest   # yalnız çevrimdışı
```

Ayrıştırıcılar, kaydedilmiş gerçek yanıtlar (`tests/fixtures/`) üzerinde saf fonksiyonlardır. Ayrı bir test sunucuyu stdio üzerinden resmî MCP istemcisiyle başlatıp araç çağırır. Resmî Python MCP SDK (`mcp`) ile yazıldı; PDF ve HTML ayrıştırma için Python kütüphaneleri çok uygun olduğu için TypeScript yerine seçildi.

## Yol haritası

- Diğer fakültelerin ders programı sayfa düzenleri
- Yeni yıl takviminde otomatik PDF bulma
- Kütüphane çalışma saatleri ve duyuruları
- Burs ve Erasmus başvuru dönemleri için özet

## Yazar

Abdullah Halik Suveyt, Bilgisayar Mühendisliği, İstanbul Üniversitesi.

## Lisans

[MIT](LICENSE). Veriler ilgili yayıncılara (İstanbul Üniversitesi birimleri) aittir; bu proje yalnızca herkese açık bilgiyi çekip düzenler.