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ı

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:

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.

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

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