# 🧾 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](https://github.com/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:

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

### Claude Code

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

### Claude Desktop (`claude_desktop_config.json`)

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

```json
{
  "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

```bash
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.