内容
# satelia-mcp-freshdesk
一个用于 Freshdesk 的 MCP 服务器：获取工单，读取详情，添加备注，管理状态和标签。
## 前置条件
- Node.js 版本 18 或以上。验证方法：打开终端，输入 `node --version`
- 如果 Node.js 未安装，请从官方网站下载：https://nodejs.org（选择“LTS”版本）。
## 安装
1. 克隆仓库并安装依赖：
```bash
git clone <仓库地址>
cd satelia-mcp-freshdesk
npm install
npm run build
```
会出现一个 `build` 目录，其中包含 `build/index.js` 文件，Claude 将使用该文件。
## 配置（Freshdesk）
该服务器需要两个环境变量，定义在 Claude Desktop 配置文件（`claude_desktop_config.json`）中，位于服务器的 `env` 块中 - **绝不能在代码中**：
```json
{
"mcpServers": {
"freshdesk": {
"command": "node",
"args": ["/绝对路径/到/build/index.js"],
"env": {
"FRESHDESK_DOMAIN": "satelia",
"FRESHDESK_API_KEY": "您的 API 密钥"
}
}
}
}
```
- `FRESHDESK_DOMAIN`：子域名（例如，`satelia` 表示 `satelia.freshdesk.com`）。
- `FRESHDESK_API_KEY`：Freshdesk → *个人资料设置 → 查看 API 密钥*。
⚠️ **安全**：Freshdesk API 密钥可访问所有支持信息。绝不能分享（不要通过电子邮件、聊天或公共仓库分享）。在生产环境之前，**重新生成一个新的密钥**（*个人资料设置 → 查看 API 密钥 → 重置*），特别是如果当前密钥已经分享过。
修改后：运行 `npm run build` 然后重启 Claude Desktop。
## 可用工具
- `chercher-tickets` — 列出/搜索工单（邮箱客户端，状态，优先级，标签，日期）。
- `lire-ticket` — 详细查看工单（对话 + 自定义字段，包括患者代码）。
- `voir-contact` — 查看联系人信息（通过邮箱或 ID）。
- `ajouter-note` — 添加**私有**备注（草稿，绝不会发送给客户）。
- `changer-statut` — 修改状态：打开 / 待处理 / 已解决 / 已关闭。
- `gerer-tags` — 添加/移除标签。
## 现场测试（使用真实 Freshdesk）
在设置环境变量后，**从阅读开始**（⚠️ 患者数据：仅限少量工单）：
1. `FRESHDESK_DOMAIN=satelia FRESHDESK_API_KEY=... npm run dev`（启动服务器）。
2. 从 Claude：`chercher-tickets` 无过滤 → 验证是否有工单返回。
3. 对返回的 ID 运行 `lire-ticket` → 验证显示（对话，自定义字段）。
4. 在**测试工单**上：运行 `ajouter-note`，然后 `changer-statut`，然后 `gerer-tags`。
5. 在 Freshdesk 界面中验证备注确实是**私有**的。
## 许可证
MIT。查看 `LICENSE` 文件。
