Breeze Chms MCP Server

Breeze ChMS MCP服务器

模型上下文协议（MCP）服务器，提供对微风教堂管理系统API的访问。该服务器允许AI助手与Breeze ChMS数据进行交互，包括人员管理、事件、贡献、标签、表格、志愿者和家庭。

特性

人员管理

• 列出具有筛选选项的人员
• 获取详细的人员信息
• 添加新用户
• 更新人员信息
• 删除人员
• 管理配置文件字段

事件管理

• 列出日期范围内的事件
• 获取活动详细信息和时间表
• 创建新事件
• 删除事件实例
• 管理活动日历
• 处理活动出席和登记

标签和组织

• 列出所有标签和标签文件夹
• 创建新标签和文件夹
• 为人员分配/取消分配标签
• 使用标签层次结构进行组织

表单

• 列表表格（活动和存档）
• 获取表单字段定义
• 检索表单条目
• 删除表单条目

志愿者

• 列出活动志愿者
• 安排/不安排志愿者
• 管理志愿者角色

家

• 创建新家庭
• 添加/删除家庭成员
• 摧毁现有家庭

捐款/捐赠

• 添加贡献记录
• 支持多种支付方式
• 处理资金分配
• 批量捐款

活动日志

• 查看详细的活动日志
• 按操作类型、日期、用户筛选
• 轨道系统变更

安装

1. 克隆此存储库

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

配置

设置以下环境变量：

• BREEZE_SUBDOMAIN：您的Breeze子域名（例如，mychurch.breezechms.com的“mychurch”）
• BREEZE_API_KEY：您的Breeze API密钥（可从Breeze中的扩展>API页面获得）

获取API密钥

1. 登录您的Breeze ChMS帐户
2. 首选 扩展 > API
3. 复制API密钥
4. 从浏览器URL中注意您的子域

用法

运行服务器

# Development mode
npm run dev

# Production mode
npm run build && npm start

MCP客户端配置

将此服务器添加到MCP客户端配置中：

