# YEK MCP — Yazma Eserlerde Yapay Zekâ Destekli Katalog Araması

> **Sorumlu kullanım:** Bu araç `portal.yek.gov.tr` adresine senin kendi yetkili
> hesabınla erişir. Kurumun kullanım şartları otomatik erişimi sınırlayabilir; bu yüzden
> aracı yalnızca **düşük hacimde, kişisel/akademik araştırma** amacıyla kullan. Görsel ya
> da varak (sayfa) indirme **bilinçli olarak yoktur**.

## Bu araç ne işe yarar?

Türkiye Yazma Eserler Kurumu'nun kataloğunda **674 binin üzerinde** yazma ve nadir eser
var. Bu devasa hazinede aradığını bulmak çoğu zaman şuna bağlı: doğru anahtar kelimeyi,
doğru imlâyla, doğru alana yazabilmek. Bir mecmuanın adını tam bilmiyorsan, yalnızca
"şu özelliklerde bir eser arıyorum" diyebiliyorsan, klasik katalog arama kutusu seni
çoğu zaman yarı yolda bırakır.

**YEK MCP tam burada devreye girer.** Bu proje, YEK kataloğunu Claude gibi bir yapay zekâ
asistanına **konuşabileceğin bir araç** hâline getirir. Artık katalogla tek tek anahtar
kelime denemek yerine, asistanla **doğal dilde sohbet ederek beyin fırtınası** yaparsın:

- *"Osmanlı Türkçesi, 100 varaktan kısa bir şiir mecmuası arıyorum"* dersin,
- asistan senin yerine kataloğa gider, kayıtları okur, **insan ölçütlerinle eşleştirir**,
- sana uygun adayları gerekçeleriyle birlikte sıralar,
- istediğinde **doğrudan açılabilir katalog bağlantısını** verir.

Yani bu, bir "arama kutusu" değil; **674 bin eser üzerinde seninle birlikte düşünen bir
araştırma asistanı**dır.

## Çalışma mantığı — neden böyle kurguladık?

Önemli olan kodun iç iskeleti değil, **yaklaşımdır**. Klasik bir katalog araması
"kelimeyi yaz, eşleşeni getir" mantığıyla çalışır; insanın gerçek araştırma soruları ise
çok daha bulanıktır. Araştırmacı "tam olarak şu kelime" demez; *"şuna benzer, şu dönemden,
şu türde, şu hacimde bir şey"* der.

Bu araç, o boşluğu kapatmak için iki şeyi birleştirir:

1. **Kataloğa erişen sade bir köprü.** Asistan, senin oturumunla katalog sayfalarını çeker
   ve içlerindeki kayıtları (eser adı, kütüphane, koleksiyon, varak sayısı, dil, istinsah
   tarihi, içerik notu, dijital görüntü var mı…) düzenli, okunabilir bir veriye dönüştürür.
2. **Üstünde düşünen yapay zekâ.** Asistan bu düzenli veriyi okur, senin koyduğun ölçütlerle
   karşılaştırır ve **katalog kayıtlarındaki farklı yazım ve eksik alanları da hesaba katar.**
   Örneğin YEK, dil alanına çoğu zaman "Osmanlı Türkçesi" değil sadece "Türkçe" yazar; asistan
   bunu göz önünde bulundurur ve bir eserin Osmanlı Türkçesi olup olmadığını **Arap harfli yazı
   türü + istinsah tarihi + içerik** üzerinden değerlendirir.

Bu sayede araştırmacı, teknik ayrıntılarla uğraşmadan, kendi sorusunu kendi diliyle
sorabilir.

## Gerçek bir örnek: bir şiir mecmuası arayışı

Aşağıdaki, araçla yapılmış **gerçek bir beyin fırtınası araması**. Hiçbir kayıt adını önceden
bilmeden, yalnızca insan ölçütleriyle başlandı:

> **Araştırmacı:**
> Arama konusu:
> — Yazma eser olacak
> — Osmanlı Türkçesi olacak
> — Bir şiir mecmuası veyahut mecmua
> İyi olur: en fazla 100 varak vb.
> Bu kıstaslarla bir eser çıkar.

> **Asistan (kataloğu tarayıp kayıtları okuduktan sonra):**
>
> **Kıstaslara uyan en güçlü aday — Mecmûa-i Eş'âr (öneri)**
> - **Kayıt no:** `611545`
> - **Kütüphane:** Milli Kütüphane
> - **Koleksiyon no:** `06 Mil Yz A 2519`
> - **Materyal:** Yazma eser
> - **Hacim:** 49 varak
> - **Dil:** Türkçe · **Alfabe:** Arap alfabesi, harekeli nesih
> - **İstinsah:** 19. yüzyıl
> - **İçerik:** Bâkî, Muhibbî, Hayâlî, Fevrî, Rahmî, Şevkî ve başka şairlerin şiirleri
> - **Dijital görüntü:** Var
>
> *Katalog notunda açıkça "Eser, şiir mecmuasıdır" deniyor. Türkçe, Arap harfli ve 19.
> yüzyıla tarihlendiği için Osmanlı Türkçesi ölçütünü en güçlü biçimde karşılayan kayıt bu.*
>
> *Not: YEK dil alanında "Osmanlı Türkçesi" yerine genellikle yalnızca "Türkçe" yazar.
> Osmanlı Türkçesi değerlendirmesini Arap harfli yazı, istinsah tarihi ve katalog içeriğine
> dayanarak yaptım.*

