内容
# FirstReply MCP 服务器
MCP（[模型上下文协议](https://modelcontextprotocol.io)）服务器，暴露了 [FirstReply](https://firstreply.ai) 的客户支持操作，作为 [Claude](https://www.anthropic.com/claude) 等 AI 助手的工具。它允许助手浏览和回答客户对话，拉取支持统计数据，草拟 AI 回复，并管理组织 API 密钥 —— 所有这些都由 FirstReply REST API 进行范围和权限检查。
## 工具列表
### 组织与设置
| 工具 | 描述 |
|------|-------------|
| `organization_list` | 列出可访问的组织 |
| `inbox_list` | 列出组织的支持邮箱 |
| `member_list` | 列出组织成员 |
| `api_key_list` | 列出组织的命名 API 密钥（仅元数据） |
| `api_key_create` | 创建命名 API 密钥； plaintext 仅返回一次 |
| `api_key_delete` | 删除（吊销）API 密钥（破坏性） |
### 对话
| 工具 | 描述 |
|------|-------------|
| `conversation_list` | 列出/筛选客户对话 |
| `conversation_get` | 获取单个对话 |
| `conversation_messages` | 列出对话的消息 |
| `conversation_reply` | 向客户发送回复（破坏性） |
| `conversation_close` | 关闭对话 |
| `conversation_update` | 分配/重新优先/重新分类对话 |
| `conversation_stats` | 指定日期范围的对话统计 |
| `conversation_totals` | 当前开放/未读总数 |
### 人工智能
| 工具 | 描述 |
|------|-------------|
| `ai_draft_reply` | 生成 AI 回复草稿而不发送 |
## 要求
- Node.js >= 18
- FirstReply 组织 API 密钥
## 身份验证
服务器使用 **组织 API 密钥**（`fr_...`）通过 FirstReply REST API 进行身份验证，该密钥在 FirstReply 下的组织 → 开发 → API 密钥下创建。组织支持多个命名密钥（可选过期），因此最好为此 MCP 服务器创建一个专用密钥。密钥作为 `Authorization: Bearer` 发送。
API 密钥请求以组织所有者的权限运行 — 将密钥视为秘密，并通过创建新密钥和删除旧密钥来轮换它。
## 用法（stdio，例如 Claude Desktop）
```json
{
"mcpServers": {
"firstreply": {
"command": "npx",
"args": ["-y", "@firstreply/mcp"],
"env": {
"FIRSTREPLY_API_TOKEN": "fr_..."
}
}
}
}
```
### Claude 代码
```bash
claude mcp add firstreply --env FIRSTREPLY_API_TOKEN=fr_... -- npx -y @firstreply/mcp
```
## 用法（HTTP）
```bash
npm run build && npm run start:http # 监听 :8080
```
无状态可流式 HTTP 传输；每个请求都必须携带 `Authorization: Bearer fr_...`。提供了一个 `/health` 端点用于探测。
## 环境变量
| 变量 | 描述 |
|----------|-------------|
| `FIRSTREPLY_API_TOKEN` | 组织 API 密钥（stdio 模式） |
| `FIRSTREPLY_API_URL` | API 基 URL（默认 `https://api.firstreply.ai`） |
| `PORT` | HTTP 端口（HTTP 模式，默认 8080） |
| `MCP_ENDPOINT_PATH` | HTTP 端点路径（默认 `/`） |
## 开发
```bash
npm install
npm run typecheck
npm test # 构建并运行 node:test 套件
npm run build # 将 TypeScript 编译到 dist/
```
### 项目结构
```
src/
├── index.ts # stdio 入口点
├── http-server.ts # 流式 HTTP 入口点（Express）
├── server.ts # MCP 服务器连接
├── tools.ts # 工具定义和处理程序
└── client.ts # 最小 FirstReply REST 客户端
test/
└── tools.test.ts # 工具定义健全性检查
```
## 许可证
[MIT](LICENSE)
