# Türkiye Vergi MCP

Resmî Gelir İdaresi Başkanlığı (GİB) kaynaklarını kullanan, yerel çalışabilen ve
yapılandırılmış sonuç üreten Model Context Protocol sunucusu.

Bu proje şu yetenekleri tek sunucuda toplar:

- Kanun, madde, tebliğ, sirküler, özelge, yönetmelik ve karar arama
- Resmî belge tam metni ve tarih aralığına göre değişiklik tarama
- KDV, KDV tevkifatı, stopaj ve gecikme zammı hesaplama
- Canlı GİB vergi takvimi ve isteğe bağlı ICS çıktısı
- UBL-TR/e-Fatura XML ile CSV/XLSX fatura denetimi
- Resmî kanıt bağlantıları içeren şirket içi vergi sirküleri taslağı

> Bu sunucu genel bilgilendirme ve araştırma amaçlıdır. Hukuki görüş veya mali
> müşavirlik hizmeti vermez. İşleme özgü sonuçlar güncel resmî metin ve yetkili
> uzman tarafından doğrulanmalıdır.

## Hızlı başlangıç

Gereksinimler: Python 3.11–3.14 ve [uv](https://docs.astral.sh/uv/).

```powershell
uv sync --native-tls --extra dev
uv run vergi-mcp
```

`stdio` taşıması kullanılır; masaüstü MCP istemcileri için önerilen çalışma
şeklidir. Sunucu standart çıktıya log yazmaz, dolayısıyla JSON-RPC akışı bozulmaz.

Genel bir MCP istemci yapılandırması:

```json
{
  "mcpServers": {
    "vergi": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\PROJE\\vergiMcp",
        "run",
        "vergi-mcp"
      ]
    }
  }
}
```

Yolu kendi proje klasörünüzle değiştirin. API anahtarı gerekmez.

## Sunulan MCP araçları

| Araç | İşlev |
|---|---|
| `saglik_kontrolu` | Sunucu sürümü ve isteğe bağlı canlı GİB erişimi |
| `mevzuat_ara` | Tüm resmî vergi belge türlerinde arama |
| `ozelge_ara` | Konu, kanun ve tarih filtreli özelge arama |
| `mevzuat_belgesi_getir` | Arama sonucundaki GİB sayfasını temiz metin olarak alma |
| `mevzuat_degisikliklerini_bul` | Tarih aralığındaki yeni düzenlemeleri tarama |
| `kdv_hesapla` | KDV hariç/dâhil ve isteğe bağlı tevkifat hesabı |
| `stopaj_hesapla` | Brüt/net stopaj ve isteğe bağlı KDV hesabı |
| `gecikme_zammi_oranlari` | Yürürlük tarihli resmî oran tablosu |
| `gecikme_zammi_hesapla` | Tam ay ve günlük kesirleri dikkate alan hesaplama |
| `vergi_takvimi` | Canlı beyan/ödeme takvimi ve ICS çıktısı |
| `fatura_denetle` | XML, CSV veya XLSX fatura kontrolü |
| `sirkuler_taslagi_olustur` | Kaynak bağlantılı Markdown sirküler taslağı |
| `resmi_kaynaklari_listele` | Kullanılan birincil kaynak kataloğu |

Kaynaklar ayrıca `vergi://resmi-kaynaklar`,
`vergi://oranlar/gecikme-zammi` ve `vergi://yasal-uyari` URI’leriyle sunulur.

## Örnek istekler

Bir MCP istemcisinde doğal dille şunları isteyebilirsiniz:

- “KDV tevkifatı konusunda 2026 özelgelerini ara ve kaynaklarını göster.”
- “118.000 TL KDV dâhil tutarı %20 KDV ve 7/10 tevkifatla hesapla.”
- “1 Ocak–31 Temmuz 2026 arasındaki KDV son tarihlerini ICS olarak getir.”
- “Bu UBL-TR XML faturasındaki matematik ve zorunlu alan hatalarını denetle.”
- “Son altı aydaki e-Defter düzenlemelerinden yönetim sirküleri taslağı hazırla.”

## Fatura denetimi

Üç girdi biçimi desteklenir:

- Doğrudan `xml_icerigi`
- Base64 kodlu `base64_xml`
- Yerel `.xml`, `.csv` veya `.xlsx` için `dosya_yolu`

Yerel dosya okuma varsayılan olarak yalnızca sunucunun başlatıldığı klasörle
sınırlıdır. İzinli kökleri `.env` içinde noktalı virgülle belirleyebilirsiniz:

```dotenv
VERGI_MCP_ALLOWED_INPUT_DIRS=C:\Faturalar;D:\Kontrol
VERGI_MCP_MAX_INPUT_BYTES=10485760
VERGI_MCP_MAX_INVOICE_ROWS=10000
```

Denetleyici:

- DTD/haricî varlık işlemeden güvenli XML ayrıştırır.
- UBL 2.1/TR profil alanlarını ve taraf kimliklerini kontrol eder.
- Satır, vergi, tevkifat ve ödenecek tutar matematiğini `Decimal` ile karşılaştırır.
- CSV/XLSX sütunlarını Türkçe ve İngilizce yaygın başlıklarla eşler.
- VKN/TCKN değerlerini çıktıda maskeleyerek raporlar.
- Dosya içeriğini hiçbir dış servise göndermez.

Bu kontrol, GİB’in tam XSD/Schematron doğrulaması veya XMLDSig/XAdES imza
doğrulaması değildir. Sonuç modeli bunu açıkça belirtir; “GİB tarafından geçerli”
iddiasında bulunmaz. Tam resmî doğrulama için GİB’in güncel UBL-TR 1.2.1 XSD,
Schematron/kod listesi ve uygun XPath 2.0 motoru ayrıca kurulmalıdır.

## Hesaplamaların kapsamı

- Para hesabında ikili kayan nokta yerine `Decimal` ve `ROUND_HALF_UP` kullanılır.
- KDV ve stopaj oranları kullanıcı girdisidir; işlem sınıflandırması otomatik
  hukuki karar olarak verilmez.
- Gecikme zammı oranları yürürlük başlangıç/bitiş tarihleriyle
  [`tax_rates.json`](src/vergi_mcp/data/tax_rates.json) içinde tutulur.
- Gecikme zammı motoru tam ayları, günlük kesirleri, dönem içi oran değişikliklerini,
  günlük oranın altı ondalığa yukarı tamamlanmasını ve asgari 1 TL kuralını raporlar.
- Tecil, iflas, aciz, mücbir sebep ve benzeri özel durumlar standart hesap dışında
  bırakılır ve sonuçta uyarı olarak gösterilir.

## Streamable HTTP

Yerel HTTP endpoint’i çalıştırmak için:

```powershell
uv run vergi-mcp-http
```

Endpoint `http://127.0.0.1:8000/mcp` olur. Kimlik doğrulamasız HTTP taşıması
güvenlik nedeniyle yalnızca loopback adresinde başlatılır. Özellikle mükellef veya
fatura verisi işlenecekse sunucuyu doğrudan internete açmayın. Uzak dağıtım için
OAuth/token doğrulaması, TLS, erişim kaydı ve veri saklama politikası ekleyin.

## Yapılandırma

Tüm değişkenler `VERGI_MCP_` önekini kullanır. Örnekler
[`.env.example`](.env.example) dosyasındadır.

| Değişken | Varsayılan | Açıklama |
|---|---:|---|
| `VERGI_MCP_REQUEST_TIMEOUT_SECONDS` | `25` | GİB HTTP zaman aşımı |
| `VERGI_MCP_CACHE_TTL_SECONDS` | `600` | Salt okunur yanıt önbelleği |
| `VERGI_MCP_ALLOWED_INPUT_DIRS` | `.` | Okunabilecek yerel klasörler |
| `VERGI_MCP_MAX_INPUT_BYTES` | `10485760` | Azami fatura boyutu |
| `VERGI_MCP_MAX_INVOICE_ROWS` | `10000` | Azami tablo satırı |
| `VERGI_MCP_HTTP_HOST` | `127.0.0.1` | Yerel HTTP bind adresi |
| `VERGI_MCP_HTTP_PORT` | `8000` | Yerel HTTP portu |
| `VERGI_MCP_LOG_LEVEL` | `INFO` | stderr log seviyesi |

## Test ve kalite kontrolleri

```powershell
uv run pytest
uv run pytest --cov=vergi_mcp --cov-report=term-missing
uv run ruff check .
uv run mypy src
uv run python scripts/live_smoke.py
uv run python scripts/http_smoke.py
```

Test paketi saf hesaplamaları, XML/tablo ayrıştırmayı, dosya yolu sınırlarını,
GİB yanıt normalizasyonunu ve MCP’nin bellek içi araç sözleşmelerini kapsar.

## Mimari

```text
src/vergi_mcp/
├── server.py                 MCP araç, kaynak ve prompt kayıtları
├── config.py                 Ortam ayarları ve dosya erişim sınırları
├── clients/gib.py            GİB HTTP adaptörü, retry ve önbellek
├── services/mevzuat.py       Mevzuat/özelge/değişiklik araması
├── services/calendar.py      Canlı vergi takvimi
├── services/calculations.py  Decimal tabanlı hesap motorları
├── services/invoice.py       UBL-TR ve tablo denetimi
├── services/circular.py      Kanıt tabanlı sirküler taslağı
└── data/tax_rates.json       Yürürlük tarihli oran verisi
```

İş mantığı MCP dekoratörlerinden ayrıdır; servisler doğrudan test edilebilir.
GİB’in ön yüz API’sinin yayımlanmış bir OpenAPI sözleşmesi bulunmadığı için bütün
uçlar tek bir değiştirilebilir adaptörde tutulur ve beklenmeyen yanıtlar sessizce
yanlış sonuca çevrilmez.

## Veri güncelliği

Mevzuat ve takvim her çağrıda GİB’den alınır ve kısa süreli önbelleğe konur.
Hesaplama oranları sürümlü yerel veridir. Oran dosyası güncellenirken:

1. GİB’in resmî oran geçmişini kontrol edin.
2. Yeni kaydı yürürlük tarihi ve kaynak URL’siyle ekleyin.
3. Önceki kaydın `effective_to` tarihini kapatın.
4. Oran sınır ve geçiş testlerini çalıştırın.

## Lisans

[MIT](LICENSE)