AI导哈

Wild Apricot API服务器

一个提供Wild Apricot API访问的MCP服务器，用于将Wild Apricot数据与Claude等MCP兼容的AI助手集成。

  • by kmcoleman
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 kmcoleman/WA_MCP

使用说明

野杏MCP服务器

一种MCP（模型上下文协议）服务器，提供对Wild Apricot API的访问。使用此功能将Wild Apricot数据与Claude和其他MCP兼容的AI助手集成。

⚠️ 重要警告

使用风险自负

此软件按原样提供。 并非所有功能都经过彻底测试尤其是 写/更新/删除操作.

在使用写操作之前：

  • 考虑跑步 只读模式 首先安全地探索您的数据
  • 如果可能的话，使用非关键数据或沙盒Wild Apricot帐户进行测试
  • 小心你的提示——人工智能助手可能会误解请求
  • 在确认任何写入操作之前，请先查看预览数据
  • 删除操作需要 双重确认 具有精确的文本匹配

作者不对您的Wild Apricot帐户的任何数据丢失、损坏或意外修改负责。

特性

  • 读取操作：查询联系人、事件、注册、会员级别、发票和帐户信息
  • 写入操作：创建和更新联系人、事件、注册和发票（可以禁用）
  • 删除操作：通过双重确认删除联系人和事件（额外安全）
  • 需要确认：所有写入操作在执行前都需要明确确认
  • 输入验证：暂存操作前的电子邮件、日期和字段验证
  • CSV导出：将联系人、事件和注册导出为CSV格式
  • 快捷操作：用于常见任务的简化工具（按姓名搜索、通过电子邮件登记等）
  • 只读模式：禁用所有突变以进行安全的数据探索
  • 速率限制：遵守Wild Apricot API限制的内置延迟

目录

设置

1.获取您的API证书

  1. 登录您的Wild Apricot管理面板
  2. 首选 设置 > 安全 > 授权申请
  3. 点击 授权申请
  4. 选择 服务器应用程序 （API密钥）
  5. 选择适当的访问级别：
    • 只读访问 -建议用于初始测试
    • 完全访问 -写入操作所需
  6. 复制 API密钥 生成
  7. 注意你的 帐户ID （在URL中可见： https://app.wildapricot.org/admin/XXXXXX/...)

2.安装

git clone https://github.com/yourusername/wildapricot-mcp.git
cd wildapricot-mcp
npm install
npm run build

3.配置

cp .env.example .env
# Edit .env with your credentials

4.添加到克劳德桌面

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "wildapricot": {
      "command": "node",
      "args": ["/full/path/to/wildapricot-mcp/dist/index.js"],
      "env": {
        "WILDAPRICOT_API_KEY": "your_api_key_here",
        "WILDAPRICOT_ACCOUNT_ID": "your_account_id_here",
        "WILDAPRICOT_READ_ONLY": "true"
      }
    }
  }
}

可用工具

读取操作（18个工具-始终可用）

帐户和联系人

工具 说明
get_account 获取账户详细信息（姓名、时区、货币、联系人数量）
list_contacts 使用OData筛选器列出/搜索联系人
get_contact 通过ID获取联系方式
get_contact_by_email 通过确切的电子邮件地址查找联系人
search_contacts_by_name 按名字/姓氏搜索（比过滤器更简单）
export_contacts_csv 将联系人导出为CSV格式

事件

工具 说明
list_events 使用日期过滤器列出事件
get_event 按ID获取事件
get_upcoming_events 获取未来N天内的事件（默认值：30）
get_event_attendees 在一次通话中获取活动+所有注册
export_events_csv 将事件导出为CSV格式

注册

工具 说明
list_event_registrations 列出活动的注册信息
get_registration 按ID注册
find_registration_by_email 通过与会者电子邮件查找注册信息
export_registrations_csv 将注册导出为CSV格式

其他

工具 说明
list_membership_levels 列出所有会员级别
list_invoices 列出带有过滤器的发票
get_invoice 按ID获取发票

写入操作（9个工具-READ_ONLY=true时禁用）

⚠️ 所有写入操作都需要确认。删除操作需要 双重确认.

工具 说明 确认
create_contact 创建新联系人 confirm_operation
update_contact 更新联系人字段 confirm_operation
delete_contact 永久删除联系人 confirm_delete +“删除”
create_event 创建新事件 confirm_operation
update_event 更新事件详细信息 confirm_operation
delete_event 删除事件和所有注册 confirm_delete +“删除”
update_registration 更新注册（登记、备忘录） confirm_operation
check_in_by_email 通过电子邮件查找和登记 confirm_operation
create_invoice 创建新发票 confirm_operation

