evds-mcp-server

Türkiye ekonomik verisini (TCMB EVDS) bir LLM'in güvenle çağırabileceği, curated araçlar olarak sunan bir MCP 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:

{
  "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.

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):

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:

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):

{
  "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)

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

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ı 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). 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)