{
"markdown": "\n\n# fonzip-mcp\n\n**[Fonzip](https://fonzip.com) API v2 için Model Context Protocol sunucusu**\n\nDernek ve vakıfların bağış, üye, aidat, etkinlik ve kampanya verilerine AI ajanlarından erişim.\n\n[](https://www.npmjs.com/package/@ubaranzorlu/fonzip-mcp)\n[](https://github.com/ubaranzorlu/fonzip-mcp/actions/workflows/ci.yml)\n[](LICENSE)\n[](https://registry.modelcontextprotocol.io)\n\n
\n\n---\n\n> Bağımsız bir açık kaynak projesidir; Fonzip Yazılım A.Ş. tarafından geliştirilmemiş, desteklenmemekte ve onaylanmamaktadır.\n\nClaude Code, Claude Desktop, Cursor, VS Code, Codex ve MCP destekleyen diğer istemcilerin Fonzip verilerinize doğrudan erişmesini sağlar.\n\n```\nSen: Bu ay kaç düzenli bağışçı kaydolmuş, toplam ne kadar?\nAjan: [fonzip_donations / list çağrılır]\n Ağustos'ta 34 yeni düzenli bağışçı, aylık toplam 41.250 TL.\n```\n\n- **13 tool**, Fonzip API v2'nin **113 operasyonunu** kapsar\n- Tool tanımları OpenAPI spec'inden **otomatik üretilir** — elle senkron tutulmaz\n- OAuth2 `client_credentials`, token'ı süreçler arası saklama dahil\n- Türkçe hata mesajları; hatalı çağrıda beklenen şema modele geri döner\n\n## Kurulum\n\nNode.js 20 veya üstü gerekir. Önce Fonzip'te **Ayarlar > Gelişmiş > Fonzip API** menüsünden **API anahtarı oluşturun**; size bir `client_id` ve `client_secret` verilir.\n\n> [!IMPORTANT]\n> Fonzip anahtarları `$2b$12$...` ile başlar. Kabukta **tek tırnak** kullanın — çift tırnak veya tırnaksız yazarsanız kabuk `$2b` ve `$12` kısımlarını değişken sanıp siler ve `HTTP 403` alırsınız. JSON dosyalarında bu sorun yoktur.\n\n\nClaude Code
\n\n```bash\nclaude mcp add fonzip \\\n -e FONZIP_CLIENT_ID='...' \\\n -e FONZIP_CLIENT_SECRET='...' \\\n -- npx -y @ubaranzorlu/fonzip-mcp\n```\n\nSadece bulunduğunuz projeye ekler. Tüm projelerde kullanmak için `-s user`, ekiple paylaşmak için `-s project` ekleyin.\n\n \n\n\nClaude Desktop
\n\n**Ayarlar > Developer > Edit Config** ile `claude_desktop_config.json` dosyasını açın:\n\n```json\n{\n \"mcpServers\": {\n \"fonzip\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ubaranzorlu/fonzip-mcp\"],\n \"env\": {\n \"FONZIP_CLIENT_ID\": \"...\",\n \"FONZIP_CLIENT_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\nClaude Desktop'ı yeniden başlatın.\n\n \n\n\nCursor
\n\n`~/.cursor/mcp.json` (global) veya proje kökünde `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"fonzip\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ubaranzorlu/fonzip-mcp\"],\n \"env\": {\n \"FONZIP_CLIENT_ID\": \"...\",\n \"FONZIP_CLIENT_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n \n\n\nVS Code / GitHub Copilot
\n\n```bash\ncode --add-mcp '{\"name\":\"fonzip\",\"command\":\"npx\",\"args\":[\"-y\",\"@ubaranzorlu/fonzip-mcp\"],\"env\":{\"FONZIP_CLIENT_ID\":\"...\",\"FONZIP_CLIENT_SECRET\":\"...\"}}'\n```\n\nYa da `.vscode/mcp.json` dosyasına yazıp anahtarları girdi olarak sorun:\n\n```json\n{\n \"inputs\": [\n { \"type\": \"promptString\", \"id\": \"fonzip-id\", \"description\": \"Fonzip client id\", \"password\": true },\n { \"type\": \"promptString\", \"id\": \"fonzip-secret\", \"description\": \"Fonzip client secret\", \"password\": true }\n ],\n \"servers\": {\n \"fonzip\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ubaranzorlu/fonzip-mcp\"],\n \"env\": {\n \"FONZIP_CLIENT_ID\": \"${input:fonzip-id}\",\n \"FONZIP_CLIENT_SECRET\": \"${input:fonzip-secret}\"\n }\n }\n }\n}\n```\n\n \n\n\nCodex CLI
\n\n`~/.codex/config.toml`:\n\n```toml\n[mcp_servers.fonzip]\ncommand = \"npx\"\nargs = [\"-y\", \"@ubaranzorlu/fonzip-mcp\"]\nenv = { FONZIP_CLIENT_ID = \"...\", FONZIP_CLIENT_SECRET = \"...\" }\n```\n\n \n\n\nZed, Windsurf, Continue ve diğerleri
\n\nStandart stdio MCP sunucusudur. İstemcinizin yapılandırmasına şunu tanıtın:\n\n```\nkomut: npx\nargüman: -y @ubaranzorlu/fonzip-mcp\nortam: FONZIP_CLIENT_ID, FONZIP_CLIENT_SECRET\n```\n\nSunucu [MCP Registry](https://registry.modelcontextprotocol.io)'de `io.github.ubaranzorlu/fonzip` adıyla kayıtlıdır; registry'den kurulum destekleyen istemciler doğrudan bulabilir.\n\n \n\n### Doğrulama\n\nİstemcinize sorun: *\"Fonzip hesabımın bilgilerini göster\"* — sunucu `fonzip_system` / `me` çağrısıyla kurum adınızı döndürmeli.\n\n## Ortam değişkenleri\n\n| Değişken | Zorunlu | Varsayılan | Açıklama |\n|---|---|---|---|\n| `FONZIP_CLIENT_ID` | evet¹ | — | Fonzip API client id |\n| `FONZIP_CLIENT_SECRET` | evet¹ | — | Fonzip API client secret |\n| `FONZIP_ACCESS_TOKEN` | hayır | — | Hazır token. Verilirse `client_credentials` akışı atlanır |\n| `FONZIP_BASE_URL` | hayır | `https://fonzip.com/api/v2` | API adresi |\n| `FONZIP_SCHEMA_MODE` | hayır | `full` | `full` veya `compact` — [şema modu](#şema-modu) |\n| `FONZIP_TOKEN_CACHE` | hayır | `~/.cache/fonzip-mcp/tokens.json` | Token önbelleği yolu. `off` ile kapatılır |\n| `FONZIP_TIMEOUT_MS` | hayır | `30000` | İstek zaman aşımı |\n| `FONZIP_MAX_RETRIES` | hayır | `3` | 429 ve 5xx için yeniden deneme sayısı |\n| `FONZIP_USER_AGENT` | hayır | `fonzip-mcp/` | **Boş bırakmayın** — [neden](#bilinmesi-gerekenler) |\n\n¹ `FONZIP_ACCESS_TOKEN` verilmediyse zorunlu.\n\n## Tool'lar\n\nFonzip API v2'de 115 operasyon var. Her biri ayrı bir tool olsaydı istemcinin tool listesi şişerdi; bunun yerine operasyonlar konu başlığına göre 13 tool'da gruplandı. Her tool zorunlu bir `action` parametresi alır.\n\n| Tool | Action | Kapsam |\n|---|:--:|---|\n| `fonzip_system` | 5 | Kurum bilgisi (`me`), ödeme sistemleri, banka hesapları, pazarlama kanalları |\n| `fonzip_users` | 18 | Üye/bağışçı kayıtları, zaman tüneli, etiketler, kişiye bağlı listeler |\n| `fonzip_donations` | 14 | Bağışlar, bağış kategorileri, mikro bağışlar, bağış sayfaları ve formları |\n| `fonzip_monthly_donations` | 5 | Düzenli bağış tutar/kart değişikliği ve iptal |\n| `fonzip_membership_dues` | 9 | Aidat abonelikleri ve borçlar |\n| `fonzip_events` | 12 | Etkinlikler, biletler, bilet satışları |\n| `fonzip_fundraising` | 19 | Bağış kampanyaları, kampanya etkinlikleri, takımlar |\n| `fonzip_forms` | 4 | Formlar ve form cevapları |\n| `fonzip_ecards` | 9 | E-kartlar, kategoriler, satış işlemleri |\n| `fonzip_tags` | 4 | Etiket yönetimi |\n| `fonzip_templates` | 5 | Mesaj şablonları |\n| `fonzip_webhooks` | 6 | Webhook yönetimi ve test bildirimi |\n| `fonzip_communication_permissions` | 3 | E-posta/SMS/telefon izinleri |\n\n`/token` ve `/authorize` uçları tool olarak sunulmaz; kimlik doğrulama sunucunun kendi işidir.\n\nÖrnek çağrı:\n\n```json\n{\n \"name\": \"fonzip_donations\",\n \"arguments\": {\n \"action\": \"list\",\n \"status\": \"paid\",\n \"start_date\": \"2026-01-01T00:00:00+03:00\",\n \"end_date\": \"2026-01-31T23:59:59+03:00\"\n }\n}\n```\n\n### Şema modu\n\n`full` (varsayılan) modda her tool'un tüm parametreleri JSON Schema olarak istemciye gönderilir. 13 tool'un toplam şeması yaklaşık 70 KB (~19 bin token) tutar; model tek turda doğru çağrıyı kurabilir.\n\nBağlam bütçesi darsa `FONZIP_SCHEMA_MODE=compact` kullanın: şemalar yalnızca `action` ve serbest bir `params` objesine iner, alan adları ise tool açıklamasında özetlenir. Toplam yaklaşık 22 KB (~6 bin token), yani `full` modun üçte biri. Eksik alan gönderildiğinde hata mesajı o action'ın tam şemasını geri döndürür, böylece model kendini düzeltir.\n\nHer iki modda da hem düz (`{\"action\": \"get\", \"user_id\": 1}`) hem sarmalanmış (`{\"action\": \"get\", \"params\": {\"user_id\": 1}}`) biçim kabul edilir.\n\n## Bilinmesi gerekenler\n\n**Fonzip aynı anda tek token verir.** Geçerli bir token varken `/token` çağrısı `HTTP 409 \"Token already created\"` döner. MCP sunucuları sık yeniden başlatıldığından, token varsayılan olarak `~/.cache/fonzip-mcp/tokens.json` dosyasına (`0600` izniyle, client id yazılmadan) kaydedilir ve yeniden başlatmada tekrar kullanılır. Bu önbelleği kapatırsanız sunucu yeniden başladığında bir saate kadar token alamayabilir.\n\n**User-Agent zorunludur.** Fonzip'in önündeki Cloudflare, `User-Agent` başlığı olmayan istekleri `HTTP 403 (error code 1010)` ile reddeder. `FONZIP_USER_AGENT` değerini boş bırakmayın.\n\n**Hız sınırı dakikada 240 istektir.** `HTTP 429` alındığında `Retry-After` başlığına uyularak yeniden denenir.\n\n**İşlem listeleri tarih aralığı ister.** `start_date` ve `end_date` şu action'larda zorunludur; eksikse istek Fonzip'e gitmeden reddedilir:\n\n`fonzip_donations` → `list`, `list_micro`, `report` · `fonzip_membership_dues` → `list` · `fonzip_events` → `list_ticket_sales` · `fonzip_forms` → `list_answers` · `fonzip_ecards` → `list_transactions`\n\nSayfalama (`start_page`, varsayılan 1) ve sayfa boyutu (`how_many`, varsayılan 10, en fazla 100) göndermezseniz varsayılanları otomatik eklenir. Aynı şekilde `fonzip_donations` / `list` için `status` varsayılan olarak `paid` gider.\n\n**Yazma işlemleri açıktır.** Sunucu tüm CRUD operasyonlarını sunar; silme işlemleri geri alınamaz. Silme içeren tool'lar MCP `destructiveHint` ile işaretlenir, istemciniz bunlar için onay isteyebilir. Yalnızca okuma istiyorsanız Fonzip'te salt okunur yetkili bir API anahtarı oluşturun.\n\n**Kişisel veri modele gider.** Fonzip yanıtları ad, e-posta, telefon, TC kimlik no ve IBAN içerebilir; bunlar MCP istemcinize ve kullandığınız modele aktarılır. KVKK yükümlülükleriniz açısından değerlendirin. Ayrıntı için [SECURITY.md](SECURITY.md).\n\n**Büyük yanıtlar kırpılır.** 100.000 karakteri aşan yanıtlar kesilir ve sayfalama önerilir.\n\n## Geliştirme\n\n```bash\ngit clone https://github.com/ubaranzorlu/fonzip-mcp.git\ncd fonzip-mcp\nnpm install\nnpm test # 97 test\nnpm run build\n```\n\nDepoda `.mcp.json` var; `npm run build` sonrası Claude Code bu projede sunucuyu yerel `dist/` üzerinden çalıştırır. Kabuğunuzda `FONZIP_CLIENT_ID` ve `FONZIP_CLIENT_SECRET` tanımlı olmalıdır.\n\nTool tanımları elle yazılmaz — `scripts/generate.ts`, `openapi/fonzip-v2.yaml` dosyasından `src/generated/operations.ts` üretir. Ayrıntılar ve sürüm çıkarma adımları için [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Katkı\n\nKatkılar memnuniyetle karşılanır. Başlamadan önce [CONTRIBUTING.md](CONTRIBUTING.md) ve [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) dosyalarına göz atın. Güvenlik açıkları için [SECURITY.md](SECURITY.md).\n\n## Lisans\n\nBu depodaki kod [MIT](LICENSE) © Umut Baran Zorlu.\n\n`openapi/fonzip-v2.yaml` Fonzip Yazılım A.Ş.'nin kendi API dokümanıdır ve MIT kapsamı dışındadır; depoda yalnızca tool tanımlarının üretilmesi için referans olarak bulunur. Aynı istisna, spec'ten türeyen `src/generated/operations.ts` ve yayınlanan `dist/` içeriği için de geçerlidir. \"Fonzip\" adı yalnızca sunucunun hangi servise bağlandığını belirtmek için kullanılır. Ayrıntı: [NOTICE](NOTICE).\n\nAPI ile ilgili sorular için: help@fonzip.com\n",
"bytes": 10992,
"sha": "fef7541d28dcac816dbb0517cbe3c210e51a6b4761430fda1c4c9e5bbf0311de",
"repo_slug": "ubaranzorlu/fonzip-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_ubaranzorlu_fonzip_52450c4e/readme"
}