确认工具（4个工具-READ_ONLY=true时禁用）

工具 说明
confirm_operation 执行待定的创建/更新操作
confirm_delete 执行挂起的删除操作（需要“delete”文本）
cancel_operation 取消挂起的操作
list_pending_operations 列出所有待处理的操作

确认工作流程

标准写入操作（创建/更新）

1. Call write tool (e.g., create_contact)
   → Returns: operationId + preview

2. Review the preview

3. Call confirm_operation(operationId)
   → Executes the operation

删除操作（双重确认）

删除操作具有额外的安全性：

1. Call delete tool with matching IDs
   delete_contact(contactId: 123, confirmContactId: 123)
   → Returns: operationId + preview

2. Review what will be deleted

3. Call confirm_delete(operationId, confirmText: "DELETE")
   → Must type "DELETE" exactly to proceed

示例：删除联系人

User: "Delete contact 12345"

AI calls: delete_contact(contactId: 12345, confirmContactId: 12345)

Response:
{
  "status": "PENDING_DOUBLE_CONFIRMATION",
  "operationId": "op_xxx",
  "warning": "THIS CANNOT BE UNDONE",
  "preview": {
    "action": "DELETE CONTACT",
    "contactId": 12345,
    "contactName": "John Smith",
    "contactEmail": "john@example.com"
  }
}

User: "Yes, delete it"

AI calls: confirm_delete(operationId: "op_xxx", confirmText: "DELETE")

Response:
{
  "success": true,
  "message": "⚠️ DELETED: DELETE contact: John Smith..."
}

示例提示

安全只读提示

"Show me account information"
"List all active members"
"Find John Smith"
"Get contact with email john@example.com"
"Show upcoming events for the next 2 weeks"
"Get all registrations for event 12345"
"Export all contacts to CSV"
"Export registrations for event 12345 to CSV"

写提示（需要确认）

"Create a contact for Jane Doe with email jane@example.com"
→ Review preview → "Confirm"

"Check in john@example.com for event 12345"
→ Review preview → "Yes, check them in"

"Update event 12345 location to 'Main Hall'"
→ Review preview → "Confirm the update"

删除提示（需要双重确认）

"Delete contact 12345"
→ Review what will be deleted
→ "Yes, permanently delete it"
→ AI must call confirm_delete with "DELETE"

提示避免

❌ "Update all contacts..." - Could stage many operations
❌ "Delete all old events..." - Very dangerous
❌ "Confirm all pending operations" - Review each one!
❌ "Clean up the database..." - Ambiguous and dangerous

配置选项

环境变量 必填 默认 描述
WILDAPRICOT_API_KEY 是 - 您的Wild Apricot API密钥
WILDAPRICOT_ACCOUNT_ID 是 - 您的野生杏账户ID
WILDAPRICOT_READ_ONLY 没有 false 设置为 true 禁用所有写入操作

发展

npm run dev    # Development mode with tsx
npm run build  # Build for production
npm start      # Start production server

项目结构

src/
├── index.ts              # MCP server entry point
├── config.ts             # Configuration loading
├── auth.ts               # OAuth token management
├── client.ts             # API client with rate limiting
├── validation.ts         # Input validation utilities
├── csv-export.ts         # CSV export utilities
├── pending-operations.ts # Confirmation system
└── tools/
    ├── index.ts          # Tool registration
    ├── account.ts        # Account tools
    ├── contacts.ts       # Contact tools (CRUD + search + export)
    ├── events.ts         # Event tools (CRUD + search + export)
    ├── registrations.ts  # Registration tools (RU + search + export)
    ├── memberships.ts    # Membership level tools
    └── invoices.ts       # Invoice tools (CR)

故障排除

常见错误

错误 解决方案
“WILDAPRICOT_API_KEY必需” 在配置中设置环境变量
“身份验证失败：401” 在WA管理中重新生成API密钥
“API错误：403” 检查API密钥权限
“API错误：429” 速率受限-等待并重试
“找不到操作” 已过期（5分钟限制）-再次执行阶段
“验证错误” 检查输入格式（电子邮件、日期、ID）

删除确认失败

  • 确保 confirmText 正是 "DELETE" （全部大写）
  • 确保 contactId/eventId 匹配确认参数
  • 检查操作未过期（5分钟限制）

API 参考

许可证

麻省理工学院

免责声明

本项目不隶属于野杏或Personify。野杏是Personify的商标。

本软件按“原样”提供，不提供任何形式的保修。 使用风险自负。

相关 MCP