使用说明

规划中心Python（或：Python规划中心）

一个全面且现代的Python包装器，用于Planning Center API，采用Pydantic和async/await模式。此库提供类型安全的访问所有Planning Center产品，包括人员、服务、签到、奉献、小组和日历。

🚀 功能特点

类型安全 为所有数据结构提供完整的 Pydantic 模型
Async/await 支持使用 httpx 以适应现代 Python 模式
原生Webhook 具有内置签名验证和事件处理功能
所有产品 支持的功能：人员、服务、签到、捐赠、群组、日历、发布、Webhooks（网络钩子）、组织
自动分页 为了无缝处理大型数据集
限速具有自动指数退避功能
全面的错误处理 带有特定的异常类型
命令行界面（CLI）工具 用于常见操作
实用函数 用于数据处理和分析
MCP 服务器 为AI助手集成80多种工具，包括高级分析功能

📦 安装

核心API包

# Install with uv (recommended)
cd planning-center-api
uv pip install "planning_center_api@."

# Or with pip
cd planning-center-api
pip install .

MCP 服务器（可选）

对于AI助手的集成：

# Install MCP server
cd planning-center-mcp-server
uv pip install "planning_center_mcp@."

# Or with 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:
        # Get all people with emails
        people = await client.get_people(include=["emails"])
        
        # Create new person
        person = await client.create_person({
            "first_name": "John",
            "last_name": "Doe"
        })
        
        # Auto-paginate through all services
        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和个人访问令牌（Personal Access Token）两种认证方式：

# OAuth 2.0 (recommended)
client = PCOClient(access_token="your_oauth_token")

# Personal Access 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"}

📚 API 参考手册

核心客户端

`PCOClient`

规划中心API操作的主要客户端。

async with PCOClient(
    app_id="your_app_id",
    secret="your_secret",
    access_token="your_token",  # Alternative to app_id/secret
    webhook_secret="your_webhook_secret"
) as client:
    # Use client here

通用的CRUD操作

# Get resources
people = await client.get(PCOProduct.PEOPLE, "people")
person = await client.get(PCOProduct.PEOPLE, "people", "person_id")

# Create resources
new_person = await client.create(PCOProduct.PEOPLE, "people", {
    "first_name": "John",
    "last_name": "Doe"
})

# Update resources
updated_person = await client.update(
    PCOProduct.PEOPLE, "people", "person_id", {
        "phone": "555-123-4567"
    }
)

# Delete resources
success = await client.delete(PCOProduct.PEOPLE, "people", "person_id")

分页

# Auto-paginate through all resources
async for person in client.paginate_all(
    product=PCOProduct.PEOPLE,
    resource="people",
    per_page=25
):
    print(person.get_full_name())

针对特定产品的方法

人们

# Get people
people = await client.get_people(per_page=50, include=["emails", "phone_numbers"])
person = await client.get_person("person_id", include=["emails"])

# Search and filter
results = await client.search_people("john")
email_results = await client.get_people_by_email("john@example.com")
active_people = await client.get_active_people()

# Create and update
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"})

服务

# Get services and plans
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）工具：

# Get people
pco-cli get --product people --resource people --per-page 10

# Search people
pco-cli search-people --query "john" --output table

# Create a person
pco-cli create --product people --resource people --data '{"first_name": "John", "last_name": "Doe"}'

# Paginate through all services
pco-cli paginate --product services --resource services --output csv

# Find by email
pco-cli find-by-email --email "john@example.com"

🤖 用于AI助手的MCP服务器

该存储库包含一个全面的模型上下文协议（MCP）服务器，该服务器提供了 所有主要的规划中心API 作为像Claude、Cursor以及其他MCP兼容客户端等AI助手的工具。

🚀 特点

全面覆盖9款规划中心产品中的80+款只读工具
原生MCP集成使用官方MCP协议构建，实现无缝集成AI助手
只读操作 为了数据安全
包含模拟服务器 用于测试，无需API凭据
Claude Desktop 已准备就绪 带有预配置设置
高级过滤 以及分页支持
高级分析10+款专业分析工具，助力数据驱动洞察
活动参与者筛选 用于增强活动管理

📋 可用的MCP工具（80+种工具）

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

Webhooks API （2个工具）

get_webhook_subscriptions， get_webhook_subscription

组织API （4个工具）

get_connected_applications， get_connected_application， get_oauth_applications， get_oauth_application

🚀 快速入门

选项1：模拟服务器（无需凭据）

