Metadata-Version: 2.5
Name: veritr-mcp
Version: 0.1.0
Summary: Türkiye's public data layer for AI agents — TÜİK, TCMB and more through one MCP server.
Project-URL: Homepage, https://github.com/ulascan54/VeriTR-MCP
Project-URL: Repository, https://github.com/ulascan54/VeriTR-MCP
Project-URL: Issues, https://github.com/ulascan54/VeriTR-MCP/issues
Author: VeriTR Contributors
License: MIT
License-File: LICENSE
Keywords: ai-agents,evds,government-data,llm,mcp,mcp-server,model-context-protocol,open-data,tcmb,tuik,turkey,turkiye,turkstat
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: diskcache>=5.6
Requires-Dist: fastmcp>=2.3
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# 🇹🇷 VeriTR

### Türkiye'nin verisi. Yapay zekânın bağlamı.

**VeriTR**, Türkiye'deki resmi ve açık veri kaynaklarını Claude, ChatGPT, Gemini ve diğer AI agent'ların kullanabileceği tek bir Model Context Protocol (MCP) sunucusunda birleştiren açık kaynaklı bir projedir.

TÜİK'ten nüfus, TCMB'den ekonomik göstergeler, İBB'den İstanbul'un şehir verileri; ilerleyen sürümlerde SGK'dan istihdam, YSK'dan seçim…
**Kaynağı aramak yerine soruyu sorun.**

