fonzip

独立したオープンソースプロジェクトです。Fonzip Yazılım A.Ş. による開発、サポート、承認は受けていません。

Claude Code、Claude Desktop、Cursor、VS Code、Codex、およびMCPに対応するその他のクライアントから、Fonzip のデータに直接アクセスできます。

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 個のツールで、Fonzip API v2 の113 個の操作をカバーします
• ツール定義は OpenAPI spec から自動生成されるため、手動で同期する必要はありません
• OAuth2 client_credentials に対応し、プロセス間でトークンを保存します
• エラーメッセージはトルコ語です。呼び出しに不備がある場合は、期待されるスキーマがモデルに返されます

インストール

Node.js 20 以降が必要です。まず Fonzip の Ayarlar > Gelişmiş > Fonzip API メニューからAPI キーを作成します。client_id と client_secret が発行されます。

重要

Fonzip のキーは $2b$12$... で始まります。シェルでは単一引用符を使用してください。二重引用符または引用符なしで入力すると、シェルが $2b と $12 を変数とみなして削除するため、HTTP 403 が発生します。JSON ファイルではこの問題は起きません。

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

動作確認

クライアントに 「Fonzip アカウントの情報を表示して」 と尋ねてください。サーバーが fonzip_system / me を呼び出し、組織名を返せば正常です。

環境変数

¹ FONZIP_ACCESS_TOKEN が指定されていない場合は必須です。

ツール

Fonzip API v2には115個の操作があります。各操作を個別のツールにすると、クライアントのツール一覧が膨れ上がるため、操作はトピックごとに13個のツールにまとめられています。各ツールは必須のactionパラメーターを受け取ります。

/tokenと/authorizeエンドポイントはツールとして公開されません。認証はサーバー自体が処理します。

呼び出し例：

{
  "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"
  }
}

スキーマモード

full（デフォルト）モードでは、各ツールのすべてのパラメーターがJSON Schemaとしてクライアントに送信されます。13個のツールのスキーマは合計で約70 KB（約1万9千トークン）となり、モデルは1回のターンで適切な呼び出しを組み立てられます。

コンテキストの予算が限られている場合は、FONZIP_SCHEMA_MODE=compactを使用してください。スキーマはactionと自由形式のparamsオブジェクトのみになり、フィールド名はツールの説明にまとめられます。合計で約22 KB（約6千トークン）となり、fullモードの3分の1です。必須フィールドが不足している場合、エラーメッセージにそのactionの完全なスキーマが返されるため、モデルは自分で修正できます。

どちらのモードでも、フラット形式（{"action": "get", "user_id": 1}）とラップ形式（{"action": "get", "params": {"user_id": 1}}）の両方を受け付けます。

知っておくべきこと

Fonzipは同時に1つのトークンしか発行しません。 有効なトークンがある状態で/tokenを呼び出すと、HTTP 409 "Token already created"が返されます。MCPサーバーは頻繁に再起動されるため、トークンはデフォルトで~/.cache/fonzip-mcp/tokens.jsonに（0600の権限で、client idを記録せずに）保存され、再起動後も再利用されます。このキャッシュを無効にすると、サーバーの再起動後、最大1時間トークンを取得できない場合があります。

User-Agentは必須です。 Fonzipの前段にあるCloudflareは、User-AgentヘッダーのないリクエストをHTTP 403 (error code 1010)で拒否します。FONZIP_USER_AGENTを空のままにしないでください。

レート制限は1分あたり240リクエストです。 HTTP 429を受け取った場合は、Retry-Afterヘッダーに従って再試行します。

取引リストには日付範囲が必要です。 次のactionではstart_dateとend_dateが必須です。不足している場合、リクエストはFonzipに送信される前に拒否されます。

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

ページネーション（start_page、デフォルトは1）とページサイズ（how_many、デフォルトは10、最大100）を指定しない場合、デフォルト値が自動的に追加されます。同様に、fonzip_donations / listでは、statusのデフォルト値としてpaidが指定されます。

書き込み操作が有効です。 サーバーはすべてのCRUD操作を提供します。削除操作は元に戻せません。削除を含むツールにはMCPのdestructiveHintが設定されているため、クライアントが確認を求める場合があります。読み取り専用で使用する場合は、Fonzipで読み取り専用権限のAPIキーを作成してください。

個人データがモデルに送信されます。 Fonzipの応答には、氏名、メールアドレス、電話番号、トルコ共和国身分証番号、IBANが含まれる場合があります。これらはMCPクライアントおよび使用するモデルに転送されます。KVKKに基づく義務を考慮してください。詳細はSECURITY.mdを参照してください。

大きな応答は切り詰められます。 100,000文字を超える応答は切り詰められ、ページネーションが推奨されます。

開発

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

リポジトリには .mcp.json があります。npm run build の実行後、Claude Code はこのプロジェクトのサーバーをローカルの dist/ から起動します。シェルで FONZIP_CLIENT_ID と FONZIP_CLIENT_SECRET が定義されている必要があります。

ツールの定義は手作業では作成しません。scripts/generate.ts が openapi/fonzip-v2.yaml から src/generated/operations.ts を生成します。詳細とリリース手順については、CONTRIBUTING.md をご覧ください。

貢献

貢献を歓迎します。始める前に、CONTRIBUTING.md と CODE_OF_CONDUCT.md をご確認ください。セキュリティ上の脆弱性については、SECURITY.md をご覧ください。

ライセンス

このリポジトリ内のコードは MIT © Umut Baran Zorlu です。

openapi/fonzip-v2.yaml は Fonzip Yazılım A.Ş. 独自の API ドキュメントであり、MIT ライセンスの適用対象外です。リポジトリ内では、ツール定義の生成に使用する参照資料としてのみ含まれています。同じ例外は、仕様から生成された src/generated/operations.ts と公開される dist/ の内容にも適用されます。「Fonzip」という名称は、サーバーが接続するサービスを示す目的でのみ使用しています。詳細については、NOTICE をご覧ください。

API に関するお問い合わせ：[email protected]