TEFAS Scraper

TEFAS (Türkiye Elektronik Fon Dağılım Platformu) verilerini çekmek, analiz etmek ve Gemini/CLI üzerinden erişim sağlamak için hazırlanmış bir araç seti.

Özet

MCP sunucusu ve komut satırı arayüzü (CLI) sağlar.
TEFAS'ın açık API uç noktalarından fon analizleri, tarihsel veriler ve karşılaştırmalı raporlar alır.

Özellikler

MCP (FastMCP) araçları: analyze_fund, get_fund_history_info, get_fund_allocation_history, compare_fund_returns, compare_fund_sizes, compare_fund_fees.
CLI modunda doğrudan çağrılabilir: python mcp_server.py --cli <command>.
Alternatif HTTP API (FastAPI) örneği: tefas_scraper_extension/main.py.

Gereksinimler

Python 3.12+ (önerilir)
Python bağımlılıkları: pip install -r requirements.txt

Kurulum

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Hızlı Başlangıç

MCP sunucusu (stdio transport, Gemini ile entegrasyon için):

python mcp_server.py

CLI örnekleri:

# Fon analizi (price range ile)
python mcp_server.py --cli analyze --fund-type YAT --fund-code TTE --price-range 1M --pretty

# Tarihsel bilgi (history-info)
python mcp_server.py --cli history-info --fund-code TTE --start-date 2024-01-01 --end-date 2024-01-31 --pretty

# Portföy dağılımı geçmişi
python mcp_server.py --cli history-allocation --fund-code TTE --start-date 2024-01-01 --end-date 2024-01-31 --pretty

# Getiri karşılaştırması
python mcp_server.py --cli compare-returns --fund-type YAT --periods 0,0,0,1,0,0,0 --pretty

# Büyüklük karşılaştırması (DD.MM.YYYY formatıyla)
python mcp_server.py --cli compare-sizes --start-date 01.01.2024 --end-date 31.01.2024 --pretty

FastAPI (alternatif HTTP) çalıştırma:

uvicorn tefas_scraper_extension.main:app --reload --port 8000

API / MCP Araçları

analyze_fund — parametreler: fund_type (zorunlu), fund_code (zorunlu), start_date (DD.MM.YYYY), end_date (DD.MM.YYYY), price_range (1H,1M,3M,6M,YTD,1Y,3Y,5Y).
get_fund_history_info — parametreler: fund_code, start_date (YYYY-MM-DD), end_date (YYYY-MM-DD), fund_type (opsiyonel).
get_fund_allocation_history — aynı format ve zorunluluklar get_fund_history_info ile uyumlu.
compare_fund_returns — fund_type ve periods (ör. 1,1,1,1,1,1,1).
compare_fund_sizes — tarihler DD.MM.YYYY formatında beklenir.
compare_fund_fees — fund_type parametresi.

Tarih Formatlarına Dikkat

analyze_fund ve bazı karşılaştırma araçları DD.MM.YYYY tarih formatı bekler.
history-* uç noktaları YYYY-MM-DD formatı bekler.
Karışık formatlar geçersiz girişlere veya ValueError hatalarına yol açabilir. Lütfen örnekleri dikkatle takip edin.

Test Etme / CLI Kombinasyonlarını Deneme

Aşağıdaki küçük komut dosyası, CLI komutlarını ve tipik argüman kombinasyonlarını çalıştırıp hata veren kombinasyonları yakalamaya uygundur. Bu, gerçek TEFAS çağrıları gerçekleştireceği için dikkatle ve kısıtlı sıklıkta çalıştırınız.

#!/usr/bin/env bash
set +e
echo "Basit CLI testi başlıyor..."
commands=(
	"python mcp_server.py --cli analyze --fund-type YAT --fund-code TTE --price-range 1M --pretty"
	"python mcp_server.py --cli analyze --fund-code TTE --price-range 1M --pretty"  # eksik fund-type -> parser hatası
	"python mcp_server.py --cli history-info --fund-code TTE --start-date 2024-01-01 --end-date 2024-01-31 --pretty"
	"python mcp_server.py --cli history-info --fund-code TTE --start-date 01.01.2024 --end-date 31.01.2024 --pretty" # yanlış format -> ValueError beklenir
	"python mcp_server.py --cli compare-sizes --start-date 01.01.2024 --end-date 31.01.2024 --pretty"
)

for cmd in "${commands[@]}"; do
	echo "=> $cmd"
	eval $cmd
	rc=$?
	if [ $rc -ne 0 ]; then
		echo "FAILED (exit $rc): $cmd"
	else
		echo "OK: $cmd"
	fi
	echo "---"
done

Not: Bu script hataları yakalayacak, ancak asıl amaç hangi argüman kombinasyonunun servis veya kodda hata çıkardığını gözlemlemektir. Eğer history-info için DD.MM.YYYY formatı gönderirseniz ValueError alırsınız; bu davranış bilinmektedir.

Troubleshooting (Hızlı İpuçları)

Eğer ValueError: Invalid date format görüyorsanız, doğru formatı kullandığınızdan emin olun (endpoint'e bağlı olarak DD.MM.YYYY veya YYYY-MM-DD).
Failed to decode JSON veya aldığınız cevap HTML içeriyorsa (WAF/robot engellemesi), istek frekansı veya User-Agent nedeniyle servis tarafından engellenmiş olabilirsiniz.
Boş yanıt (Empty response from server) dönerse parametreleri kontrol edin.
BrokenPipeError ile karşılaşırsanız, çıktıyı küçük parçalara bölün veya --pretty seçeneğini kaldırın.

Geliştirme ve Katkı

Test eklemek için pytest ve responses/requests-mock kullanılması önerilir.
Önerilen ilk PR'lar: (1) requirements.txt için versiyon sabitleme, (2) test iskeleti (tests/), (3) TLS ve retry iyileştirmesi.

Test Sonuçları (Yerel)

Testler yerel venv içinde çalıştırıldı. Sonuç: 3 passed.

Lisans

Projede bir LICENSE dosyası bulunmaktadır; lisans koşullarına uyun.

Not: Bash scriptler tefasUrlExploration/ klasöründe referans için saklanmaktadır.