# Cendyn MCP 连接器

一个把 **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](https://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（部署到任意云 / 自己的服务器）
```bash
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：本地先试跑（验证密钥是否正确）
```bash
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 口令一致。