内容
# VoIPBin MCP 服务器
# VoIPBin MCP 服务器
VoIPBin API 的模型上下文协议（MCP）服务器实现，使 AI 模型能够与 VoIP 服务交互。
## 免责声明
本软件按“原样”提供，不附带任何明示或暗示的保证。作者不保证软件的完整性、可靠性或准确性。使用本软件的风险由您自行承担。作者不对因使用本软件而产生的任何损害负责。
## 概述
本 MCP 服务器为 AI 模型与 VoIPBin API 服务交互提供了一个标准化的接口。它实现了模型上下文协议规范，并支持 SSE 和 stdio 两种传输类型。
## 功能特点
- 通过 MCP 协议完全集成 VoIPBin API
- 支持 stdio 和 SSE 两种传输模式
- 具有适当注释的综合工具定义
- 类型安全的请求/响应处理
- 异步 HTTP 请求
- 适当的错误处理和验证
- 方便部署的 Docker 支持
## 可用工具
### 呼叫管理
- `get_calls`：检索可选筛选的呼叫列表
- `get_call`：获取特定呼叫的详细信息
- `create_call`：创建新呼叫
- `end_call`：结束活动呼叫
### 代理管理
- `get_agents`：检索代理列表
- `get_agent`：获取特定代理的详细信息
- `update_agent_status`：更新代理状态
### 活动管理
- `get_campaigns`：检索活动列表
- `get_campaign`：获取特定活动的详细信息
- `create_campaign`：创建新活动
### 录音管理
- `get_recordings`：检索呼叫录音列表
- `get_recording`：获取特定录音的详细信息
### 队列管理
- `get_queues`：检索呼叫队列列表
- `get_queue`：获取特定队列的详细信息
### 会议管理
- `get_conferences`：检索活动会议列表
- `create_conference`：创建新会议
### 聊天管理
- `get_chats`：检索聊天对话列表
- `send_chat_message`：在聊天对话中发送消息
### 计费管理
- `get_billing_info`：检索当前计费信息
- `get_billing_history`：检索可选日期筛选的计费历史
## 设置
### 本地开发设置
1. 创建虚拟环境：
```bash
python -m venv venv
source venv/bin/activate # 在 Windows 上：venv\Scripts\activate
```
2. 安装依赖项：
```bash
pip install -r requirements.txt
```
3. 创建 `.env` 文件：
```bash
cp .env.example .env
```
4. 使用 VoIPBin API 凭证更新 `.env` 文件：
```
VOIPBIN_API_URL=https://api.voipbin.net/v1.0
VOIPBIN_API_KEY=your-api-key-here
PORT=8000
```
### Docker 设置
1. 使用 Docker Compose 构建和运行：
```bash
# 构建和启动容器
docker-compose up --build
# 在分离模式下运行
docker-compose up -d
# 停止容器
docker-compose down
```
2. 或直接使用 Docker 构建和运行：
```bash
# 构建镜像
docker build -t voipbin-mcp-server .
# 运行容器
docker run -d \
-p 8000:8000 \
-e VOIPBIN_API_KEY=your-api-key-here \
-e VOIPBIN_API_URL=https://api.voipbin.net/v1.0 \
voipbin-mcp-server
```
## 运行服务器
### 本地开发
#### 标准 I/O 模式
```bash
python src/main.py --transport stdio
```
#### SSE 模式
```bash
python src/main.py --transport sse --port 8000
```
### Docker
使用 Docker 时，服务器默认在 SSE 模式下运行。容器暴露端口 8000 用于 SSE 连接。
## 工具使用示例
### 创建呼叫
```json
{
"name": "create_call",
"arguments": {
"body": {
"phone_number": "+1234567890",
"agent_id": "agent_123",
"campaign_id": "campaign_456"
}
}
}
```
### 获取呼叫详情
```json
{
"name": "get_call",
"arguments": {
"call_id": "call_789"
}
}
```
### 创建会议
```json
{
"name": "create_conference",
"arguments": {
"body": {
"name": "团队会议",
"participants": ["+1234567890", "+0987654321"]
}
}
}
```
### 发送聊天消息
```json
{
"name": "send_chat_message",
"arguments": {
"chat_id": "chat_123",
"body": {
"message": "您好，今天我能帮您什么？"
}
}
}
```
## 工具注释
每个工具都包含提供其行为元数据的注释：
- `readOnlyHint`：指示工具是否仅读取数据
- `destructiveHint`：指示工具是否修改或删除数据
- `idempotentHint`：指示重复调用是否与单个调用具有相同的效果
- `openWorldHint`：指示工具是否在开放世界上下文中运行
## 错误处理
服务器包含全面的错误处理：
- 无效的 API 凭证
- 网络连接问题
- 无效的请求参数
- 速率限制
- 服务器错误
## 开发
### 添加新工具
要添加新工具：
1. 在 `list_tools()` 函数中添加工具定义
2. 在 `voipbin_tool()` 函数中实现工具处理程序
3. 更新文档
### 测试
运行测试套件：
```bash
python -m pytest tests/
```
## 安全
- API 密钥安全地存储在环境变量中
- 所有请求都经过身份验证
- API 通信强制使用 HTTPS
- 对所有请求进行输入验证
- Docker 容器以非 root 用户身份运行
- 健康检查确保容器正常运行
## 贡献
1. 分叉仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建拉取请求
## 许可证
本项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
MIT 许可证是一种宽容的许可证，简短且直截了当。只要人们提供对您的源代码的引用，并且不让您承担责任，他们就可以对代码做任何他们想做的事情。
### 您可以用此代码执行的操作：
- 商业使用
- 修改
- 分发
- 私人使用
- 子许可
### 您必须执行的操作：
- 包括原始版权声明
- 包括许可证文本
- 提供对原始源代码的明确引用
- 在任何派生作品中保持引用
### 您不能执行的操作：
- 让作者对损害负责
- 删除或遮蔽引用
- 声称作品是您自己的
有关 MIT 许可证的更多信息，请访问 [choosealicense.com/licenses/mit/](https://choosealicense.com/licenses/mit/)。
MCP 市场
