内容
# KallyAI MCP 服务器
KallyAI API 的 MCP（模型上下文协议）服务器 - 一款代表您拨打电话的 AI 语音助手。
## 概述
此 MCP 服务器使 LLM 代理能够与 KallyAI API 交互，以：
- 进行 AI 电话预约餐厅、医疗预约、酒店预订和一般查询
- 检索通话历史和详细信息
- 获取通话记录
- 检查订阅状态和使用情况统计
## 功能
### 工具
1. **创建 AI 电话预约** - 进行 AI 电话预约
- 餐厅预约
- 医疗预约
- 酒店预订
- 一般查询
2. **列出通话历史** - 列出通话历史，支持分页
3. **获取通话详情** - 获取通话详细信息
4. **获取通话记录** - 检索通话记录
5. **检查订阅状态** - 检查订阅状态
6. **获取使用情况统计** - 获取使用情况和配额信息
## 快速入门
### 步骤 1：身份验证（一次性）
```bash
npx kallyai-mcp-server --setup
```
按照提示在 https://kallyai.com/app 登录
### 步骤 2：在 Claude Desktop 中安装
将以下内容添加到您的 Claude Desktop 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS）：
```json
{
"mcpServers": {
"kallyai": {
"command": "npx",
"args": ["-y", "kallyai-mcp-server"]
}
}
}
```
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
### 步骤 3：重启 Claude Desktop
完成！试试看："打电话预约餐厅"
## 验证
测试服务器：
```bash
npx kallyai-mcp-server
# 应启动成功且无错误
```
检查身份验证：
```bash
# 验证令牌文件是否存在
ls -la ~/.kallyai_token.json
```
## 故障排除
### "身份验证失败" 或 "未找到令牌"
- 运行 `npx kallyai-mcp-server --setup` 重新身份验证
- 确保您已在 https://kallyai.com/app 完成登录流程
### "找不到命令：npx"
- 从 https://nodejs.org 安装 Node.js（版本 18 或更高）
- 安装后重启终端
### "服务器未显示在 Claude Desktop 中"
- 检查您的配置文件路径是否正确（针对您的操作系统）
- 验证 JSON 语法是否有效（无尾随逗号）
- 完全重启 Claude Desktop（退出并重新打开）
### "quota_exceeded" 错误
- 您已用完所有可用分钟
- 在 https://kallyai.com/app/settings 升级您的计划
## 身份验证
MCP 服务器使用自动令牌管理：
1. **自动令牌管理**：从 `~/.kallyai_token.json` 读取令牌
2. **自动刷新**：自动刷新过期令牌
3. **无需手动传递令牌**：用户无需在工具参数中提供令牌
身份验证令牌存储在 `~/.kallyai_token.json` 中，由所有 MCP 工具自动使用。
## 高级用法
### 作为 stdio 服务器（本地开发）
```bash
npm install
npm run build
npm start
```
### 作为 HTTP 服务器（远程）
```bash
npm install
npm run build
TRANSPORT=http PORT=3000 npm start
```
## 配置
环境变量：
- `TRANSPORT`: 设置为 `http` 以使用 HTTP 服务器，默认为 `stdio`
- `PORT`: HTTP 服务器端口（默认为 3000）
- `ALLOWED_ORIGINS`: 以逗号分隔的允许的 CORS 来源列表（适用于 HTTP 模式，默认为 `https://claude.ai,https://www.anthropic.com`）
### 安全功能（HTTP 模式）
在 HTTP 模式下运行服务器时，包括：
- **CORS 保护**：限制跨源请求到允许的域名
- **速率限制**：每 15 分钟每个 IP 地址 100 次请求
- **安全标头**：Helmet 中间件，包含 CSP 和 HSTS
- **请求大小限制**：最大有效载荷大小为 100kb
## 示例工具调用
### 预约餐厅
```json
{
"task_category": "restaurant",
"task_description": "预订 4 人 7 点的餐位",
"respondent_phone": "+14155551234",
"business_name": "意大利小酒馆",
"user_name": "约翰·史密斯",
"party_size": 4,
"appointment_date": "2026-01-28",
"appointment_time": "19:00",
"timezone": "America/New_York"
}
```
注意：无需 `access_token` 参数 - 身份验证是自动的！
### 预约医疗服务
```json
{
"task_category": "clinic",
"task_description": "预约牙科检查",
"respondent_phone": "+14155551234",
"user_name": "简·多",
"time_preference_text": "上午 11 点前",
"timezone": "America/New_York"
}
```
### 一般查询
```json
{
"task_category": "general",
"task_description": "询问他们是否有 iPhone 15 以及价格",
"respondent_phone": "+34900000000",
"business_name": "手机商店",
"call_language": "es",
"timezone": "Europe/Madrid"
}
```
**测试成功！** 查看 [TEST-RESULTS.md](TEST-RESULTS.md) 以获取验证信息。
## 响应格式
所有工具都支持两种响应格式：
- `markdown`（默认）：人类可读的格式化文本
- `json`：机器可读的结构化数据
## 错误处理
服务器为常见场景提供详细的错误信息：
- `quota_exceeded`：用户分钟数用完，需要升级
- `missing_phone_number`：无效的电话号码格式
- `emergency_number`：不能拨打紧急服务
- `country_restriction`：不支持的国家
- `call_not_found`：通话 ID 不存在
## 开发
```bash
# 安装依赖
npm install
# 开发模式，自动重新加载
npm run dev
# 构建
npm run build
# 清理构建产物
npm run clean
```
## API 参考
基准 URL：`https://api.kallyai.com/v1`
查看 [API 参考](https://api.kallyai.com/docs) 以获取完整文档。
## 支持的国家
- 美国
- 加拿大
- 英国
- 西班牙
- 大多数欧洲国家
## 支持的语言
- 英语 (`en`)
- 西班牙语 (`es`)
## 隐私政策
**完整隐私政策**：[PRIVACY.md](PRIVACY.md)
### 数据收集和使用
KallyAI MCP 服务器 **不收集或存储任何用户数据**。它作为一个直通服务运行：
- **身份验证**：OAuth2 令牌存储在本地 `~/.kallyai_token.json`（仅所有者权限）
- **无日志记录**：不记录通话历史和个人信息
- **无分析**：无遥测或使用情况跟踪
- **安全传输**：所有 API 请求都使用 HTTPS/TLS 加密
- **第三方服务**：请求转发到 KallyAI API（https://api.kallyai.com）- 查看 [KallyAI 隐私政策](https://kallyai.com/privacy-policy)
### 传输数据
当您使用此 MCP 服务器时，以下数据将发送到 KallyAI API：
- 您请求拨打的电话号码
- AI 助手的任务描述
- 通话设置（语言、时区等）
- 您的 OAuth2 身份验证令牌
### 数据保留
- **本地令牌**：存储直到手动删除 (`rm ~/.kallyai_token.json`)
- **通话数据**：由 KallyAI 根据其隐私政策保留
- **MCP 服务器**：会话之间不保留任何数据
### 用户权利
您有权：
- 通过 KallyAI API 工具访问您的数据
- 删除本地身份验证令牌
- 通过 KallyAI 仪表板撤销 API 访问权限
- 导出您的通话历史
### 联系方式
隐私问题：
- **此 MCP 服务器**：support@kallyintelligence.com
- **KallyAI 服务**：privacy@kallyintelligence.com
- **GitHub 问题**：https://github.com/Kally-Intelligence-Inc/kallyai-mcp-server/issues
## 许可证
MIT
## 支持
如有问题和疑问：
- API 文档：https://api.kallyai.com/docs
- 网站：https://kallyai.com
- 支持：support@kallyintelligence.com
- GitHub 问题：https://github.com/Kally-Intelligence-Inc/kallyai-mcp-server/issues
