# aa-mcp

Artificial Analysis'in bağımsız LLM ölçümlerini (fiyat, hız, benchmark, sağlayıcı)
MCP üzerinden veren sunucu. Python, stdio, **MCP spec 2026-07-28**.

Veri kaynağı: [Artificial Analysis](https://artificialanalysis.ai) — atıf tüm
katmanlarda zorunludur ve her tool yanıtının `meta.attribution` alanında taşınır.

## Neden kendi sunucumuz

Mevcut açık kaynak alternatif ([davidhariri/artificial-analysis-mcp](https://github.com/davidhariri/artificial-analysis-mcp))
emekliye ayrılan `/api/v2/data/llms/models` ucunu kullanıyor (**Sunset: 2026-11-04**,
sonrası `410 Gone`), sayfalama ve cache'i yok, TypeScript SDK'sı da 2026-07-28'i
konuşmuyor. Ayrıntılı karşılaştırma ve karar: [PLAN.md](PLAN.md).

## Kurulum

```bash
uv venv --python 3.14
uv pip install -e .
cp .env.example .env   # AA_API_KEY'i doldur
```

MCP istemcisine ekleme (Claude Code / Desktop) — komut **repo venv'i** olmalı,
global Python'da `mcp 2.0.0` var ve `aa_mcp` kurulu değil:

```json
{
  "aa": {
    "type": "stdio",
    "command": "C:\\Projeler\\Claude\\homelab-aa-mcp\\.venv\\Scripts\\python.exe",
    "args": ["-m", "aa_mcp"]
  }
}
```

## Tool'lar

| Tool | Ne yapar |
|---|---|
| `list_models` | Fiyat/hız/benchmark'a göre süzülüp sıralanmış model listesi (özet alanlar) |
| `get_model` | Tek modelin tüm ölçümleri; bulunamazsa benzer slug önerir |
| `compare_models` | 2–5 modeli yan yana koyar |
| `list_providers` | Bir modeli sunan sağlayıcılar, ucuzdan pahalıya (ticari katman gerektirebilir) |

Hepsi salt-okunur (`read_only_hint`), yapılandırılmış çıktı verir ve yanıtına
`meta` ekler: katman, zeka indeksi sürümü, verinin çekilme zamanı, tazelik
(`fresh`/`cached`/`stale`) ve kalan kota.

## Katman farkı (canlı doğrulandı, 2026-09-18)

Elimizdeki anahtar **free** katmanında (`x-aa-tier: free`). Gerçek yanıt:
`/language/models` → `403 "Language models list requires a Pro subscription"`,
sunucu otomatik `/language/models/free`'ye düşüyor — 652 model, 4 sayfa,
`intelligence_index_version` 4.3.

| Alan | free | Pro |
|---|---|---|
| `slug`, `name`, `creator`, `release_date` | ✓ | ✓ |
| Zeka / kodlama / agentic indeksi | ✓ | ✓ |
| Zeka indeksi koşturma maliyeti (`index_cost`) | ✓ (652'nin 135'inde) | ✓ |
| Girdi, çıktı, cache hit/write fiyatı | ✓ | ✓ |
| tokens/s, TTFT, uçtan uca süre | ✓ | ✓ |
| Harmanlanmış fiyat (`price_blended`) | — | ✓ |
| Bağlam penceresi, açık ağırlık, parametre sayısı | — | ✓ |
| `reasoning_model`, HuggingFace / OpenRouter kimliği | — | ✓ |
| İndeks dışı benchmark'lar (`gpqa_diamond` vb.) | — | ✓ |

`index_cost`, AA'nın zeka indeksi test setini o modelde koşturmasının **toplam
maliyetidir** (USD); `get_model` ayrıca görev başına maliyeti de verir
(`intelligence_index_cost_usd`, `intelligence_index_cost_per_task_usd`). Fiyat
listesi değil, "bu zekâ kaça mal oluyor" ölçüsüdür — modellerin yaklaşık
beşte birinde ölçülmüştür, geri kalanı sıralamada sona düşer.

`list_models`, harmanlanmış fiyata göre sıralama ya da `max_price_blended`
süzmesi istendiğinde katmanda bu alan yoksa **sessiz boş sonuç yerine açık hata**
verir; `price_input` / `price_output` çalışır.

`list_providers` ise **Commercial** erişim ister; free anahtarla AA'nın kendi
metnini taşıyan bir hata döner ("Providers list requires Commercial API access…").
Bu hata cache'lenmez, yani her çağrı kotadan 1 istek harcar.

İlk soğuk açılışta Pro yolu bir kez denendiği için 403 de kotadan sayılır
(toplam 5 istek); seçilen yol cache'e yazıldığından sonraki tazelemeler 4 istek.

## Kota ve cache

Ücretsiz katman **24 saatte 100 istek** ve kota anahtar değil organizasyon
bazlıdır. Sunucu tüm model listesini tek seferde çeker, 12 saat (`AA_CACHE_TTL_HOURS`)
bellekte + diskte tutar; süreç yeniden başlasa bile disk kopyası kullanılır.
AA erişilemezse bayat kopya `freshness="stale"` işaretiyle döner.

## Yapılandırma

| Değişken | Varsayılan | Açıklama |
|---|---|---|
| `AA_API_KEY` | — | Zorunlu |
| `AA_CACHE_TTL_HOURS` | 12 | 0 = cache kapalı (önerilmez) |
| `AA_CACHE_DIR` | `%LOCALAPPDATA%\aa-mcp` | Disk cache yeri |
| `AA_HTTP_TIMEOUT` | 30 | Saniye |

## Test

```bash
.venv/Scripts/python.exe -m pytest -q
```

Ağ gerektirmez. Ücretsiz katman fixture'ları canlı yanıttan birebir alındı
(2026-09-18); harmanlanmış fiyat/lisans gibi yalnız Pro'da olan alanların
fixture'ları AA dokümanından türetildi ve canlı doğrulanmadı.
Duman testi sunucuyu gerçekten stdio'dan açıp protokol pazarlığının
`2026-07-28` olduğunu doğrular.

## Lisans

GPL-3.0-or-later.