Planningcenter Python

🚀 Planning Center Python

這是一個全面且現代化的Python包裝器，用於與Planning Center API進行交互。它藉助Pydantic和異步/等待模式，為所有Planning Center產品（包括人員管理、服務安排、簽到系統、捐贈管理、群組活動和日程安排等）提供類型安全的訪問方式。

🚀 快速開始

基礎用法

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

✨ 主要特性

• 類型安全：為所有數據結構提供完整的Pydantic模型。
• 異步/等待支持：使用httpx庫，支持現代Python編程模式。
• 原生Webhook：內置簽名驗證和事件處理功能。
• 全產品支持：涵蓋人員管理、服務安排、簽到系統、捐贈管理、群組活動和日程安排等所有Planning Center產品。
• 自動分頁：無縫處理大型數據集。
• 速率限制：具備自動指數退避機制。
• 全面的錯誤處理：提供特定的異常類型。
• CLI工具：用於常見操作。
• 實用函數：用於數據處理和分析。
• MCP服務器：使用FastAPI - MCP實現AI助手集成。

📦 安裝指南

核心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())

高級用法

# 示例代碼用於展示更復雜的操作
# 例如，結合多個API調用和數據處理
import asyncio
from planning_center_api import PCOClient, PCOProduct

async def advanced_usage():
    async with PCOClient(app_id="your_app_id", secret="your_secret") as client:
        # 獲取人員數據
        people = await client.get_people(include=["emails"])
        # 對人員數據進行篩選和處理
        active_people = [p for p in people if p.attributes.get('active')]
        for person in active_people:
            print(f"Active person: {person.attributes.get('first_name')} {person.attributes.get('last_name')}")

asyncio.run(advanced_usage())

📚 詳細文檔

核心客戶端

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 = 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 = 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服務器

該倉庫包含一個全面的模型上下文協議（MCP）服務器，它將所有主要的Planning Center API作為工具暴露給像Claude、Cursor等MCP兼容的AI助手客戶端。

特性

• 全面覆蓋：涵蓋9個Planning Center產品的65 + 只讀工具。
• 原生MCP集成：使用官方MCP協議構建，實現與AI助手的無縫集成。
• 只讀操作：確保數據安全。
• 包含模擬服務器：無需API憑證即可進行測試。
• 支持Claude桌面版：預配置設置。
• 高級過濾和分頁支持。
• 活動參與者過濾：增強活動管理功能。

可用的MCP工具（65 + 工具）

人員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

服務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

註冊API（5個工具）

• get_registrations、get_registration、get_attendees、get_attendee、get_event_attendees

捐贈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

群組API（8個工具）

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

日曆API（2個工具）

• get_calendar_events、get_calendar_event

簽到API（4個工具）

• get_check_in_events、get_check_in_event、get_locations、get_location

發佈API（4個工具）

• get_channels、get_channel、get_episodes、get_episode

Webhook API（2個工具）

• get_webhook_subscriptions、get_webhook_subscription

組織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桌面版集成

服務器已預配置，可與Claude桌面版集成：

1. 編輯Claude桌面版配置文件：%APPDATA%\Claude\claude_desktop_config.json
2. 添加服務器配置（如果按照設置步驟操作，此步驟已完成）
3. 重啟Claude桌面版
4. 開始詢問關於Planning Center數據的問題

Claude桌面版可用選項

• 模擬服務器：planning-center-mock（無需憑證）
• 真實服務器：planning-center-api（需要API憑證）

使用示例

配置完成後，你可以向Claude詢問以下問題：

• "顯示我們數據庫中所有活躍人員"
• "獲取2024年夏令營的參與者"
• "查找上個月的所有捐贈記錄"
• "列出所有群組及其成員"
• "顯示即將到來的日曆事件"

模擬服務器特性

• 14 + 工具：涵蓋最常用的端點。
• 逼真的模擬數據：實體之間具有正確的關係。
• 無需身份驗證：便於測試。
• 與真實服務器相同的API結構。
• 支持MCP集成：用於AI助手測試。

詳細的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("人員未找到")
except PCOAuthenticationError:
    print("身份驗證失敗")
except PCORateLimitError as e:
    print(f"速率受限。請在 {e.retry_after} 後重試")
except PCOError as e:
    print(f"API錯誤: {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桌面版設置指南
│   ├── QUICKSTART.md            # 快速開始指南
│   └── pyproject.toml           # MCP服務器配置
├── _apis/                        # API文檔
└── README.md                     # 本文件

🤝 貢獻

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 添加測試
5. 提交拉取請求

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE 文件。

🆘 支持

• 查看 示例 目錄。
• 查閱 API文檔。
• MCP服務器文檔：
  • 全面的MCP服務器README
  • 完整的API覆蓋指南
  • Claude桌面版設置指南
  • 快速開始指南
• 如有Bug或功能請求，請提交問題。

🔗 鏈接

• Planning Center API文檔
• Pydantic文檔
• httpx文檔
• FastAPI - MCP文檔