# Sokrates — Spec-Elicitation MCP Sunucusu

Kullanıcının belirsiz bir hedefini Sokratik sorularla netleştirip
yapılandırılmış bir teknik spec'e dönüştürmeye yardımcı olan bir MCP
araç seti.

## Tasarım ilkesi: sıfır API kullanımı

Bu sunucu **hiçbir LLM API'sine bağlanmaz, kendi API key'i yoktur.**
Reasoning'in tamamı (hangi soruyu soracağına karar vermek, ne zaman
yeterli bilgi toplandığını değerlendirmek) bu araçları **çağıran model**
(Claude Desktop/Code, kullanıcının kendi aboneliği üzerinden) tarafından
yapılır. Sokrates sadece:

- Oturum durumu tutar (hangi kategoriler cevaplandı) — düz Python state.
- Elle küratörlüğü yapılan bir bilgi tabanında anahtar kelime araması yapar.
- Toplanan cevapları bir markdown şablonuyla birleştirir.

Hiçbiri dış bir servise ağ isteği atmıyor.

## Dil tasarımı

Tool tanımları, `instructions` ve veri dosyaları (`checklist.yaml`,
`bilgi_tabani.yaml`) kasıtlı olarak **İngilizce** — bunlar doğrudan
kullanıcıya gösterilmeyen, LLM'in okuduğu bir "protokol katmanı".
Sokrates'in `instructions`'ı çağıran modele açıkça şunu söylüyor:
kullanıcıyla HER ZAMAN kullanıcının kendi dilinde konuş (Türkçe yazan
Türkçe, İngilizce yazan İngilizce soru alır — bu otomatik). `generate_spec`
çıktısı ise varsayılan olarak İngilizce üretilir (taşınabilirlik için —
başka bir kodlama LLM'ine verilecek bir prompt olduğundan), kullanıcı
açıkça kendi dilini isterse bu değişir.

## Bağlanma

### Hosted (önerilen — kurulum gerektirmez)

Sokrates [FastMCP Cloud](https://fastmcp.cloud) üzerinde yayında:

```
https://sokrates.fastmcp.app/mcp
```

Claude Desktop/Code'un MCP ayarlarına (veya `.mcp.json`'a) bu URL'i uzak
(remote/HTTP) bir sunucu olarak eklemeniz yeterli — Python kurulumu,
`pip install`, dosya yolu düzenlemesi gerekmez. FastMCP Cloud, `main`
branch'e her push'ta otomatik olarak yeniden deploy eder.

**Claude.ai (web) üzerinden bağlanma:**

1. [claude.ai](https://claude.ai) → sohbet kutusunun yanındaki **+** menüsü
   → **Connectors** → **Add connector**.
2. İsim olarak `sokrates`, URL olarak `https://sokrates.fastmcp.app/mcp`
   girip kaydedin.
3. Aynı **+** menüsünden **Connectors** listesinde `sokrates`'i açık
   konuma getirin.
4. Yeni bir sohbette belirsiz bir hedefinizi anlatın (ör. "bir gym app
   yapmak istiyorum") — Claude otomatik olarak `start_session`'ı çağırır.

Kurulum, config dosyası düzenleme veya Python gerekmez.

### Yerel (geliştirme/offline kullanım için)

```bash
pip install -r requirements.txt
```

Ardından `setup.bat`'ı çalıştırın — bu, `kurulum_yardimci.py` aracılığıyla
Claude Desktop'ın `claude_desktop_config.json` dosyasına Sokrates'i
güvenli şekilde ekler (mevcut başka MCP sunucularını bozmadan). Claude
Code kullanıyorsanız bu klasördeki `.mcp.json`'u projenize kopyalayın.

Kaydedip Claude'u yeniden başlattığınızda `start_session`,
`search_knowledge_base`, `submit_answer`, `generate_spec` araçları
otomatik olarak görünür.

## Kullanım akışı

1. Kullanıcı belirsiz bir hedef anlatır ("bir RAG chatbot istiyorum" gibi).
2. Model `start_session(goal)` çağırır, sabit bir checklist alır.
3. Model, checklist'teki HER kategori için kendi Sokratik sorularını
   kullanıcıya sorar, cevabı `submit_answer` ile kaydeder.
4. Belirsiz bir teknik terim/araç seçimi gerektiğinde
   `search_knowledge_base` ile güncel seçenekleri sorgular.
5. Tüm kategoriler kapanınca `generate_spec` ile nihai spec üretilir.

## Bakım

`data/bilgi_tabani.yaml` **elle** küratörlüğü yapılan bir dosyadır,
otomatik güncellenmez. Yeni bir araç/framework kategorisi eklemek ya
da mevcut bir girdiyi güncellemek için doğrudan bu dosyayı düzenleyin
(`last_updated` alanını da güncelleyin) — **İngilizce yazın**, dil
tasarımı yukarıda açıklandı. `data/checklist.yaml` elicitation
kategorilerini tanımlar — yeni bir proje türü için ek kategori
gerekiyorsa buraya eklenir.

## v1 kapsam sınırları (bilinçli ertelendi)

- Bilgi tabanı araması basit anahtar kelime eşleşmesi — embedding tabanlı
  semantik arama yok.
- Oturumlar bellek-içi (`_oturumlar` dict) — sunucu süreci yeniden
  başlarsa (ör. yeni bir deploy) açık oturumlar kaybolur, kalıcı
  depolama yok.