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文档