# tefas-fund-comparator

**MCP (Model Context Protocol)** sunucusu: [TEFAS](https://www.tefas.gov.tr/) fonlarını listeleme, karşılaştırma, getiri/performans analizi ve portföy dağılımı inceleme.

Sunucu adı: **`tefas-fund-comparator`**

## Özellikler

| Tool | Açıklama |
|------|----------|
| `list_funds` | Fon tipi + tarih aralığı + kod/isim filtresi ile fon listesi |
| `get_fund_details` | Fiyat geçmişi, özet metrikler, portföy dağılımı |
| `compare_funds` | Çoklu fon: getiri, volatilite, Sharpe, max drawdown, AUM |
| `get_portfolio_breakdown` | Varlık dağılımı (hisse, repo, eurobond, …) |
| `get_historical_returns` | RB / SB / MB bazlı TEFAS getiri tabloları |
| `analyze_performance` | Risk/getiri istatistikleri (pandas) |

- **stdio** + **Streamable HTTP** transport
- **pytefas**: otomatik chunking + rate-limit retry
- **tefasfon**: RB/SB/MB getiri tabloları
- Çıktı: **markdown tablo** veya **JSON**

## Kurulum

### Gereksinimler

- Python **3.10+**
- İnternet erişimi (TEFAS API)

### pip

```bash
cd TEFAS-MCP
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
# source .venv/bin/activate

pip install -e .
# veya
pip install -r requirements.txt
pip install -e .
```

### uv

```bash
cd TEFAS-MCP
uv venv
uv pip install -e .
```

## Çalıştırma

### stdio (Claude Code / Cline / Cursor — varsayılan)

```bash
python -m tefas_mcp.server
# veya
tefas-fund-comparator
```

### Streamable HTTP

```bash
python -m tefas_mcp.server --transport http --host 127.0.0.1 --port 8000
# Endpoint: http://127.0.0.1:8000/mcp
# Health:   http://127.0.0.1:8000/health
```

### Yardım

```bash
python -m tefas_mcp.server --help
```

## Docker (yerel)

```bash
# Image build + run (port 8000)
docker compose up --build

# veya
docker build -t tefas-fund-comparator .
docker run --rm -p 8000:8000 -e PORT=8000 tefas-fund-comparator
```

Kontrol:

```bash
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/
```

## Render.com (Docker Web Service)

Hazır dosyalar: `Dockerfile`, `render.yaml`, `.dockerignore`.

### A) Blueprint (önerilen)

1. Kodu GitHub’a push edin.
2. [Render Dashboard](https://dashboard.render.com/) → **New** → **Blueprint**.
3. Repo’yu seçin; `render.yaml` otomatik okunur.
4. Deploy sonrası URL örneği: `https://tefas-fund-comparator.onrender.com`
5. MCP endpoint: `https://tefas-fund-comparator.onrender.com/mcp`  
   Health: `https://tefas-fund-comparator.onrender.com/health`

### B) Manuel Web Service

1. **New** → **Web Service** → repo bağla  
2. **Runtime:** Docker  
3. **Dockerfile path:** `./Dockerfile`  
4. **Health Check Path:** `/health`  
5. Env (opsiyonel; Dockerfile varsayılanları yeter):

| Key | Value |
|-----|--------|
| `MCP_TRANSPORT` | `http` |
| `HOST` | `0.0.0.0` |
| `MCP_PATH` | `/mcp` |
| `LOG_LEVEL` | `INFO` |

> `PORT` Render tarafından otomatik enjekte edilir; elle yazmayın.

### Claude / Cline ile Render URL

Claude genelde uzak HTTP MCP’ye doğrudan bağlanmaz; `mcp-remote` kullanın
(`examples/mcp_config.render.json`):

```json
{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-SERVICE.onrender.com/mcp"
      ]
    }
  }
}
```

`YOUR-SERVICE` kısmını kendi Render servis adınızla değiştirin.

### Render notları

- **Free plan** idle sonrası uykuya geçer; ilk istek ~30–60 sn sürebilir.
- TEFAS rate-limit nedeniyle uzun analizler yavaş / timeout olabilir; gerekirse plan yükseltin veya timeout’ları artırın.
- Servis herkese açıksa istek koruması (auth, IP allowlist, Cloudflare) eklemeniz önerilir — bu imajda API anahtarı yoktur.

## MCP istemci yapılandırması

Aşağıda `PYTHON` yolunu kendi venv’inize göre düzenleyin.

### Claude Code / Claude Desktop (`claude_desktop_config.json` veya proje `.mcp.json`)

```json
{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "C:\\Users\\kerem\\Documents\\TEFAS-MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "tefas_mcp.server"],
      "cwd": "C:\\Users\\kerem\\Documents\\TEFAS-MCP"
    }
  }
}
```

macOS/Linux örneği:

```json
{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "/path/to/TEFAS-MCP/.venv/bin/python",
      "args": ["-m", "tefas_mcp.server"],
      "cwd": "/path/to/TEFAS-MCP"
    }
  }
}
```

Global `pip install -e .` yaptıysanız:

```json
{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "tefas-fund-comparator",
      "args": []
    }
  }
}
```

### Cline (VS Code)

Cline → MCP Settings:

```json
{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "python",
      "args": ["-m", "tefas_mcp.server"],
      "cwd": "C:\\Users\\kerem\\Documents\\TEFAS-MCP",
      "disabled": false
    }
  }
}
```

### HTTP + mcp-remote (isteğe bağlı)

Önce sunucuyu HTTP modunda başlatın, sonra:

```json
{
  "mcpServers": {
    "tefas-fund-comparator-http": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}
```

### uvx (paket yayımlanmışsa)

```json
{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "uvx",
      "args": ["tefas-fund-comparator"]
    }
  }
}
```

Yerel dizinden `uv run`:

```json
{
  "mcpServers": {
    "tefas-fund-comparator": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\Users\\kerem\\Documents\\TEFAS-MCP", "python", "-m", "tefas_mcp.server"]
    }
  }
}
```

## Fon tipleri

| Kod | Anlam | tefasfon alias |
|-----|--------|----------------|
| `YAT` | Yatırım fonu | `SEC` |
| `EMK` | Emeklilik | `PEN` |
| `BYF` | Borsa yatırım fonu (ETF) | `ETF` |
| `GYF` | Gayrimenkul | `RE` |
| `GSYF` | Girişim sermayesi | `VC` |

## Örnek tool çağrıları

Agent / istemci üzerinden (anlamsal örnekler):

```text
list_funds(fund_type="YAT", name_contains="ALTIN", limit=20)

get_fund_details(fund_code="AAL", fund_type="YAT")

compare_funds(
  fund_codes=["AAL", "AAK"],
  start_date="2026-01-01",
  end_date="2026-04-01",
  metrics=["return", "volatility", "sharpe", "max_drawdown"]
)

get_portfolio_breakdown(fund_code="AAL")

get_historical_returns(fund_type="YAT", basis="RB", limit=25)

analyze_performance(
  fund_codes=["AAL", "AAK"],
  start_date="2025-04-01",
  end_date="2026-04-01",
  risk_free_annual=0.40
)
```

## Rate limit ve süre

TEFAS yaklaşık **dakikada 6 istek** sınırına yakındır. pytefas uzun aralıkları ~28 günlük parçalara böler:

| Aralık | Kabaca süre |
|--------|-------------|
| 1 ay | ~10 sn |
| 3 ay | ~1 dk |
| 1 yıl | ~3 dk |

Aynı istekler ~60 sn TTL ile bellekte önbelleğe alınır.

## Test

```bash
pip install -e ".[dev]"
pytest -q
```

Ağ gerektiren smoke test (manuel):

```bash
python -c "from tefas_mcp.client import get_service; print(get_service().fetch_info('2026-04-20','2026-04-24',kind='YAT',fund_code='AAL').head())"
```

## Proje yapısı

```
src/tefas_mcp/
  server.py           # FastMCP entrypoint
  client/             # pytefas + tefasfon façade
  tools/              # 6 MCP tools
  analytics/          # Sharpe, vol, max DD
  models/             # enums / validation
  utils/              # dates, formatters, errors
```

## Bağımlılıklar

- [fastmcp](https://github.com/PrefectHQ/fastmcp)
- [pytefas](https://github.com/mirzazad/pytefas)
- [tefasfon](https://pypi.org/project/tefasfon/)
- pandas, pydantic, httpx

## Uyarı

Bu araç yatırım tavsiyesi değildir. TEFAS API’si resmi olarak dokümante edilmemiştir; site değişikliklerinde paket güncellemesi gerekebilir. Metrikler eğitim / karşılaştırma amaçlı basitleştirilmiş istatistiklerdir.

## Lisans

MIT