pi-finance-tr

Türk finans verilerini pi için MCP araçları olarak sunan paket.

⚠️ Önemli Uyarı

Bu paket yatırım tavsiyesi değildir ve SPK lisansı yoktur. Sunulan veriler yalnızca bilgilendirme amaçlıdır. Finansal kararlarınızı lisanslı yatırım danışmanlarınıza danışarak alınız. Veri gecikmeli veya hatalı olabilir; her türlü sorumluluk kullanıcıya aittir.

Niçin pi-finance-tr?

Türkçe pi kullanıcısı için sade, terminal-dostu günlük finans araçları sunar: TCMB döviz kurları, kripto fiyatları, kira artış hesabı, kredi taksiti gibi pratik ihtiyaçlar. borsa-mcp gibi profesyonel teknik analiz odaklı bağımsız MCP sunucularına alternatif değildir; pi ekosistemine native entegre olur ve tek komutla kurulur.

Araçlar

Döviz (kur modülü — tam)

| Araç | Açıklama | |------|----------| | finance_tr_doviz_kur | TCMB resmi döviz kuru (güncel veya geçmiş tarih) |

Kripto (v0.1.0 — tam)

| Araç | Açıklama | |------|----------| | finance_tr_kripto_fiyat | CoinGecko üzerinden kripto fiyatları (TRY + USD, 24s değişim) |

Borsa (v0.2.0'da)

| Araç | Açıklama | |------|----------| | finance_tr_borsa_hisse | BIST hisse senedi fiyatı |

Emtia (v0.3.0'da)

| Araç | Açıklama | |------|----------| | finance_tr_emtia_fiyat | Altın, gümüş vb. emtia fiyatları |

KAP (v0.3.0'da)

| Araç | Açıklama | |------|----------| | finance_tr_kap_bildirim | KAP bildirimleri ve özel durum açıklamaları |

Gereksinimler

• pi
• Node.js >= 18

Kurulum

pi install npm:pi-finance-tr

Yerel kaynak koddan kurulum:

pi install /path/to/pi-finance-tr

Yapılandırma

examples.env dosyasını başlangıç noktası olarak kullanabilirsiniz.

Ortam Değişkenleri

| Değişken | Açıklama | Varsayılan | |----------|----------|------------| | FINANCE_TR_ENABLED_MODULES | Açık modüller (virgülle ayrılmış) | tümü | | FINANCE_TR_EVDS_KEY | TCMB EVDS API anahtarı (borsa/emtia için) | — | | FINANCE_TR_CACHE_TTL_OVERRIDE | Önbellek süresi (saniye) | 3600 | | FINANCE_TR_USER_AGENT | HTTP User-Agent başlığı | pi-finance-tr/0.1.0 | | FINANCE_TR_TIMEOUT_MS | HTTP istek zaman aşımı (ms) | 15000 |

Örnek

# Yalnızca kur ve kripto modüllerini aç
export FINANCE_TR_ENABLED_MODULES=kur,kripto

# Önbelleği 30 dakikaya düşür
export FINANCE_TR_CACHE_TTL_OVERRIDE=1800

Modül eşleşmesi

| Modül | Araç(lar) | |-------|-----------| | kur | finance_tr_doviz_kur | | kripto | finance_tr_kripto_fiyat | | borsa | finance_tr_borsa_hisse | | emtia | finance_tr_emtia_fiyat | | kap | finance_tr_kap_bildirim |

Kullanım Örnekleri

Döviz kuru sorgulama

• "Dolar bugün kaç TL?"
• "Euro alış ve satış kurları nedir?"
• "Geçen ay 15'inde pound kaçtı?"
• "2025-11-03 tarihinde USD satış kuru ne idi?"
• "Japon yeni kuru bugün TCMB'ye göre kaç?"

Kripto fiyat sorgulama

• "Bitcoin kaç TL?"
• "ETH son 24 saatte ne kadar değişti?"
• "SOL fiyatı dolar ve TL cinsinden nedir?"

Araç Parametreleri

finance_tr_doviz_kur

| Parametre | Tip | Zorunlu | Açıklama | |-----------|-----|---------|----------| | currency | string | evet | Döviz kodu (USD, EUR, GBP, JPY, CHF vb.) | | date | string | hayır | Tarih (YYYY-MM-DD; belirtilmezse bugünkü kur) |

Not: TCMB tatil ve hafta sonlarında bülten yayımlamaz. Bu günlere ait kur sorgusu Türkçe hata mesajı döner.

finance_tr_kripto_fiyat

| Parametre | Tip | Zorunlu | Açıklama | |-----------|-----|---------|----------| | coin | string | evet | Kripto para kodu (BTC, ETH, SOL vb.) veya CoinGecko ID | | currencies | string[] | hayır | Karşılaştırma para birimleri (varsayılan: ["try", "usd"]) |

Roadmap

| Versiyon | İçerik | |----------|--------| | v0.1.0 (mevcut) | Kripto modülü — CoinGecko, TRY+USD, 24s değişim | | v0.2.0 | Borsa modülü — BigPara + Investing fallback | | v0.3.0 | KAP scraping + altın/gümüş emtia | | v1.0.0 | Kişisel finans hesaplayıcıları (kira artışı, kredi taksit, BES) |

Sorun Giderme

Modül çalışmıyor

FINANCE_TR_ENABLED_MODULES değişkenini kontrol edin. Değer belirtilmezse tüm modüller açık olur.

Zaman aşımı hatası

export FINANCE_TR_TIMEOUT_MS=30000

TCMB'den veri gelmiyor

• İş günü olduğundan ve TCMB'nin bülteni yayımladığından emin olun (genellikle 15:30'dan sonra).
• Tarih formatının YYYY-MM-DD olduğunu kontrol edin.
• Döviz kodunun TCMB'nin kabul ettiği kodlardan biri olduğunu doğrulayın (USD, EUR, GBP, JPY, CHF vb.).

Katkı

Issue açmak için GitHub Issues sayfasını kullanın. Lütfen şunları belirtin:

• Hangi modül/araçla ilgili
• Beklenen ve gerçekleşen davranış
• Node.js versiyonu

PR akışı

1. Repo'yu fork edin
2. git checkout -b feat/açıklayıcı-isim
3. Değişikliklerinizi yapın
4. npm run typecheck && npm run lint && npm test geçtiğinden emin olun
5. PR açın — ADIM'lara karşılık gelen commit'ler tercih edilir

Detaylar için CONTRIBUTING.md dosyasına bakın.

Lisans

MIT