fonzip

Bağımsız bir açık kaynak projesidir; Fonzip Yazılım A.Ş. tarafından geliştirilmemiş, desteklenmemekte ve onaylanmamaktadır.

Claude Code, Claude Desktop, Cursor, VS Code, Codex ve MCP destekleyen diğer istemcilerin Fonzip verilerinize doğrudan erişmesini sağlar.

Sen:    Bu ay kaç düzenli bağışçı kaydolmuş, toplam ne kadar?
Ajan:   [fonzip_donations / list çağrılır]
        Ağustos'ta 34 yeni düzenli bağışçı, aylık toplam 41.250 TL.

• 13 tool, Fonzip API v2'nin 113 operasyonunu kapsar
• Tool tanımları OpenAPI spec'inden otomatik üretilir — elle senkron tutulmaz
• OAuth2 client_credentials, token'ı süreçler arası saklama dahil
• Türkçe hata mesajları; hatalı çağrıda beklenen şema modele geri döner

Kurulum

Node.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.

Important

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.

claude mcp add fonzip \
  -e FONZIP_CLIENT_ID='...' \
  -e FONZIP_CLIENT_SECRET='...' \
  -- npx -y @ubaranzorlu/fonzip-mcp

{
  "mcpServers": {
    "fonzip": {
      "command": "npx",
      "args": ["-y", "@ubaranzorlu/fonzip-mcp"],
      "env": {
        "FONZIP_CLIENT_ID": "...",
        "FONZIP_CLIENT_SECRET": "..."
      }
    }
  }
}

{
  "mcpServers": {
    "fonzip": {
      "command": "npx",
      "args": ["-y", "@ubaranzorlu/fonzip-mcp"],
      "env": {
        "FONZIP_CLIENT_ID": "...",
        "FONZIP_CLIENT_SECRET": "..."
      }
    }
  }
}

code --add-mcp '{"name":"fonzip","command":"npx","args":["-y","@ubaranzorlu/fonzip-mcp"],"env":{"FONZIP_CLIENT_ID":"...","FONZIP_CLIENT_SECRET":"..."}}'

{
  "inputs": [
    { "type": "promptString", "id": "fonzip-id", "description": "Fonzip client id", "password": true },
    { "type": "promptString", "id": "fonzip-secret", "description": "Fonzip client secret", "password": true }
  ],
  "servers": {
    "fonzip": {
      "command": "npx",
      "args": ["-y", "@ubaranzorlu/fonzip-mcp"],
      "env": {
        "FONZIP_CLIENT_ID": "${input:fonzip-id}",
        "FONZIP_CLIENT_SECRET": "${input:fonzip-secret}"
      }
    }
  }
}

[mcp_servers.fonzip]
command = "npx"
args = ["-y", "@ubaranzorlu/fonzip-mcp"]
env = { FONZIP_CLIENT_ID = "...", FONZIP_CLIENT_SECRET = "..." }

komut:    npx
argüman:  -y @ubaranzorlu/fonzip-mcp
ortam:    FONZIP_CLIENT_ID, FONZIP_CLIENT_SECRET

Doğrulama

İstemcinize sorun: "Fonzip hesabımın bilgilerini göster" — sunucu fonzip_system / me çağrısıyla kurum adınızı döndürmeli.

Ortam değişkenleri

¹ FONZIP_ACCESS_TOKEN verilmediyse zorunlu.

Tool'lar

Fonzip 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.

/token ve /authorize uçları tool olarak sunulmaz; kimlik doğrulama sunucunun kendi işidir.

Örnek çağrı:

{
  "name": "fonzip_donations",
  "arguments": {
    "action": "list",
    "status": "paid",
    "start_date": "2026-01-01T00:00:00+03:00",
    "end_date": "2026-01-31T23:59:59+03:00"
  }
}

Şema modu

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.

Bağ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.

Her iki modda da hem düz ({"action": "get", "user_id": 1}) hem sarmalanmış ({"action": "get", "params": {"user_id": 1}}) biçim kabul edilir.

Bilinmesi gerekenler

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.

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.

Hız sınırı dakikada 240 istektir. HTTP 429 alındığında Retry-After başlığına uyularak yeniden denenir.

İşlem listeleri tarih aralığı ister. start_date ve end_date şu action'larda zorunludur; eksikse istek Fonzip'e gitmeden reddedilir:

fonzip_donations → list, list_micro, report · fonzip_membership_dues → list · fonzip_events → list_ticket_sales · fonzip_forms → list_answers · fonzip_ecards → list_transactions

Sayfalama (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.

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.

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.

Büyük yanıtlar kırpılır. 100.000 karakteri aşan yanıtlar kesilir ve sayfalama önerilir.

Geliştirme

git clone https://github.com/ubaranzorlu/fonzip-mcp.git
cd fonzip-mcp
npm install
npm test        # 97 test
npm run build

Depoda .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.

Tool 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.

Katkı

Katkılar memnuniyetle karşılanır. Başlamadan önce CONTRIBUTING.md ve CODE_OF_CONDUCT.md dosyalarına göz atın. Güvenlik açıkları için SECURITY.md.

Lisans

Bu depodaki kod MIT © Umut Baran Zorlu.

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.

API ile ilgili sorular için: [email protected]