imzala-mcp

# İmzala MCP Sunucusu **İmzala MCP sunucusu:** AI asistanınızın (Claude, Cursor vb.) İmzala hesabınıza erişmesini sağlar. API anahtarıyla kimlik doğrulaması yapılır; altı araç sunar: `whoami` (hesap ve kredi bilgisi), `eser_tescil` (RFC 3161 zaman damgası), `sozlesme_durumu` (sözleşme durumu ve imza takibi), `sablonlarim` (şablon listesi), `sablon_detay` (şablon detayı ve değişken kataloğu), `imzali_pdf_indir` (tamamlanmış sözleşmenin imzalı PDF'ini indirme). > **Not:** Bu paket varsayılan olarak İmzala üretim ortamına (`https://api-prd.imzala.org`) bağlanır. Farklı bir uç nokta için `IMZALA_API_BASE_URL` değişkenini ayarlayın. --- ## Kurulum ve Yapılandırma `npx @imzala/mcp-server` komutuyla kurulum gerektirmeden çalışır. Aşağıdaki JSON bloğunu ilgili araç yapılandırma dosyasına ekleyin: ### Claude Desktop `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) veya `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "imzala": { "command": "npx", "args": ["-y", "@imzala/mcp-server"], "env": { "IMZALA_API_KEY": "imz_..." } } } } ``` ### Claude Code (CLI) `.claude/settings.json` (proje) veya `~/.claude/settings.json` (global): ```json { "mcpServers": { "imzala": { "command": "npx", "args": ["-y", "@imzala/mcp-server"], "env": { "IMZALA_API_KEY": "imz_..." } } } } ``` ### Cursor `.cursor/mcp.json` (proje) veya `~/.cursor/mcp.json` (global): ```json { "mcpServers": { "imzala": { "command": "npx", "args": ["-y", "@imzala/mcp-server"], "env": { "IMZALA_API_KEY": "imz_..." } } } } ``` ### Ortam Değişkenleri | Değişken | Zorunlu | Açıklama | |----------|---------|----------| | `IMZALA_API_KEY` | Evet | `imz_` ile başlayan API anahtarı | | `IMZALA_API_BASE_URL` | Hayır | Varsayılan: `https://api-prd.imzala.org` (üretim). Test ortamı için `https://test-api.imzala.org` ayarlanabilir | --- ## API Anahtarı Nasıl Alınır 1. [app.imzala.org](https://app.imzala.org) adresinden hesabınıza giriş yapın. 2. Saga üstten **Hesap ayarları** bölümüne gidin. 3. **API Anahtarları** sekmesini açın ve **Yeni Anahtar** butonuna tıklayın. 4. Kapsam seçiminde, hangi araçları kullanacağınıza göre en dar (minimal) kombinasyonu işaretleyin. Bu MCP sunucusundaki araçların HEPSİ salt-okunurdur (hiçbiri sözleşme oluşturmaz ya da değiştirmez), bu yüzden **salt-okunur kapsam** vermeniz önerilir: `eser_tescil` ve `whoami` için `timestamps`; `sozlesme_durumu` ve `imzali_pdf_indir` için `demands:read`; `sablonlarim` ve `sablon_detay` için `templates:read`. Dashboard'da **"Yapay zeka asistanı için salt-okunur (önerilen)"** hazır seçeneği tam bu kombinasyonu (`timestamps` + `demands:read` + `templates:read`) tek tıkla seçer. Yazma yetkisi (`demands:write`) veren bir anahtar VERMEYİN, bu araçların hiçbiri buna ihtiyaç duymaz. (Eski, ayrımısız `demands`/`templates` kapsamlı anahtarlar da çalışır ama yazma yetkisi de içerdiğinden önerilmez.) 5. Oluşan anahtarı kopyalayın ve yukarıdaki yapılandırma dosyasına girin. --- ## Anahtar Güvenliği Bu API anahtarı hesabınıza erişim sağlar ve her zaman damgası işleminde **kredi harcar.** Aşağıdaki kurallara uyun: - Anahtarı bir parola gibi sayın; e-posta, Slack veya kaynak kod deposuna yapıştırmayın. - Anahtarı eklediğiniz AI aracının sağlayıcısı (Anthropic, Cursor vb.) yapılandırma dosyasını okuyabilir. Bu riski kabul edilebilir kılmak için **salt-okunur** bir anahtar kullanın (`timestamps` + `demands:read` + `templates:read`, dashboard'daki "Yapay zeka asistanı için salt-okunur" seçeneği); yazma yetkisi (`demands:write`) veren ya da tam yetkili anahtar **vermeyin**. Böylece anahtar sizse bile üçüncü taraf sözleşmelerinizi değiştiremez, yalnızca okuyabilir. - Anahtarınızın gizlendiğini düşünüyorsanız dashboard'daki **API Anahtarları** sayfasından hemen iptal edin ve yeni bir anahtar oluşturun. ### Veri akışı (önemli) Bu araçları kullandığınızda, sorguladığınız veri, protokolün doğası gereği kullandığınız AI aracının sağlayıcısının (Anthropic, Cursor vb.) altyapısından geçer ve onun veri işleme koşullarına tabi olur. Özellikle: - `sozlesme_durumu` sözleşmenizdeki **karşı tarafın adını, soyadını, e-postasını ve imza tarihini** çıktıda döndürür. - `imzali_pdf_indir` **tamamlanmış sözleşmenin tam içeriğini** (varsa TC kimlik, adres, finansal veri dahil) döndürür. Bu veri, dashboard'da zaten görebildiğiniz aynı bilgidir; **İmzala.org bu aktarımı yapmaz**, hangi AI aracını kullanacağınıza siz karar verirsiniz. Sözleşmenizin karşı tarafına ait verileri bu şekilde işlemeden önce kendi veri sorumlusu yükümlülüklerinizi değerlendirin. --- ## Araçlar ### `whoami` Hesap bilgilerini ve anlık kredi bakiyesini gösterir. **Girdi:** yok **Çıktı örneği:** ``` Hesap: Ahmet Yılmaz (ahmet@örnek.com) Kredi: 42 kalan Çalışma alanı: Kişisel ``` --- ### `eser_tescil` Bir dosyaya RFC 3161 zaman damgası uygular. Dosyanın belirtilen anda var olduğunu ve o andan bu yana değişmediğini kriptografik olarak kanıtlar. **Girdiler:** | Alan | Tip | Zorunlu | Açıklama | |------|-----|---------|----------| | `file_path` | `string` | XOR | Damgalanacak dosyanın yerel yolu | | `file_base64` | `string` | XOR | Dosya içeriği (standart canonical base64; data-URL veya URL-safe base64 kabul edilmez) | | `file_name` | `string` | Evet | Dosya adı, uzantı dahil (örn. `belge.pdf`) | | `owner_first_name` | `string` | Hayır | Eser sahibinin adı (beyan) | | `owner_last_name` | `string` | Hayır | Eser sahibinin soyadı (beyan) | | `description` | `string` | Hayır | Eser açıklaması | | `idempotency_key` | `string` | Hayır | Aynı isteği tekrarlamamak için benzersiz anahtar | `file_path` ve `file_base64` aynı anda kullanılmaz; birini verin. --- ### `sozlesme_durumu` Bir sözleşmenin durumunu ve hangi tarafların imzaladığını gösterir. "X sözleşmesini kim imzaladı, imzalandı mı" sorularını yanıtlar. **Girdiler:** | Alan | Tip | Zorunlu | Açıklama | |------|-----|---------|----------| | `demand_id` | `string` | Evet | Durumu sorgulanacak sözleşmenin (demand) kimliği | **Çıktı örneği:** ``` Sözleşme: Kira Sözleşmesi 2026 Durum: Bekliyor İmza durumu: 1/2 taraf imzaladı Taraflar: - Ahmet Yılmaz (ahmet@örnek.com): imzaladı (2026-06-30T10:15:00Z) - Mehmet Demir (mehmet@örnek.com): bekliyor, imza linki: https://e.imzala.org/imza/abc123 Sonuç sayfası: https://e.imzala.org/sonuc/xyz789 ``` --- ### `sablonlarim` Hesaptaki sözleşme şablonlarını listeler. **Girdiler:** | Alan | Tip | Zorunlu | Açıklama | |------|-----|---------|----------| | `page` | `number` | Hayır | Sayfa numarası (varsayılan 1) | | `limit` | `number` | Hayır | Sayfa boyutu (varsayılan 20, en fazla 100) | **Çıktı örneği:** ``` - Kira Sözleşmesi (konut kira sözleşmesi şablonu) [tpl_123], kategori: Kira, 2 taraf, 14 kez kullanıldı - Hizmet Sözleşmesi [tpl_456], 2 taraf, 3 kez kullanıldı Toplam: 2 (sayfa 1, sayfa boyutu 20) ``` --- ### `sablon_detay` Bir şablonun detayını gösterir: taraflar ve doldurulabilir değişkenler. Şablondan sözleşme oluşturmadan önce hangi değişkenlerin gerektiğini öğrenmek için kullanılır. **Girdiler:** | Alan | Tip | Zorunlu | Açıklama | |------|-----|---------|----------| | `template_id` | `string` | Evet | Detayı istenen şablonun kimliği | **Çıktı örneği:** ``` Şablon: Kira Sözleşmesi [tpl_123] Kategori: Kira Sayfa sayısı: 3 sayfa, 14 kez kullanıldı Taraflar: - Kiraya Veren (sıra 1), zorunlu - Kiracı (sıra 2), zorunlu Doldurulabilir değişkenler (sözleşme oluştururken kullanılır): - signer.full_name (İmzalayan Ad Soyad), tip: text, zorunlu - contract.start_date (Sözleşme Başlangıç Tarihi), tip: date, zorunlu, otomatik kaynak: current.date ``` --- ### `imzali_pdf_indir` Tamamlanmış bir sözleşmenin imzalı PDF'ini indirir. Sözleşmenin sahipliği önce doğrulanır; yalnız tamamlanmış (COMPLETED) sözleşmelerde çalışır. **Girdiler:** | Alan | Tip | Zorunlu | Açıklama | |------|-----|---------|----------| | `demand_id` | `string` | Evet | İmzalı PDF'i indirilecek tamamlanmış sözleşmenin kimliği | | `save_path` | `string` | Hayır | PDF'in kaydedileceği yerel dosya yolu (verilmezse base64 döner) | **Çıktı örneği (save_path verildiğinde):** ``` İmzalı PDF kaydedildi: /Users/ahmet/Downloads/kira-sozlesmesi.pdf (284213 bayt) ``` **Çıktı örneği (save_path verilmediğinde, dosya küçükse):** ``` İmzalı PDF (base64): JVBERi0xLjcKJ... ``` --- > **Not:** Bu MCP sunucusundaki dört sözleşme/şablon aracı (`sozlesme_durumu`, `imzali_pdf_indir`, `sablonlarim`, `sablon_detay`) yalnızca **okuma** kapsamı gerektirir: `sozlesme_durumu` + `imzali_pdf_indir` için `demands:read`, `sablonlarim` + `sablon_detay` için `templates:read`. Bu salt-okunur kapsamlar sözleşme oluşturma veya değiştirme yetkisi VERMEZ, dolayısıyla bir yapay zeka asistanına vermek için en güvenli seçimdir. Dashboard'daki "Yapay zeka asistanı için salt-okunur (önerilen)" hazır seçeneği bu kombinasyonu tek tıkla seçer. --- ## Zaman Damgası Hakkında Hukuki Not `eser_tescil` RFC 3161 standardında bir zaman damgasıdır. Dosyanın belirtilen anda var olduğunu ve değişmediğini ispat eder. Bu işlem: - Dijital veya elektronik imza değildir. - Nitelikli elektronik imza (QES) değildir. - Resmi eser sahipliği veya telif hakkı tescili değildir. Belirli bir hukuki amaç için kullanmadan önce bağımsız hukuki danışma alın. --- ## Geliştirici Notu: Yayınlama ### Zorunlu yayın-öncesi e2e gate `prepublishOnly` her `npm publish` öncesi sunucu çalıştırır: **build + unit test + e2e gate**. E2E gate (`scripts/e2e-preflight.mjs`) yayınlanacak sunucunun ta kendisini (`dist/bin/stdio.js`) stdio üzerinden **gerçek bir API anahtarı ile gerçek backend'e** karşı sürer ve her aracın gerçek çıktısını doğrular. Bir araç bozuksa (örneğin v1.0.0'da `eser_tescil` her yüklemede 500 veriyordu) publish **iptal** edilir. Yayınlamadan önce gerçek bir anahtar export edin: ```bash export IMZALA_E2E_API_KEY=imz_... # timestamps + templates + demands kapsamlı export IMZALA_E2E_BASE_URL=https://test-api.imzala.org # isteğe bağlı — prod kredisi harcamamak için test ortamı # isteğe bağlı, sözleşme araçlarını da test etmek için: export IMZALA_E2E_DEMAND_ID=<demand-id> export IMZALA_E2E_COMPLETED_DEMAND_ID=<tamamlanmis-demand-id> npm publish --tag next # prepublishOnly → build + test + e2e otomatik koşar ``` Gate'i tek başına çalıştırmak: `npm run e2e`. `eser_tescil` gerçek zaman damgası oluşturur (~4 kredi); atlamak için `IMZALA_E2E_SKIP_TIMESTAMP=1`. Acil durum bypass (yayın DOĞRULANMADAN çıkar): `IMZALA_E2E_SKIP=1`. ### Release akışı ```bash # Ön-sürüm olarak yayınla (e2e gate otomatik koşar) npm publish --tag next # Yeterli soak sonrası stable'a yükselt npm dist-tag add @imzala/mcp-server@<v> latest ``` Bu komutları yalnızca npm tokeni olan yetkili kullanıcı çalıştırır. MCP server kodu bu işlemi yapmaz.