Dikkat: araştırmacı tek bir kayıt numarası bilmiyordu; yalnızca **"şiir mecmuası, Osmanlı
Türkçesi, kısa hacimli"** dedi. Geri kalanını araç ve asistan birlikte yaptı.

### Doğrudan bağlantı isteyebilirsin

Bir kaydı incelemek istediğinde asistandan **"bunun linkini ver"** demen yeterli; sana o
eserin doğrudan açılabilen katalog sayfasını verir. Örneğin yukarıdaki öneri için:

`https://portal.yek.gov.tr/works/detail/611545`

Böylece beyin fırtınasından çıkan sonucu tek tıkla kurumun kendi sayfasında açıp
doğrulayabilirsin.

## Asistana kazandırdığı yetenekler (araçlar)

Asistan, sohbet sırasında perde arkasında şu dört aracı kullanır:

- **`search_yek_works`** — katalogda anahtar kelime / alan bazlı arama yapar.
- **`get_yek_work_details`** — bir eserin tüm katalog künyesini getirir (yukarıdaki
  Mecmûa örneğindeki gibi).
- **`list_yek_libraries`** — katalogdaki kütüphaneleri listeler.
- **`list_yek_collections`** — koleksiyonları listeler.

Sen bu araçların adlarını hiç bilmek zorunda değilsin; sadece ne aradığını anlatırsın,
asistan doğru aracı kendi seçer.

---

## Kurulum ve kullanım (teknik bölüm)

> Bu bölüm aracı kendi bilgisayarına kuracaklar içindir. Adımları sırasıyla izlemen yeterli.

### 1. Kurulum
```bash
pip install -e .
playwright install chromium
Copy-Item .env.example .env   # PowerShell; gerekirse içini düzenle
```

### 2. Bir kerelik giriş (oturum açma)
Katalog, içeriğine erişmek için giriş ister. Bunu **bir kez** yaparsın:
```bash
python -m yek_mcp.login
```
Açılan tarayıcıda kendi hesabınla giriş yap (gerekirse e-Devlet/SMS), sonra terminale dönüp
**ENTER**'a bas. Oturum bilgin yalnızca **kendi bilgisayarında** `storage_state.json`
dosyasına kaydedilir ve sonraki aramalarda yeniden kullanılır. Oturumun zamanla sona ererse
bu komutu tekrar çalıştırman yeterlidir.

### 3. Çalıştırma
```bash
yek-mcp           # yerel (stdio) MCP server olarak başlar
```

### 4. Claude Desktop / Claude Code'a ekleme
Aşağıdaki ayarı MCP istemcine eklersen asistan bu araçları otomatik görür:
```json
{
  "mcpServers": {
    "yek": {
      "command": "yek-mcp",
      "cwd": "C:/path/to/yek-mcp"
    }
  }
}
```

## Nasıl çalışır (mimari özet)

Detaylı tasarım gerekçeleri için: [`ARCHITECTURE.md`](ARCHITECTURE.md). Kısaca:

- Katalog sayfaları sunucu tarafında HTML olarak üretilir; araç bu sayfaları çeker ve
  **selectolax** ile okunur veriye dönüştürür. Sonuçlar **Pydantic** modellerine yerleşir.
- Varsayılan istemci hafif ve hızlı **httpx**'tir. **Playwright/Chromium** yalnızca bir
  kerelik girişte (ve gerekirse `YEK_ADAPTER=playwright` ile tam-render yedeğinde) devreye
  girer; her iki yol da aynı okuyucuları paylaşır.
- Kimlik doğrulama, senin tarayıcı oturumundan alınan bir oturum bilgisiyle yapılır. Bu bilgi
  **makineden dışarı çıkmaz**, log'a/çıktıya yazılmaz ve depoya gönderilmez.
- Oturum sona erdiğinde araç sessizce boş sonuç dönmez; **net bir hata** verir ve seni
  yeniden girişe yönlendirir. Geçici ağ ve hız-limiti durumlarında ölçülü biçimde yeniden
  dener (varsayılan: en çok ~1 istek/saniye).

## Bilinçli sınırlar

- **Görsel/varak indirme yoktur** (kota ve kullanım şartları hassasiyeti). Araç yalnızca
  katalog künyesiyle ilgilenir.
- Aramada `library`/`collection` ölçütleri kabul edilir ama doğrudan filtrelemeye değil,
  asistanın sonuçları kütüphane/koleksiyon bilgisine göre değerlendirmesine yarar.
- Katalogdaki kütüphane/koleksiyon sayıları, kurumun güncel içeriğine bağlı olarak değişebilir;
  sabit bir liste garanti edilmez.