Planningcenter Python

🚀 Planning Center Python

このライブラリは、Pydanticとasync/awaitパターンを使用した、Planning Center APIの包括的で最新のPythonラッパーです。People、Services、Check-Ins、Giving、Groups、Calendarなど、すべてのPlanning Center製品に対して型安全なアクセスを提供します。

🚀 主な機能

• 型安全：すべてのデータ構造に完全なPydanticモデルが用意されています。
• Async/await対応：httpxを使用した最新のPythonパターンをサポートしています。
• Webhook対応：組み込みの署名検証とイベントハンドリング機能を備えています。
• 全製品サポート：People、Services、Check-Ins、Giving、Groups、Calendarをサポートしています。
• 自動ページネーション：大規模なデータセットをシームレスに処理できます。
• レート制限：自動的な指数バックオフ機能付きです。
• 包括的なエラーハンドリング：特定の例外タイプを持つエラーハンドリングが行われます。
• CLIツール：一般的な操作を行うためのCLIツールが用意されています。
• ユーティリティ関数：データ処理と分析のためのユーティリティ関数があります。
• MCPサーバー：FastAPI-MCPを使用したAIアシスタントとの統合のためのMCPサーバーがあります。

📦 インストール

コアAPIパッケージ

# uvでインストール（推奨）
cd planning-center-api
uv pip install "planning_center_api@."

# またはpipでインストール
cd planning-center-api
pip install .

MCPサーバー（オプション）

AIアシスタントとの統合のために：

# MCPサーバーをインストール
cd planning-center-mcp-server
uv pip install "planning_center_mcp@."

# またはpipでインストール
cd planning-center-mcp-server
pip install .

🛠 クイックスタート

基本的な使用法

import asyncio
from planning_center_api import PCOClient, PCOProduct

async def main():
    async with PCOClient(app_id="your_app_id", secret="your_secret") as client:
        # メールアドレスを持つすべての人物を取得
        people = await client.get_people(include=["emails"])
        
        # 新しい人物を作成
        person = await client.create_person({
            "first_name": "John",
            "last_name": "Doe"
        })
        
        # すべてのサービスを自動ページネーションで取得
        async for service in client.paginate_all(
            product=PCOProduct.SERVICES,
            resource="services"
        ):
            print(f"Service: {service.attributes.get('title')}")

asyncio.run(main())

認証

このライブラリは、OAuth 2.0とパーソナルアクセストークンの両方の認証をサポートしています：

# OAuth 2.0（推奨）
client = PCOClient(access_token="your_oauth_token")

# パーソナルアクセストークン
client = PCOClient(app_id="your_app_id", secret="your_secret")

Webhookのハンドリング

from fastapi import FastAPI, Request
from planning_center_api import PCOClient, handle_webhook_event

app = FastAPI()
client = PCOClient(webhook_secret="your_secret")

@app.post("/webhook")
async def webhook_handler(request: Request):
    payload = await request.body()
    signature = request.headers.get("x-pco-signature")
    
    async def person_created(webhook_payload):
        print(f"New person: {webhook_payload.resource.attributes}")
    
    await handle_webhook_event(
        client=client,
        payload=payload.decode(),
        signature=signature,
        event_handlers={"people.created": person_created}
    )
    return {"status": "success"}

📚 ドキュメント

コアクライアント

PCOClient

Planning Center API操作のためのメインクライアントです。

async with PCOClient(
    app_id="your_app_id",
    secret="your_secret",
    access_token="your_token",  # app_id/secretの代わりに使用可能
    webhook_secret="your_webhook_secret"
) as client:
    # ここでクライアントを使用する

汎用CRUD操作

# リソースを取得
people = await client.get(PCOProduct.PEOPLE, "people")
person = await client.get(PCOProduct.PEOPLE, "people", "person_id")

# リソースを作成
new_person = await client.create(PCOProduct.PEOPLE, "people", {
    "first_name": "John",
    "last_name": "Doe"
})

# リソースを更新
updated_person = await client.update(
    PCOProduct.PEOPLE, "people", "person_id", {
        "phone": "555-123-4567"
    }
)

# リソースを削除
success = await client.delete(PCOProduct.PEOPLE, "people", "person_id")

ページネーション

# すべてのリソースを自動ページネーションで取得
async for person in client.paginate_all(
    product=PCOProduct.PEOPLE,
    resource="people",
    per_page=25
):
    print(person.get_full_name())

製品固有のメソッド

People

# 人物を取得
people = await client.get_people(per_page=50, include=["emails", "phone_numbers"])
person = await client.get_person("person_id", include=["emails"])

# 検索とフィルタリング
results = await client.search_people("john")
email_results = await client.get_people_by_email("john@example.com")
active_people = await client.get_active_people()

# 作成と更新
person = await client.create_person({
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
})
updated = await client.update_person("person_id", {"phone": "555-123-4567"})

Services