非常适合测试和开发：

# Navigate to MCP server directory
cd planning-center-mcp-server

# Run the mock server
uv run python mcp_mock_server_comprehensive.py

# Or use the batch file
run_comprehensive_server.bat

选项2：真实服务器（需要API凭据）

用于生产环境并使用真实的规划中心数据：

# Set up environment variables
cp env.example .env
# Edit .env with your Planning Center API credentials

# Run the real server
uv run python mcp_server_fixed.py

# Or use the batch file
run_real_server.bat

Claude桌面集成

服务器已预先配置以集成Claude Desktop：

编辑您的Claude桌面配置： %APPDATA%\Claude\claude_desktop_config.json
添加服务器配置 （如果您已按照设置步骤操作，则此步骤已完成）
重启Claude桌面版
开始提问 关于规划中心的数据！

可在Claude Desktop上使用

模拟服务器： planning-center-mock （无需凭据）
真实服务器： planning-center-api （需要API凭证）

💡 使用示例

配置完成后，您可以向Claude提出以下问题：

“给我显示数据库中所有活跃的人员”
“招募2024年夏令营的参与者”
“查找上个月的所有捐赠”
“列出所有群组及其成员”
“显示即将发生的日历事件”

🎭 模拟服务器功能

14+种工具 涵盖最常用的终端节点
逼真的虚假数据 实体之间具有适当的关系
无需认证 用于测试
相同的API结构 作为真实服务器
MCP集成 用于AI助手测试

有关MCP服务器的详细文档，请参阅规划中心-MCP服务器/README.md。

CLI 配置

设置环境变量或使用配置文件：

export PCO_APP_ID="your_app_id"
export PCO_SECRET="your_secret"
# or
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 模型形式返回：

# Resource models
person = await client.get_person("person_id")
print(person.get_first_name())  # Type-safe access
print(person.get_email())
print(person.get_full_name())

# Collection models
people = await client.get_people()
print(len(people))  # Collection length
for person in people:  # Iterable
    print(person.get_full_name())

# Access included resources
person = await client.get_person("person_id", include=["emails"])
emails = person.get_relationship_data("emails")

🔄 流量限制

该库自动处理带有指数退避的速率限制：

# Rate limiting is handled automatically
# You can configure it in PCOConfig
config = PCOConfig(
    rate_limit_requests=100,  # Requests per window
    rate_limit_window=60,     # Window in seconds
    max_retries=3,            # Max retry attempts
    backoff_factor=2.0        # Exponential backoff factor
)

🧪 测试

# Run tests
cd planning-center-api
pytest

# Run with coverage
pytest --cov=planning_center_api

# Run specific test file
pytest tests/test_client.py

📝 示例

检查一下 planning-center-api/examples/ 包含综合示例的目录：

basic_usage.py - 基本API操作
webhook_server.py - FastAPI 网络钩子服务器
data_export.py - 数据导出与分析
advanced_usage.py - 高级图案和实用工具

🛠 开发

设置

# Clone the repository
git clone <repository-url>
cd planningcenter-wrapper

# Install development dependencies
cd planning-center-api
uv sync --group dev

# Run linting
uv run ruff check --fix planning_center_api/

# Run tests
uv run pytest

项目结构

planningcenter-wrapper/
├── planning-center-api/          # Core API package
│   ├── planning_center_api/      # Source code
│   ├── examples/                 # Usage examples
│   ├── tests/                    # Test suite
│   ├── docs/                     # Documentation
│   └── pyproject.toml           # Package configuration
├── planning-center-mcp-server/   # Comprehensive MCP server for AI assistants
│   ├── planning_center_mcp/      # MCP server source code
│   ├── mcp_server_fixed.py      # Real server with 65+ tools
│   ├── mcp_mock_server_comprehensive.py  # Mock server for testing
│   ├── run_real_server.bat      # Batch file for real server
│   ├── run_comprehensive_server.bat  # Batch file for mock server
│   ├── README.md                 # Comprehensive MCP server documentation
│   ├── COMPREHENSIVE_API_COVERAGE.md  # Complete API coverage documentation
│   ├── CLAUDE_DESKTOP_SETUP.md  # Claude Desktop setup guide
│   ├── QUICKSTART.md            # Quick start guide
│   └── pyproject.toml           # MCP server configuration
├── _apis/                        # API documentation
└── README.md                     # This file

🤝 贡献

为仓库创建分支
创建一个特性分支
进行你的更改
添加测试
提交拉取请求