[![test](https://github.com/ulascan54/VeriTR-MCP/actions/workflows/test.yml/badge.svg)](https://github.com/ulascan54/VeriTR-MCP/actions/workflows/test.yml)
[![Python](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-000000)](https://modelcontextprotocol.io/)
[![Kaynaklar](https://img.shields.io/badge/kaynaklar-T%C3%9C%C4%B0K%20%C2%B7%20TCMB%20%C2%B7%203%20belediye-0a7d38)](#-kaynaklar)
[![Göstergeler](https://img.shields.io/badge/g%C3%B6stergeler-42%20normalize-0a7d38)](#-kaynaklar)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

<!-- PyPI rozeti bilinçli olarak yok: paket henüz yayımlanmadı ve shields.io
     "package or version not found" diye kırmızı basıyor. İlk release'ten sonra
     bu satırı ekleyin:
     [![PyPI](https://img.shields.io/pypi/v/veritr-mcp.svg)](https://pypi.org/project/veritr-mcp/)
     Aynı şekilde Docker rozeti de ilk imaj yayımlandıktan sonra anlamlı olur:
     [![Docker](https://img.shields.io/badge/docker-ghcr.io-2496ED?logo=docker&logoColor=white)](https://github.com/ulascan54/VeriTR-MCP/pkgs/container/veritr) -->

---

## Neden VeriTR?

Türkiye'nin kamu verisi dağınıktır. Nüfus TÜİK'te, enflasyon ve konut fiyatları TCMB'de, istihdam SGK'da, bütçe Hazine'de, seçim sonuçları YSK'da, şehir verileri onlarca ayrı belediye portalında durur. Her kurumun kendi arayüzü, kendi kod sistemi, kendi tarih biçimi ve kendi "il" tanımı vardır. Bir soruya cevap vermek için önce hangi kurumun hangi tabloyu tuttuğunu bilmek gerekir.

Bu yük, bugün bir AI agent'ın üzerine yıkılıyor. Agent ya veriyi bulamıyor ya da ezberinden — kaynaksız ve çoğu zaman yanlış — cevap veriyor.

**VeriTR bu kaynakları AI agent'lar için tek bir MCP arayüzünde birleştirir.** Kurum isimleri yerine normalize göstergeler (`population.total`, `economy.cpi`), kurum kodları yerine ortak coğrafya ve tarih modeli, ve her sonucun yanında **hangi kurumun hangi veri setinden geldiği** bulunur.

---

## 💬 VeriTR ile neler sorabilirsiniz?

```text
"İstanbul'un nüfusu son 20 yılda nasıl değişti?"

"Türkiye'deki genç işsizlik oranının son 15 yıllık değişimini göster."

"2025'te nüfusu en fazla olan 10 şehri sırala."

"İstanbul, Ankara ve İzmir'in nüfus artış hızını karşılaştır."

"Türkiye'de araç sayısı en fazla olan illeri bul."

"Kişi başına düşen geliri en yüksek ve en düşük illeri karşılaştır."

"Doğurganlık hızı Türkiye'de son 15 yılda nasıl değişti?"

"Güneydoğu Anadolu ile Ege'nin kişi başı gelirini karşılaştır."

"Türkiye'nin sera gazı emisyonları 1990'dan bu yana nasıl arttı?"

"Türkiye'de kaç elektrikli araba var, son 5 yılda nasıl değişti?"

"Konut satışları en çok hangi ilde arttı?"

"Trafik kazalarında ölen kişi sayısı illere göre nasıl dağılıyor?"

"İstanbul'da trafik kazası duyurularını içeren veri setini bul ve göster."

"İzmir'in açık veri portalında ulaşımla ilgili neler var?"

"Konut fiyat endeksi ile TÜFE'yi 2015'ten bu yana karşılaştır."   ← TCMB anahtarı ister
```

Agent gerekli göstergeleri kendisi bulur, verileri VeriTR üzerinden çeker, dönemleri eşleştirir ve **kaynağıyla birlikte** cevap üretir.

---

## 🚀 5 Dakikada Başla

> **Not:** VeriTR henüz PyPI'da yayımlanmadı. Bugün kaynaktan çalışıyor; ilk sürüm çıktığında `uvx veritr-mcp` tek satırlık kuruluma dönüşecek.

### Kaynaktan çalıştırma

```bash
git clone https://github.com/ulascan54/VeriTR-MCP.git
cd VeriTR-MCP
uv sync
uv run veritr-mcp
```

Python 3.12+ ve [uv](https://docs.astral.sh/uv/) gerekir. **API anahtarı gerekmez** — TÜİK ve belediye verileri anahtarsız çalışır.

### Claude Desktop / Claude Code

`claude_desktop_config.json` dosyanıza ekleyin (`/yol/VeriTR-MCP` yerine kendi klasörünüzü yazın):

```json
{
  "mcpServers": {
    "veritr": {
      "command": "uv",
      "args": ["run", "--directory", "/yol/VeriTR-MCP", "veritr-mcp"]
    }
  }
}
```

TCMB'nin finansal serilerini de istiyorsanız [evds2.tcmb.gov.tr](https://evds2.tcmb.gov.tr) adresinden ücretsiz bir anahtar alın:

```json
{
  "mcpServers": {
    "veritr": {
      "command": "uv",
      "args": ["run", "--directory", "/yol/VeriTR-MCP", "veritr-mcp"],
      "env": {
        "EVDS_API_KEY": "buraya-anahtarınız"
      }
    }
  }
}
```

Anahtar olmadan da çalışır: TCMB `not_configured` görünür, diğer kaynaklar sorunsuz devam eder.

### Docker

```bash
docker compose up -d
# MCP:    http://localhost:8000/mcp
# Health: http://localhost:8000/health
```

### PyPI ve Remote MCP

İkisi de **yol haritasında**. Yayımlandığında bu bölüm şu hâle gelecek:

```bash
uvx veritr-mcp          # yayımlanmadı
pip install veritr-mcp  # yayımlanmadı
```

Hosted Remote MCP (`https://…/mcp`) için henüz bir adres yok; kodda hiçbir domain gömülü değildir, `VERITR_PUBLIC_URL` ile verilir.

---

## 🏗️ Mimari

```mermaid
flowchart LR
    A[Claude / ChatGPT / Gemini] --> B[VeriTR MCP]
    B --> C[Unified Data Layer]
    C --> D[TÜİK]
    C --> E[TCMB]
    C --> J[Belediyeler<br/>İBB · İzmir · Konya]
    C -.-> F[SGK]
    C -.-> G[HMB]
    C -.-> H[YSK]
    C -.-> I[MGM]
```

Kesikli çizgiler yol haritasındaki kaynakları gösterir.

VeriTR iki erişim yolu sunar ve hangisinin doğru olduğunu tool açıklamaları anlatır:

- **Normalize gösterge** (`get_series`) — ulusal, karşılaştırılabilir seriler. `population.total` kimin yayımladığından bağımsızdır.
- **Ham veri seti kataloğu** (`search_datasets` → `get_dataset`) — belediye verileri ve henüz normalize edilmemiş kurum veri setleri. Belediye verisi bilinçli olarak gösterge namespace'ine **zorlanmaz**: "metro yolcu sayısı" ile "ağaç envanteri" ortak bir modele oturmaz, oturtmaya çalışmak veriyi çarpıtır.

CKAN belediye açık verisinde fiilî standart olduğu için yeni bir şehir eklemek [tek satırlık bir tablo kaydıdır](src/veritr/providers/municipal/cities.py) — adapter kodu değişmez.

Verinin izlediği yol:

```text
Resmi Kaynaklar          TÜİK .Stat API, TCMB EVDS, İBB CKAN, …
       ↓
Provider Adapters        her kurum için bağımsız, izole edilmiş adapter
       ↓
Normalization            coğrafya (81 il), dönem, frekans, birim
       ↓
Indicator Registry       population.total, economy.cpi, …
       ↓
MCP Tools                search_indicators, get_series, compare_series, …
       ↓
AI Agents
```

Bir kaynağın çökmesi diğerlerini etkilemez: TÜİK erişilemezse agent bunu `provider_unavailable` olarak görür ve diğer kaynaklara erişmeye devam eder.

---

## 🧰 Tool'lar

| Tool | Ne işe yarar | Örnek |
| --- | --- | --- |
| `search_indicators` | Doğal dille gösterge bulur. **get_series'ten önce kullanılır.** | `search_indicators("işsizlik")` |
| `get_series` | Bir göstergenin zaman serisini getirir. En temel tool. | `get_series("population.total", geography="TR-34", start_date="2015")` |
| `get_snapshot` | Tek bir dönemde tüm illeri sıralar. | `get_snapshot("population.total", date="2025", top=10)` |
| `compare_regions` | Bir göstergeyi birkaç ilde karşılaştırır. | `compare_regions("population.total", regions=["TR-34","Ankara","35"])` |
| `compare_series` | Birkaç göstergeyi — farklı kurumlardan olsa da — yan yana koyar. | `compare_series(["economy.cpi","housing.house_price_index"], normalize=True)` |
| `analyze_series` | Deterministik istatistik: artış hızı, hareketli ortalama, endeksleme. | `analyze_series("population.total", operations=["growth_rate"])` |
| `get_metadata` | Bir göstergenin birimi, frekansı, ayarlanabilir boyutları ve kaynağı. | `get_metadata("population.median_age")` |
| `search_datasets` | Ham veri setlerinde arama — İstanbul'a dair şehir soruları buradan. | `search_datasets("metro yolcu")` |
| `get_dataset` | Bulunan ham veri setinin sütunlarını ve satırlarını okur. | `get_dataset("hourly-public-transport-data-set")` |
| `get_sources` | Tüm kaynakların canlı durumu. | `get_sources()` |

**Coğrafya** her biçimde kabul edilir — ülke (`TR`, `Türkiye`), 81 il (`TR-34`, `34`, `İstanbul`, `istanbul`, `TR100`), 12 İBBS Düzey-1 bölgesi (`TR9`) ve 26 Düzey-2 alt bölgesi (`TRC1` → Gaziantep, Adıyaman, Kilis).

**Dönem** de öyle: `2024`, `2024-Q1`, `2024-01`, `2024M01`, `01-2024`, `15.01.2024`.

---

## 📊 Kaynaklar

| Kaynak | Veri | Durum | API Key |
| --- | --- | --- | --- |
| **TÜİK** | Nüfus, doğurganlık, işgücü, eğitim, ulaşım, trafik, konut satışları, üretim endeksleri, dış ticaret, GSYH, çevre | ✅ | Hayır |
| **TCMB EVDS** | TÜFE, ÜFE, konut fiyat endeksi, döviz, faiz | ✅ | Evet |
| **İBB Açık Veri** | İstanbul: ulaşım, trafik, çevre, kültür, altyapı (~560 veri seti) | ✅ | Hayır |
| **İzmir BB Açık Veri** | İzmir: ulaşım, çevre, şehir hizmetleri (~256 veri seti) | ✅ | Hayır |
| **Konya BB Açık Veri** | Konya: ulaşım, altyapı, şehir hizmetleri (~233 veri seti) | ✅ | Hayır |
| SGK | Sosyal güvenlik ve istihdam | 🗺️ | – |
| HMB | Bütçe ve kamu maliyesi | 🗺️ | – |
| SBB | Ekonomik ve sosyal göstergeler | 🗺️ | – |
| YSK | Seçim sonuçları ve katılım | 🗺️ | – |
| MGM | Meteoroloji | 🗺️ | – |
| Sağlık Bakanlığı | Hastane, personel, sağlık göstergeleri | 🗺️ | – |
| Enerji Bakanlığı | Elektrik üretimi, yenilenebilir enerji | 🗺️ | – |
| Ticaret Bakanlığı | İthalat, ihracat | 🗺️ | – |
| Diğer belediyeler | Ankara, Bursa, Antalya, Kocaeli, Gaziantep | 🗺️ | – |
| Eurostat / OECD / World Bank | Uluslararası karşılaştırma | 🗺️ | – |

```text
✅ Destekleniyor    🚧 Geliştiriliyor    🗺️ Yol haritasında
```

**Anahtar gerekmeden ne kadar yol gidilir?** Epey: nüfus, doğurganlık, işgücü, eğitim, ulaşım, trafik, konut **satışları**, üretim endeksleri, dış ticaret, GSYH ve çevre göstergelerinin tamamı TÜİK'ten, şehir verileri belediyelerden anahtarsız gelir. TCMB anahtarı bunlara fiyat endekslerini (TÜFE, ÜFE, konut fiyat endeksi) ve finansal serileri ekler.

Bugün **42 normalize gösterge** (nüfus, doğurganlık, hanehalkı, işgücü, eğitim, ulaşım, trafik güvenliği, konut satışları, sanayi/hizmet/inşaat üretimi, dış ticaret, GSYH, çevre, fiyatlar, döviz) ve **~1450 aranabilir ham veri seti** (TÜİK 408 + üç belediye ~1050) mevcut. Her göstergenin her coğrafya seviyesinde gerçekten veri döndürdüğü [günlük canlı testlerle](tests/integration/) doğrulanıyor.

Registry sürekli genişliyor — [katkı vermek kolay](docs/ADDING_A_PROVIDER.md).

---

## 🔎 Veriler nereden geliyor?

**VeriTR herhangi bir resmi kurum değildir ve veri üretmez.**

Veriler ilgili kurumların kendi resmi/açık kaynaklarından, herkese açık arayüzleri üzerinden alınır. VeriTR yalnızca üç şey yapar: **erişim**, **standardizasyon** ve **agent entegrasyonu**.

Her sonuç şu bilgileri taşır:

```json
{
  "source": {
    "provider": "tuik",
    "institution": "Türkiye İstatistik Kurumu",
    "dataset": "TR,DF_ADNKS_T30,1.1",
    "retrieved_at": "2026-08-11T12:08:55+00:00",
    "official_url": "https://databrowser2.tuik.gov.tr/vizualize.html?..."
  }
}
```

Böylece agent "TÜİK'e göre…" diyebilir ve kullanıcı aynı veriyi kurumun kendi sitesinde doğrulayabilir.

Verilerin **güncelliği, doğruluğu ve kullanım koşulları** tamamen ilgili kaynak kuruma bağlıdır. VeriTR'nin MIT lisansı yalnızca bu deponun kodunu kapsar; **kurumlardan alınan verileri kapsamaz.**

### Dürüstlük ilkeleri

VeriTR veriyi sessizce değiştirmez:

- **Frekans uyumsuzluğu gizlenmez.** Aylık TÜFE ile yıllık nüfusu karşılaştırırsanız uyarı alırsınız; arka planda sessiz bir toplulaştırma yapılmaz.
- **Kırpma duyurulur.** Sonuç listesi kısaltıldıysa kaç kaydın düştüğü açıkça söylenir.
- **Eksik veri uydurulmaz.** Kurum bir değeri yayımlamamışsa `null` döner, interpolasyon yapılmaz.
- **Veri sınırları yazılıdır.** Kurum bir göstergeyi yalnızca son yıl için yayımlıyorsa bu, göstergenin açıklamasında söylenir — agent "veri yok" sanmaz.
- **Korelasyon nedensellik değildir.** Korelasyon çıktısı bu uyarıyı her zaman taşır.

---

## ⚠️ Sorumluluk Reddi

> VeriTR; TÜİK, TCMB, SGK veya diğer kamu kurumlarıyla bağlantılı değildir, bu kurumlar tarafından desteklenmemekte veya onaylanmamaktadır. Tüm kurum adları ve markalar ilgili sahiplerine aittir.

---

## 🗺️ Yol Haritası

**v0.1** — ✅ TÜİK + TCMB EVDS · normalize gösterge registry'si · `search_indicators`, `get_series`, `get_metadata`, `compare_series`, `compare_regions`, `get_snapshot`, `analyze_series` · cache · CSV/JSON export · Docker + Streamable HTTP

**v0.2** — SGK · Hazine ve Maliye Bakanlığı · genişletilmiş gösterge kataloğu · hosted Remote MCP

**v0.3** — YSK (seçim) · MGM (meteoroloji) · Sağlık Bakanlığı · Enerji Bakanlığı

**v0.4** — Kalan belediye adapter'ları (Ankara, Bursa, Antalya, Kocaeli, Gaziantep) — İstanbul, İzmir ve Konya v0.1'de geldi

**v1.0** — Uluslararası karşılaştırma (Eurostat, OECD, World Bank, IMF, ILOSTAT) · VeriTR Explorer · stabil API

Ayrıntılar ve tekil görevler için [issue'lara](https://github.com/ulascan54/VeriTR-MCP/issues) bakın.

---

## 🤝 Katkı

VeriTR'nin büyümesinin ana yolu **topluluk provider'ları**. Yeni bir kurum eklemek kasıtlı olarak kolay tutuldu: bir adapter sınıfı, bir YAML gösterge dosyası ve fixture'lı testler.

📖 **[docs/ADDING_A_PROVIDER.md](docs/ADDING_A_PROVIDER.md)** — adım adım rehber
📋 **[CONTRIBUTING.md](CONTRIBUTING.md)** — geliştirme akışı ve kalite ölçütleri
🔒 **[SECURITY.md](SECURITY.md)** — güvenlik açığı bildirimi

```bash
uv sync
uv run pytest              # offline testler
uv run pytest -m live      # kurumların canlı API'lerine karşı
uv run ruff check src tests
uv run mypy
```

---

## 📄 Lisans

Kod [MIT](LICENSE) lisansıyla dağıtılır.
Kurumlardan alınan veriler **bu lisansın kapsamı dışındadır** ve kendi kullanım koşullarına tabidir.
