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.

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ı:

{
  "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ı

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:

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 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:

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 dosyasındadır.

Test ve kalite kontrolleri

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

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