# サービスとプランを取得
services = await client.get_services(per_page=25)
service = await client.get_service("service_id")
plans = await client.get_plans(service_id="service_id")
plan = await client.get_plan("plan_id")

🖥 CLIの使用法

このライブラリには包括的なCLIツールが含まれています：

# 人物を取得
pco-cli get --product people --resource people --per-page 10

# 人物を検索
pco-cli search-people --query "john" --output table

# 人物を作成
pco-cli create --product people --resource people --data '{"first_name": "John", "last_name": "Doe"}'

# すべてのサービスをページネーションで取得
pco-cli paginate --product services --resource services --output csv

# メールアドレスで検索
pco-cli find-by-email --email "john@example.com"

🤖 AIアシスタント用のMCPサーバー

このリポジトリには、Claude、Cursor、その他のMCP互換クライアントなどのAIアシスタントに対して、すべての主要なPlanning Center APIをツールとして公開する包括的なModel Context Protocol (MCP) サーバーが含まれています。

🚀 主な機能

• 包括的なカバレッジ：9つのPlanning Center製品にまたがる65以上の読み取り専用ツールがあります。
• ネイティブMCP統合：AIアシスタントとのシームレスな統合のために、公式のMCPプロトコルを使用して構築されています。
• 読み取り専用操作：データの安全性のために読み取り専用操作のみをサポートしています。
• モックサーバー付き：API資格情報なしでテストできるモックサーバーが含まれています。
• Claude Desktop対応：事前に設定されたセットアップでClaude Desktopに対応しています。
• 高度なフィルタリングとページネーション：高度なフィルタリングとページネーションをサポートしています。
• イベント参加者フィルタリング：イベント管理を強化するためのイベント参加者フィルタリング機能があります。

📋 利用可能なMCPツール（65以上のツール）

People API (15ツール)

• get_people, get_person, get_person_addresses, get_person_emails, get_person_phones, get_person_background_checks, get_field_definitions, get_forms, get_form, get_campuses, get_campus

Services API (12ツール)

• get_services, get_service, get_plans, get_plan, get_songs, get_song, get_arrangements, get_arrangement, get_keys, get_key, get_teams, get_team, get_team_positions, get_team_position

Registrations API (5ツール)

• get_registrations, get_registration, get_attendees, get_attendee, get_event_attendees

Giving API (10ツール)

• get_donations, get_donation, get_funds, get_fund, get_batches, get_batch, get_pledges, get_pledge, get_pledge_campaigns, get_pledge_campaign, get_recurring_donations, get_recurring_donation

Groups API (8ツール)

• get_groups, get_group, get_group_events, get_group_event, get_group_memberships, get_group_membership, get_group_types, get_group_type

Calendar API (2ツール)

• get_calendar_events, get_calendar_event

Check-ins API (4ツール)

• get_check_in_events, get_check_in_event, get_locations, get_location

Publishing API (4ツール)

• get_channels, get_channel, get_episodes, get_episode

Webhooks API (2ツール)

• get_webhook_subscriptions, get_webhook_subscription

Organization API (4ツール)

• get_connected_applications, get_connected_application, get_oauth_applications, get_oauth_application

🚀 クイックスタート

オプション1: モックサーバー（資格情報不要）

テストと開発に最適です：

# MCPサーバーディレクトリに移動
cd planning-center-mcp-server

# モックサーバーを実行
uv run python mcp_mock_server_comprehensive.py

# またはバッチファイルを使用
run_comprehensive_server.bat

オプション2: 本番サーバー（API資格情報が必要）

実際のPlanning Centerデータを使用する本番環境での使用に適しています：

# 環境変数を設定
cp env.example .env
# .envを編集して、あなたのPlanning Center API資格情報を入力

# 本番サーバーを実行
uv run python mcp_server_fixed.py

# またはバッチファイルを使用
run_real_server.bat

🤖 Claude Desktopとの統合

このサーバーはClaude Desktopとの統合のために事前に設定されています：

1. Claude Desktopの設定を編集：%APPDATA%\Claude\claude_desktop_config.json
2. サーバー設定を追加（セットアップに従った場合は既に設定済み）
3. Claude Desktopを再起動
4. Planning Centerデータに関する質問を始める

Claude Desktopで利用可能なサーバー

• モックサーバー：planning-center-mock（資格情報不要）
• 本番サーバー：planning-center-api（API資格情報が必要）

💡 使用例

設定が完了すると、Claudeに以下のような質問をすることができます：

• "データベース内のすべてのアクティブな人物を表示して"
• "2024年のサマーキャンプの参加者を取得して"
• "先月のすべての寄付を検索して"
• "すべてのグループとそのメンバーをリストアップして"
• "今後のカレンダーイベントを表示して"

🎭 モックサーバーの機能

• 14以上のツール：最も一般的に使用されるエンドポイントをカバーしています。
• リアルな偽データ：エンティティ間の適切な関係を持つリアルな偽データが生成されます。
• 認証不要：テストのために認証は必要ありません。
• 本番サーバーと同じAPI構造：本番サーバーと同じAPI構造を持っています。
• MCP統合：AIアシスタントのテストのためのMCP統合が行われています。

