🧾 fatura-mcp

GİB e-Arşiv portal üzerinde e-Fatura, e-Müstahsil Makbuzu ve e-SMM (Serbest Meslek Makbuzu) oluşturma, listeleme, imzalama vb. işlemler için MCP (Model Context Protocol) sunucusu.

mlevent/fatura PHP paketinin TypeScript/MCP portudur. Hesaplama mantığı (iskonto, KDV, tevkifat, özel matrah, stopaj, toplamlar) ve GİB istek formatları birebir taşınmıştır; hesaplamalar PHP paketinin kendi test senaryolarıyla doğrulanmıştır.

☢️ Bu araç vergiye tabi mali veri oluşturabilir. Belge imzalama (SMS doğrulama) işlemi faturanın resmen kesilmesi anlamına gelir; imzalanan belge değiştirilemez ve silinemez. Riskleri kullanan üstlenir.

Kurulum

Node.js 20.12+ gerekir. Sunucu stdio üzerinde çalışır:

git clone https://github.com/bevren/gib-fatura-mcp.git
cd gib-fatura-mcp
npm install
npm start

Claude Code

claude mcp add fatura -- npx tsx <bu-deponun-yolu>/src/index.ts

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "fatura": {
      "command": "npx",
      "args": ["tsx", "<bu-deponun-yolu>/src/index.ts"]
    }
  }
}

Kullanım Akışı

1. gib_login — gerçek kullanıcı: username + password; deneme için: testMode: true (otomatik test hesabı alınır, test portalında mali değer oluşmaz).
2. gib_create_invoice / gib_create_producer_receipt / gib_create_self_employed_receipt — belge taslağı oluşturur, tüm tutarlar otomatik hesaplanır, oluşan uuid (ETTN) döner.
3. gib_list_documents, gib_get_document, gib_get_document_html — kontrol/inceleme.
4. gib_start_sms_verification → gib_complete_sms_verification — belgeleri imzalar (☢️ resmi fatura keser; test hesaplarıyla çalışmaz).
5. gib_logout

Araçlar

Araç	Açıklama
gib_login	Portala giriş (gerçek veya otomatik test hesabı)
gib_set_token	Mevcut token ile oturum
gib_logout / gib_session_info	Oturum kapatma / durum
gib_create_invoice	e-Fatura taslağı (Satış, İade, Tevkifat, İstisna, Özel Matrah); uuid+belgeNumarasi ile güncelleme
gib_create_producer_receipt	e-Müstahsil makbuzu taslağı
gib_create_self_employed_receipt	e-SMM taslağı
gib_list_documents	Düzenlenen belgeler (tarih aralığı + onay durumu/tür/alıcı/belge no/ETTN filtreleri, limit, sıralama)
gib_list_documents_issued_to_me	Adıma düzenlenen belgeler
gib_get_document / gib_get_last_document	Belge detayı / en son belge
gib_get_document_html	HTML çıktı
gib_get_download_url / gib_save_document_to_disk	İndirme adresi / zip olarak diske kaydetme
gib_delete_drafts	Taslak silme
gib_start_sms_verification / gib_complete_sms_verification	SMS ile belge imzalama
gib_cancellation_request / gib_objection_request / gib_get_requests	İptal/itiraz talepleri
gib_get_user_data / gib_update_user_data	GİB profil bilgileri okuma/güncelleme
gib_get_recipient_data	VKN/TCKN ile mükellef sorgulama
gib_get_reference_data	Birimler, vergiler, tevkifat kodları, özel matrah nedenleri, fatura tipleri, para birimleri

Örnek: Satış Faturası

gib_create_invoice argümanları:

{
  "vknTckn": "11111111111",
  "aliciAdi": "Mert",
  "aliciSoyadi": "Levent",
  "mahalleSemtIlce": "Nilüfer",
  "sehir": "Bursa",
  "ulke": "Türkiye",
  "malHizmetListe": [
    { "malHizmet": "Çimento", "miktar": 3, "birim": "M3", "birimFiyat": 1259, "kdvOrani": 18, "iskontoOrani": 25 }
  ]
}

Dövizli fatura için paraBirimi + dovizKuru; iade için faturaTipi: "Iade" + iadeListe; tevkifat için faturaTipi: "Tevkifat" + kalemde tevkifatKodu; istisna için faturaTipi: "Istisna" + kalemde gtip; özel matrah için faturaTipi: "OzelMatrah" + kalemde ozelMatrahNedeni/ozelMatrahTutari. Kalemlere vergiler ile ek vergi eklenebilir (ör. {"vergi": "Damga", "oran": 15}).

Testler

npm run test:model   # Hesaplama testleri (PHP paketinin ModelTest senaryoları)
npm run smoke        # MCP el sıkışması + araç listesi (ağ gerektirmez)
npm run test:e2e     # GİB TEST portalına karşı uçtan uca (test hesabı)

Bilinen Notlar

• Taslak silme: GİB portalı (en azından test ortamında) EARSIV_PORTAL_FATURA_SIL isteğini zaman zaman "Silinirken bir sorun oluştu." yanıtıyla reddediyor. İstek formatı PHP paketi ve fatura.js ile birebir aynıdır; sorun portal tarafındadır.
• İndirme adresi: gib_get_download_url yalnızca tokenın alındığı IP adresinden çalışır; başka makineden erişim için gib_save_document_to_disk kullanın.
• Adıma düzenlenen belgeler: GİB tarafında bu servis her zaman stabil çalışmıyor.
• SMS imzalama test hesaplarıyla gerçekleştirilemez; mükellef sorgulama test ortamında boş döner.
• Token süresi dolduğunda gib_login ile yeni token alınmalıdır.