[English](README_EN.md)

# Kandilli Deprem MCP Server

Kandilli Rasathanesi ve Deprem Araştırma Enstitüsü'nün (koeri.boun.edu.tr) canlı
son-depremler listesini çekip [MCP (Model Context Protocol)](https://modelcontextprotocol.io)
tool'ları olarak sunan minimal bir server. Claude Desktop, Claude Code veya
herhangi bir MCP istemcisiyle (Open WebUI vb.) kullanılabilir.

## Sunulan Tool'lar

| Tool | Açıklama | Parametreler |
|---|---|---|
| `son_depremler` | Kandilli'den en güncel depremleri getirir. | `limit` (varsayılan 20, maks. 500), `min_buyukluk` (varsayılan 0.0) |
| `bolge_ara` | Yer adında (il/ilçe/bölge) verilen kelimeyi içeren depremleri arar. | `anahtar_kelime` (örn. `"BINGOL"`), `limit` (varsayılan 20) |
| `bolge_istatistik` | Belirli bir bölge için son 500 kayıt içindeki basit istatistiksel özet (kayıt sayısı, ortalama büyüklük, en büyük deprem, en son deprem). Bir tahmin **değildir**, sadece mevcut verinin özetidir. | `anahtar_kelime` (örn. `"KUTAHYA"`) |

Veri her çağrıda canlı olarak `koeri.boun.edu.tr` üzerinden çekilir (son 500 kayıt).

> **Telif:** Veri Kandilli Rasathanesi'nin telif hakkı altındadır. Ticari kullanım
> için kaynağa başvurun.

---

## 1) stdio ile Kurulum ve Çalıştırma

`stdio` transport, Claude Desktop ve Claude Code gibi MCP istemcileri tarafından
kullanılan varsayılan modudur; sunucuyu istemci kendisi başlatıp süreç (process)
üzerinden konuşur.

### Kurulum

```bash
git clone https://github.com/<kullanici-adi>/mcp-kandilli-deprem.git
cd mcp-kandilli-deprem
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### Manuel Çalıştırma

```bash
python3 server.py
```

(`TRANSPORT` ortam değişkeni verilmezse varsayılan olarak `stdio` kullanılır.)

### Claude Desktop / Claude Code Tool Direktifi

MCP istemcinizin config dosyasına (Claude Desktop için `claude_desktop_config.json`)
aşağıdaki gibi ekleyin:

```json
{
  "mcpServers": {
    "kandilli-deprem": {
      "command": "python3",
      "args": ["/tam/yol/mcp-kandilli-deprem/server.py"]
    }
  }
}
```

Sanal ortam (venv) kullanıyorsanız `command` alanına venv içindeki python'un tam
yolunu verin, örn. `/tam/yol/mcp-kandilli-deprem/.venv/bin/python3`.

Config kaydedildikten sonra istemciyi yeniden başlatın; `son_depremler`,
`bolge_ara` ve `bolge_istatistik` tool'ları otomatik olarak listelenecektir.

---

## 2) Docker ile Kurulum ve Çalıştırma

Docker modu, `streamable-http` transport üzerinden çalışır ve sunucuyu ağ
üzerinden erişilebilir bir servis olarak ayağa kaldırır (ör. Open WebUI, uzak
sunucu, birden çok istemci).

### docker compose ile (önerilen)

```bash
docker compose up -d --build
```

Bu komut `compose.yml` içindeki ayarlarla (`8811` portu, healthcheck, otomatik
yeniden başlatma) servisi arka planda ayağa kaldırır. Loglara bakmak için:

```bash
docker compose logs -f
```

Durdurmak için:

```bash
docker compose down
```

### Manuel Docker ile

```bash
docker build -t kandilli-deprem-mcp .
docker run -d \
  --name kandilli-deprem-mcp \
  -p 8811:8811 \
  -e TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8811 \
  kandilli-deprem-mcp
```

### Ortam Değişkenleri

| Değişken | Varsayılan | Açıklama |
|---|---|---|
| `TRANSPORT` | `stdio` | `stdio` veya `streamable-http` |
| `MCP_HOST` | `0.0.0.0` | `streamable-http` için bind adresi |
| `MCP_PORT` | `8811` | `streamable-http` için port |

### Tool Direktifi (Streamable HTTP)

Docker'da çalışan sunucu, MCP endpoint'ini `http://<host>:8811/mcp` üzerinden
sunar. Open WebUI veya Streamable HTTP destekleyen bir MCP istemcisinde
bağlantıyı şu şekilde tanımlayın:

```json
{
  "mcpServers": {
    "kandilli-deprem": {
      "url": "http://localhost:8811/mcp",
      "transport": "streamable-http"
    }
  }
}
```

Sunucunun ayakta olduğunu doğrulamak için:

```bash
docker compose ps
```

`healthy` durumu, servisin `8811` portunda dinlediğini gösterir.

---

## Gereksinimler

- Python 3.12+
- [mcp](https://pypi.org/project/mcp/) SDK (bkz. [requirements.txt](requirements.txt))

## Lisans

Bu projenin kaynak kodu [MIT Lisansı](LICENSE) ile lisanslanmıştır. Deprem verisi
ise Kandilli Rasathanesi'ne aittir ve ilgili kullanım koşullarına tabidir (kod
lisansından bağımsızdır).