Cendyn Connector

一个把 Cendyn CRM 接进 Claude 的"活链接"。部署一次之后，你在 Claude 里直接用中文提问，Claude 就能实时从 Cendyn 拉取宾客、消费、活动、受众等数据，做分析并给你决策建议。

• 数据只读（默认），不会误改你的 CRM。
• 你的 Cendyn 密钥只存在这台服务器上，不进入 Claude 的对话。
• 服务器可加一层 Bearer 口令，只有你的 Claude 能访问。

---

一、它能做什么（提供的工具）

工具	作用
cendyn_list_contacts	列出 / 搜索宾客（按邮箱、姓名、电话、user_id，可分页）
cendyn_get_contact	取单个宾客的完整档案
cendyn_list_purchases	消费 / 购买记录（做高价值、流失分析的关键）
cendyn_list_campaigns	列出营销活动（做效果复盘）
cendyn_list_audiences	列出受众 / 分群
cendyn_request	通用请求：调用任意端点（如预订 /hotel/、公司 /company/、优惠券 /coupon/）
cendyn_health	自检：显示配置的 base URL、账户、模式（不含密钥）

说明：Cendyn 把资源放在 /v2/account/{account_id}/... 下。上面几个是常用的专用工具；其余端点（含预订相关）用 cendyn_request 都能调到，路径以你账户开放的为准。

---

二、准备三样东西

1. Base URL：US 账户是 https://api.us.cendyncrm.com，EU 账户是 https://api.eu.cendyncrm.com。你是 US。
2. Account id：Cendyn 后台 → Api → API Keys → Account id。（你的是 688bc47f61f078000106df7e）
3. 密钥 Secret：同一页 → Show Secrets，复制某个 key 的 Secret。
   • 建议先点 Create New API Key 单独建一个给 Claude 用的 key，方便日后单独停用/轮换。
   • 优先用普通 Secret（权限小），非必要不用 Master secret。

---

三、部署（三选一）

方式 A：Render（最简单，有免费档，全程网页操作）

1. 把这个文件夹推到一个 GitHub 仓库。
2. 打开 render.com → New + → Blueprint → 选中该仓库（它会读取 render.yaml）。
3. 在 Environment 里填入密钥变量：CENDYN_ACCOUNT_ID、CENDYN_TOKEN、CONNECTOR_AUTH_TOKEN（随便设一个长随机串）。
4. 部署完成后得到一个公网地址，例如 https://cendyn-mcp.onrender.com。你的 MCP 地址就是它加 /mcp。

方式 B：Docker（部署到任意云 / 自己的服务器）

docker build -t cendyn-mcp .
docker run -p 8080:8080 \
  -e CENDYN_BASE_URL=https://api.us.cendyncrm.com \
  -e CENDYN_ACCOUNT_ID=688bc47f61f078000106df7e \
  -e CENDYN_TOKEN=你的Secret \
  -e CONNECTOR_AUTH_TOKEN=一个长随机串 \
  cendyn-mcp

方式 C：本地先试跑（验证密钥是否正确）

cp .env.example .env      # 然后编辑 .env 填入你的 Secret
npm install
npm run test:conn         # 应打印 ✅ Connected 和一条样本数据
npm start                 # 本地启动，地址 http://localhost:8080/mcp

本地地址 Claude 云端访问不到，仅用于验证。要给 Claude 用，需公网地址（方式 A/B），或用 ngrok 之类临时映射。

---

四、加到 Claude

1. 在 Claude（网页/桌面）打开 Settings → Connectors → Add custom connector。
2. URL 填你的 MCP 地址，如 https://cendyn-mcp.onrender.com/mcp。
3. 如果你设了 CONNECTOR_AUTH_TOKEN，在连接器的鉴权处填 Bearer 你的随机串（或按界面提示填该口令）。
4. 保存后开启该连接器。之后在对话里就能让 Claude 调用上面那些工具了。

自定义连接器功能与所在 Claude 套餐有关；若菜单里没有该入口，说明当前套餐暂不支持添加自定义连接器。

---

五、连上以后可以这样问

• "列出最近消费额最高的 20 位宾客，并说说他们的共同点。"
• "哪些高价值老客最近 6 个月没有再消费？该不该做召回、怎么做？"
• "把最近这次邮件活动的表现讲一下，下一步建议是什么？"
• "用 cendyn_request 调一下预订相关端点，看看这个周末的到店情况。"

Claude 会实时调用连接器取数，再给你带理由的分析和建议。

---

六、安全与边界

• 只读默认：CENDYN_ALLOW_WRITE=false。需要 Claude 触发营销/写回时才改为 true，并建议保留人工确认。
• 密钥保管：Secret 只放在服务器环境变量里，不要提交进 Git、不要贴进对话。
• 访问控制：务必设置 CONNECTOR_AUTH_TOKEN，否则任何知道你 URL 的人都能读你的数据。
• 合规：宾客数据涉及隐私（GDPR / 个人信息保护法），按最小必要原则使用。

---

七、排错

• test:conn 报 401/403：Secret 不对或该 key 未激活（Cendyn → API Keys 看 Active 是否 True）。
• 报 404：端点路径或区域 base URL 不对（US vs EU）。先用 cendyn_health 确认配置。
• Claude 加连接器失败：确认 URL 以 /mcp 结尾、服务器公网可达、Bearer 口令一致。