{
  "mcpServers": {
    "breeze-chms": {
      "command": "node",
      "args": ["path/to/breeze-chms-mcp-server/dist/index.js"],
      "env": {
        "BREEZE_SUBDOMAIN": "your-church-subdomain",
        "BREEZE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude桌面配置

对于Claude Desktop，请在配置文件中添加：

{
  "mcpServers": {
    "breeze-chms": {
      "command": "npx",
      "args": ["breeze-chms-mcp-server"],
      "env": {
        "BREEZE_SUBDOMAIN": "your-church-subdomain", 
        "BREEZE_API_KEY": "your-api-key-here"
      }
    }
  }
}

可用工具

人员管理

• list_people -列出具有可选过滤和分页功能的人员
• get_person -获取特定人员的详细信息
• add_person -将新用户添加到数据库
• update_person -更新现有人员信息
• delete_person -从数据库中删除人员
• list_profile_fields -获取所有配置文件字段部分和定义

标签管理

• list_tags -列出所有标签和标签文件夹
• add_tag -创建新标签
• add_tag_folder -创建新的标签文件夹
• assign_tag -为某人分配标签
• unassign_tag -从某人身上删除标签

事件管理

• list_events -列出日期范围内的事件
• get_event -获取特定事件实例的详细信息
• add_event -创建新事件
• delete_event_instance -删除特定事件实例
• list_calendars -列出所有活动日历

活动出席情况

• checkin_person -检查一个人是否参加活动
• get_event_attendance -获取活动的出席记录

表单

• list_forms -列出所有表格（活动或存档）
• list_form_fields -列出特定表单的字段
• list_form_entries -列出特定表单的条目

志愿者

• list_volunteers -列出活动实例的志愿者
• schedule_volunteer -为活动安排志愿者
• unschedule_volunteer -从活动中删除志愿者

家

• create_family -与指定人员创建新家庭
• destroy_family -摧毁一个现有的家庭
• add_to_family -将人添加到现有家庭
• remove_from_family -将人们从当前家庭中删除

捐赠/贡献

• add_contribution -添加捐款/捐赠记录

活动日志

• list_activity -列出带有筛选选项的活动日志条目

示例用法

列出人员

// List first 50 people with basic info
{
  "tool": "list_people",
  "arguments": {
    "details": 0,
    "limit": 50
  }
}

// List people with full details and filtering
{
  "tool": "list_people", 
  "arguments": {
    "details": 1,
    "filter_json": "{\"tag_contains\": \"volunteer\"}"
  }
}

添加新用户

{
  "tool": "add_person",
  "arguments": {
    "first": "John",
    "last": "Doe",
    "fields_json": "[{\"field_id\":\"email_primary\",\"field_type\":\"email\",\"response\":true,\"details\":{\"address\":\"john.doe@example.com\"}}]"
  }
}

让某人参与活动

{
  "tool": "checkin_person",
  "arguments": {
    "person_id": "12345678",
    "instance_id": "98765432",
    "direction": "in"
  }
}

添加贡献

{
  "tool": "add_contribution",
  "arguments": {
    "date": "2024-01-15",
    "person_json": "{\"name\":\"Jane Smith\",\"email\":\"jane@example.com\"}",
    "method": "Check",
    "amount": 100.00,
    "funds_json": "[{\"name\":\"General Fund\",\"amount\":75},{\"name\":\"Missions Fund\",\"amount\":25}]"
  }
}

分配标签

{
  "tool": "assign_tag",
  "arguments": {
    "person_id": "12345678",
    "tag_id": "567890"
  }
}

API费率限制

微风API的速率限制为 每分钟20个请求。服务器将自动处理此问题，但为了获得最佳性能，请考虑：

• 间隔API调用（请求之间等待约3.5秒）
• 尽可能使用批量操作
• 对频繁访问的数据实施缓存

错误处理

服务器为常见问题提供详细的错误消息：

• API凭据无效
• 缺少必要参数
• API请求频率超限
• 无效的人员/事件/标签ID
• 网络连接问题

字段类型和结构

在更新人员或使用自定义字段时，您需要了解Breeze的字段结构：

常见字段类型

• text -简单的文本输入
• textarea -多行文本
• radio -多选/下拉菜单（使用选项ID）
• checkbox -多项选择
• date -日期字段
• email -电子邮件地址
• phone -电话号码
• address -街道地址
• birthdate -出生日期
• family_role -家庭关系角色

字段JSON结构

// Text field
{
  "field_id": "123456789",
  "field_type": "text", 
  "response": "Sample text value"
}

// Email field
{
  "field_id": "987654321",
  "field_type": "email",
  "response": true,
  "details": {
    "address": "user@example.com"
  }
}

// Phone field
{
  "field_id": "456789123",
  "field_type": "phone",
  "response": true,
  "details": {
    "phone_mobile": "555-123-4567"
  }
}

故障排除

常见问题

1. 身份验证错误

- 验证您的API密钥是否正确 - 检查您的子域是否与您的Breeze URL匹配 - 确保您在Breeze中启用了API访问

1. 速率限制错误

- 降低请求频率 - 实现通话之间的延迟 - 在可用时使用批处理操作

1. 字段ID无效

- 使用 list_profile_fields 获取当前字段ID - 如果重新创建字段，字段ID可能会更改

1. 权限错误

- 验证您的Breeze用户是否具有适当的权限 - 某些操作需要管理员级别的访问权限

调试

通过设置环境变量启用调试日志记录：

DEBUG=breeze-chms-mcp-server

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

这是一种非正式的整合。有关Breeze ChMS支持，请访问 技术支持.breezechms.com.

对于此MCP服务器的问题，请打开GitHub问题。

更新日志

v1.0.0

• 初始版本
• 为人员、事件、标签、表格、志愿者、家庭提供完整的API覆盖范围
• 支持捐款和活动记录
• 全面的错误处理和验证