# evds-mcp-server

Türkiye ekonomik verisini (**TCMB EVDS**) bir LLM'in güvenle çağırabileceği,
**curated** araçlar olarak sunan bir [MCP](https://modelcontextprotocol.io) server'ı.

FRED/ECB/Eurostat için MCP server'lar var; Türkiye (EVDS) için yoktu. Bu server o
boşluğu dolduruyor: Claude (Desktop/Code) "2023'te yıllık enflasyon neydi?",
"dolar son 1 yılda ne oldu?" gibi soruları **serbest sorgu yazmadan**, önceden
doğrulanmış araçlarla EVDS'den **canlı** çekip **kaynağıyla** yanıtlar.

> **Tasarım ilkesi:** LLM serbest seri seçmez. Her araç doğru EVDS seri koduna ve
> birime kilitlidir. Bu, yanlış seri / nominal-reel karışması / hallucination'ı
> baştan engeller. Her yanıt **kaynak + dönem + birim + nominal/reel** taşır.

- **Stateless:** veritabanı yok, cache yok. Her çağrı EVDS'ye canlı gider.
- **Stdio** transport, tek paket, TypeScript.
- Veri kaynağı: **yalnızca EVDS (TCMB).**

---

## Araçlar (6 curated tool)

| Araç | Ne yapar | Önemli parametreler |
|---|---|---|
| `get_inflation` | TÜFE / Yİ-ÜFE / çekirdek (C) enflasyon | `measure`, `change: yoy\|level`, `period` |
| `get_fx` | TCMB döviz alış/satış kuru (günlük) | `pair`, `side: alis\|satis`, `period` |
| `get_policy_rate` | Politika faizi proxy'si (AOFM) | `frequency: daily\|monthly`, `period` |
| `get_trade_balance` | Dış ticaret: ihracat / ithalat / denge | `flow: export\|import\|balance`, `period` |
| `get_growth` | GSYİH büyüme | `basis: yoy\|level`, `period` |
| `compare_indicators` | İki göstergeyi aynı dönemde (nominal/reel) | `a`, `b`, `transform: real\|yoy`, `period` |

`period` her araçta `{ start, end }` ve tarihler `YYYY`, `YYYY-MM` veya
`YYYY-MM-DD` olabilir.

### Ortak çıktı şeması

Her araç (compare hariç) aynı zarfı döndürür:

```jsonc
{
  "series": "TP.DK.USD.S.YTL",        // EVDS seri kodu
  "label": "ABD Doları (Döviz Satış)",
  "unit": "TL (1 USD karşılığı)",
  "basis": "nominal",                  // nominal | reel | düzey | yıllık % değişim ...
  "observations": [
    { "date": "25-06-2026", "value": 46.4935 },
    { "date": "26-06-2026", "value": 46.5139 }
  ],
  "source": "TCMB EVDS",
  "fetchedAt": "2026-06-26T11:58:05.746Z",
  "note": "…"                          // varsa metodoloji/uyarı
}
```

> Yukarıdaki, EVDS'den dönen **gerçek** bir örnektir (USD satış, 25–26 Haz 2026).

---

## Kurulum

Gereksinim: **Node.js ≥ 20**.

```bash
git clone <repo-url> evds-mcp-server
cd evds-mcp-server
npm install
npm run build        # dist/index.js üretir
```

### EVDS API anahtarı

1. <https://evds3.tcmb.gov.tr> adresine kayıt olun / giriş yapın.
2. **Profil → API Anahtarı**'ndan anahtarınızı alın (ücretsiz).
3. `.env` dosyası oluşturun (`.env.example`'ı kopyalayın):

```bash
cp .env.example .env
# .env içine: EVDS_API_KEY=sizin_anahtarınız
```

> Anahtar 2024 değişikliğiyle artık **HTTP header** olarak gönderilir (URL'de
> değil). Bu server bunu sizin için yapar. `.env` repoya **girmez**
> (`.gitignore`'da).

### Seri kodu doğrulama / sağlık kontrolü

13 seri kodunun tamamı canlı evds3 katalogundan + gerçek bir veri çağrısıyla
doğrulanmıştır (TÜFE/çekirdek 2025=100 yeni seri, dış ticaret "Toplam", GSYİH
toplam dahil). Anahtarınızla bir sağlık kontrolü çalıştırmak için:

```bash
npm run verify
```

Bu komut her seriyi canlı EVDS'den teyit eder, resmî EVDS etiketini ve son
gözlemi yazar, ardından gerçek bir `get_fx USD` örneği basar. TÜİK ileride
yeniden baz yılı değiştirirse (örn. 2003=100 → 2025=100 geçişinde olduğu gibi)
bu komut hangi serinin durduğunu gösterir; doğru kodu `src/series.ts` içine
yazabilirsiniz.

---

## Claude'a ekleme

### Claude Desktop

`claude_desktop_config.json` dosyasına ekleyin
(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```jsonc
{
  "mcpServers": {
    "evds": {
      "command": "node",
      "args": ["/MUTLAK/YOL/evds-mcp-server/dist/index.js"],
      "env": { "EVDS_API_KEY": "sizin_anahtarınız" }
    }
  }
}
```

Claude Desktop'ı yeniden başlatın. `/MUTLAK/YOL`'u kendi yolunuzla değiştirin
(`pwd` ile bulabilirsiniz).

### Claude Code (CLI)

```bash
claude mcp add evds --env EVDS_API_KEY=sizin_anahtarınız -- node /MUTLAK/YOL/evds-mcp-server/dist/index.js
```

### Manuel stdio çalıştırma

```bash
EVDS_API_KEY=xxx node dist/index.js     # MCP istemcisi stdin/stdout ile konuşur
node dist/index.js --help               # yardım
```

---

## Doğruluk kuralları

- Her yanıt **kaynak + dönem + birim + nominal/reel** taşır. İstisna yok.
- EVDS boş/null dönerse **uydurulmaz** — `note` alanında "veri yok" denir.
- Birim ve nominal/reel ayrımı asla karıştırılmaz (TL ≠ USD, endeks ≠ % değişim).
- EVDS yanıtı zod ile doğrulanır; beklenmeyen şekil → açıklayıcı hata.
- Anahtar eksik/geçersizse araç çağrısı **net Türkçe hata** döndürür (server çökmez).

---

## Veri kaynağı, lisans, etik

- **Veri: TCMB EVDS.** Kişisel kullanım ve araştırma amaçlıdır; [EVDS kullanım
  koşulları](https://evds3.tcmb.gov.tr) geçerlidir. Ticari yeniden-dağıtım iddiası
  yoktur.
- Her araç çıktısında `source: "TCMB EVDS"` bulunur — kaynak gösterimi hem etik
  hem zorunludur.
- API anahtarı **size aittir**; repoya girmez.
- Kod lisansı: **MIT** (bkz. [LICENSE](LICENSE)). Lisans yalnızca bu server'ın
  kaynak kodunu kapsar; veriyi değil.

---

## Sonraki fazlar (bu sürümün kapsamı dışında)

- Web arayüzü.
- Ek kaynaklar: World Bank, TÜİK doğrudan.
- Daha fazla curated gösterge (işsizlik, cari denge, konut fiyat endeksi…).

---

## Proje yapısı

```
src/
  index.ts          # MCP server (stdio), 6 aracı kaydeder
  evds.ts           # EVDS adapter: fetch + header auth, zod, tarih/frekans, katalog
  series.ts         # curated seri kayıt defteri (kodlar burada kilitli)
  constants.ts      # frekans/formül/aggregation kodları
  types.ts          # ortak çıktı şeması (zod)
  format.ts         # ortak çıktı montajı + hata biçimleme
  tools/            # 6 aracın implementasyonu
scripts/
  verify.ts         # canlı katalog doğrulama (npm run verify)
```