io.github.ubaranzorlu/fonzip
Dernek ve vakiflar icin Fonzip API v2 MCP sunucusu: bagis, uye, aidat ve etkinlik verileri.
Open source Open in the app JSON README (API)
About
Dernek ve vakiflar icin Fonzip API v2 MCP sunucusu: bagis, uye, aidat ve etkinlik verileri.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ubaranzorlu
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.2
- Last push
- 2026-08-30T19:16:13Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-30 19:01:02
- Updated
- 2026-08-30 19:01:02
- Origin id
io.github.ubaranzorlu/fonzip
README
<div align="center">
# fonzip-mcp
**[Fonzip](https://fonzip.com) API v2 için Model Context Protocol sunucusu**
Dernek ve vakıfların bağış, üye, aidat, etkinlik ve kampanya verilerine AI ajanlarından erişim.
[](https://www.npmjs.com/package/@ubaranzorlu/fonzip-mcp)
[](https://github.com/ubaranzorlu/fonzip-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://registry.modelcontextprotocol.io)
</div>
---
> 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.
<details open>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add fonzip \
-e FONZIP_CLIENT_ID='...' \
-e FONZIP_CLIENT_SECRET='...' \
-- npx -y @ubaranzorlu/fonzip-mcp
```
Sadece bulunduğunuz projeye ekler. Tüm projelerde kullanmak için `-s user`, ekiple paylaşmak için `-s project` ekleyin.
</details>
<details>
<summary><b>Claude Desktop</b></summary>
**Ayarlar > Developer > Edit Config** ile `claude_desktop_config.json` dosyasını açın:
```json
{
"mcpServers": {
"fonzip": {
"command": "npx",
"args": ["-y", "@ubaranzorlu/fonzip-mcp"],
"env": {
"FONZIP_CLIENT_ID": "...",
"FONZIP_CLIENT_SECRET": "..."
}
}
}
}
```
Claude Desktop'ı yeniden başlatın.
</details>
<details>
<summary><b>Cursor</b></summary>
`~/.cursor/mcp.json` (global) veya proje kökünde `.cursor/mcp.json`:
```json
{
"mcpServers": {
"fonzip": {
"command": "npx",
"args": ["-y", "@ubaranzorlu/fonzip-mcp"],
"env": {
"FONZIP_CLIENT_ID": "...",
"FONZIP_CLIENT_SECRET": "..."
}
}
}
}
```
</details>
<details>
<summary><b>VS Code / GitHub Copilot</b></summary>
```bash
code --add-mcp '{"name":"fonzip","command":"npx","args":["-y","@ubaranzorlu/fonzip-mcp"],"env":{"FONZIP_CLIENT_ID":"...","FONZIP_CLIENT_SECRET":"..."}}'
```
Ya da `.vscode/mcp.json` dosyasına yazıp anahtarları girdi olarak sorun:
```json
{
"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}"
}
}
}
}
```
</details>
<details>
<summary><b>Codex CLI</b></summary>
`~/.codex/config.toml`:
```toml
[mcp_servers.fonzip]
command = "npx"
args = ["-y", "@ubaranzorlu/fonzip-mcp"]
env = { FONZIP_CLIENT_ID = "...", FONZIP_CLIENT_SECRET = "..." }
```
</details>
<details>
<summary><b>Zed, Windsurf, Continue ve diğerleri</b></summary>
Standart stdio MCP sunucusudur. İstemcinizin yapılandırmasına şunu tanıtın:
```
komut: npx
argüman: -y @ubaranzorlu/fonzip-mcp
ortam: FONZIP_CLIENT_ID, FONZIP_CLIENT_SECRET
```
Sunucu [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.
</details>
### 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
| Değişken | Zorunlu | Varsayılan | Açıklama |
|---|---|---|---|
| `FONZIP_CLIENT_ID` | evet¹ | — | Fonzip API client id |
| `FONZIP_CLIENT_SECRET` | evet¹ | — | Fonzip API client secret |
| `FONZIP_ACCESS_TOKEN` | hayır | — | Hazır token. Verilirse `client_credentials` akışı atlanır |
| `FONZIP_BASE_URL` | hayır | `https://fonzip.com/api/v2` | API adresi |
| `FONZIP_SCHEMA_MODE` | hayır | `full` | `full` veya `compact` — [şema modu](#şema-modu) |
| `FONZIP_TOKEN_CACHE` | hayır | `~/.cache/fonzip-mcp/tokens.json` | Token önbelleği yolu. `off` ile kapatılır |
| `FONZIP_TIMEOUT_MS` | hayır | `30000` | İstek zaman aşımı |
| `FONZIP_MAX_RETRIES` | hayır | `3` | 429 ve 5xx için yeniden deneme sayısı |
| `FONZIP_USER_AGENT` | hayır | `fonzip-mcp/<sürüm>` | **Boş bırakmayın** — [neden](#bilinmesi-gerekenler) |
¹ `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.
| Tool | Action | Kapsam |
|---|:--:|---|
| `fonzip_system` | 5 | Kurum bilgisi (`me`), ödeme sistemleri, banka hesapları, pazarlama kanalları |
| `fonzip_users` | 18 | Üye/bağışçı kayıtları, zaman tüneli, etiketler, kişiye bağlı listeler |
| `fonzip_donations` | 14 | Bağışlar, bağış kategorileri, mikro bağışlar, bağış sayfaları ve formları |
| `fonzip_monthly_donations` | 5 | Düzenli bağış tutar/kart değişikliği ve iptal |
| `fonzip_membership_dues` | 9 | Aidat abonelikleri ve borçlar |
| `fonzip_events` | 12 | Etkinlikler, biletler, bilet satışları |
| `fonzip_fundraising` | 19 | Bağış kampanyaları, kampanya etkinlikleri, takımlar |
| `fonzip_forms` | 4 | Formlar ve form cevapları |
| `fonzip_ecards` | 9 | E-kartlar, kategoriler, satış işlemleri |
| `fonzip_tags` | 4 | Etiket yönetimi |
| `fonzip_templates` | 5 | Mesaj şablonları |
| `fonzip_webhooks` | 6 | Webhook yönetimi ve test bildirimi |
| `fonzip_communication_permissions` | 3 | E-posta/SMS/telefon izinleri |
`/token` ve `/authorize` uçları tool olarak sunulmaz; kimlik doğrulama sunucunun kendi işidir.
Örnek çağrı:
```json
{
"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](SECURITY.md).
**Büyük yanıtlar kırpılır.** 100.000 karakteri aşan yanıtlar kesilir ve sayfalama önerilir.
## Geliştirme
```bash
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](CONTRIBUTING.md).
## Katkı
Katkı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).
## Lisans
Bu depodaki kod [MIT](LICENSE) © 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](NOTICE).
API ile ilgili sorular için: help@fonzip.com