詳細なMCPサーバーのドキュメントについては、planning-center-mcp-server/README.mdを参照してください。

CLIの設定

環境変数を設定するか、設定ファイルを使用します：

export PCO_APP_ID="your_app_id"
export PCO_SECRET="your_secret"
# または
export PCO_ACCESS_TOKEN="your_token"

または、config.jsonファイルを作成します：

{
    "app_id": "your_app_id",
    "secret": "your_secret",
    "timeout": 30.0,
    "max_retries": 3
}

🚨 エラーハンドリング

このライブラリは、さまざまなエラーシナリオに対して特定の例外タイプを提供します：

from planning_center_api.exceptions import (
    PCOError,
    PCOAuthenticationError,
    PCOPermissionError,
    PCONotFoundError,
    PCOValidationError,
    PCORateLimitError,
    PCOServerError
)

try:
    person = await client.get_person("invalid_id")
except PCONotFoundError:
    print("Person not found")
except PCOAuthenticationError:
    print("Authentication failed")
except PCORateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after}")
except PCOError as e:
    print(f"API error: {e.message}")

📊 データモデル

すべてのデータは型安全なPydanticモデルとして返されます：

# リソースモデル
person = await client.get_person("person_id")
print(person.get_first_name())  # 型安全なアクセス
print(person.get_email())
print(person.get_full_name())

# コレクションモデル
people = await client.get_people()
print(len(people))  # コレクションの長さ
for person in people:  # 反復可能
    print(person.get_full_name())

# 関連するリソースにアクセス
person = await client.get_person("person_id", include=["emails"])
emails = person.get_relationship_data("emails")

🔄 レート制限

このライブラリは、指数バックオフを使用して自動的にレート制限を処理します：

# レート制限は自動的に処理されます
# PCOConfigで設定することができます
config = PCOConfig(
    rate_limit_requests=100,  # ウィンドウごとのリクエスト数
    rate_limit_window=60,     # ウィンドウの秒数
    max_retries=3,            # 最大リトライ回数
    backoff_factor=2.0        # 指数バックオフ係数
)

🧪 テスト

# テストを実行
cd planning-center-api
pytest

# カバレッジを含めて実行
pytest --cov=planning_center_api

# 特定のテストファイルを実行
pytest tests/test_client.py

📝 サンプル

包括的なサンプルについては、planning-center-api/examples/ディレクトリを確認してください：

• basic_usage.py - 基本的なAPI操作
• webhook_server.py - FastAPIのWebhookサーバー
• data_export.py - データエクスポートと分析
• advanced_usage.py - 高度なパターンとユーティリティ

🛠 開発

セットアップ

# リポジトリをクローン
git clone <repository-url>
cd planningcenter-wrapper

# 開発用依存関係をインストール
cd planning-center-api
uv sync --group dev

# リンティングを実行
uv run ruff check --fix planning_center_api/

# テストを実行
uv run pytest

プロジェクト構造

planningcenter-wrapper/
├── planning-center-api/          # コアAPIパッケージ
│   ├── planning_center_api/      # ソースコード
│   ├── examples/                 # 使用例
│   ├── tests/                    # テストスイート
│   ├── docs/                     # ドキュメント
│   └── pyproject.toml           # パッケージ構成
├── planning-center-mcp-server/   # AIアシスタント用の包括的なMCPサーバー
│   ├── planning_center_mcp/      # MCPサーバーのソースコード
│   ├── mcp_server_fixed.py      # 65以上のツールを持つ本番サーバー
│   ├── mcp_mock_server_comprehensive.py  # テスト用のモックサーバー
│   ├── run_real_server.bat      # 本番サーバー用のバッチファイル
│   ├── run_comprehensive_server.bat  # モックサーバー用のバッチファイル
│   ├── README.md                 # 包括的なMCPサーバーのドキュメント
│   ├── COMPREHENSIVE_API_COVERAGE.md  # 完全なAPIカバレッジのドキュメント
│   ├── CLAUDE_DESKTOP_SETUP.md  # Claude Desktopのセットアップガイド
│   ├── QUICKSTART.md            # クイックスタートガイド
│   └── pyproject.toml           # MCPサーバーの構成
├── _apis/                        # APIドキュメント
└── README.md                     # このファイル

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. テストを追加します。
5. プルリクエストを送信します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🆘 サポート

• サンプルディレクトリを確認してください。
• APIドキュメントを確認してください。
• MCPサーバーのドキュメント：
  • 包括的なMCPサーバーのREADME
  • 完全なAPIカバレッジガイド
  • Claude Desktopのセットアップガイド
  • クイックスタートガイド
• バグや機能要求については、イシューを開いてください。

🔗 リンク

• Planning Center APIドキュメント
• Pydanticドキュメント
• httpxドキュメント
• FastAPI-MCPドキュメント