VoIPBin MCP Server

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：结束正在进行的通话

Agent 管理

• get_agents：获取 Agent 列表
• get_agent：获取指定 Agent 的详细信息
• update_agent_status：更新 Agent 状态

活动管理

• 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. 创建虚拟环境：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. 安装依赖：

pip install -r requirements.txt

3. 创建 .env 文件：

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 构建并运行：

# Build and start the container
docker-compose up --build

# Run in detached mode
docker-compose up -d

# Stop the container
docker-compose down

2. 或直接使用 Docker 构建并运行：

# Build the image
docker build -t voipbin-mcp-server .

# Run the container
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

运行服务

本地开发

标准输入/输出模式

python src/main.py --transport stdio

SSE 模式

python src/main.py --transport sse --port 8000

Docker

使用 Docker 时，服务默认以 SSE 模式运行。容器会公开端口 8000，用于 SSE 连接。

工具使用示例

创建通话

{
  "name": "create_call",
  "arguments": {
    "body": {
      "phone_number": "+1234567890",
      "agent_id": "agent_123",
      "campaign_id": "campaign_456"
    }
  }
}

获取通话详情

{
  "name": "get_call",
  "arguments": {
    "call_id": "call_789"
  }
}

创建会议

{
  "name": "create_conference",
  "arguments": {
    "body": {
      "name": "Team Meeting",
      "participants": ["+1234567890", "+0987654321"]
    }
  }
}

发送聊天消息

{
  "name": "send_chat_message",
  "arguments": {
    "chat_id": "chat_123",
    "body": {
      "message": "Hello, how can I help you today?"
    }
  }
}

工具注释

每个工具都包含用于描述其行为的元数据注释：

• readOnlyHint：指示该工具是否只读取数据
• destructiveHint：指示该工具是否会修改或删除数据
• idempotentHint：指示重复调用是否与单次调用效果相同
• openWorldHint：指示该工具是否在开放世界环境中运行

错误处理

服务包含全面的错误处理机制：

• API 凭据无效
• 网络连接问题
• 请求参数无效
• 速率限制
• 服务端错误

开发

添加新工具

添加新工具的步骤：

1. 在 list_tools() 函数中添加工具定义
2. 在 voipbin_tool() 函数中实现工具处理程序
3. 更新文档

测试

运行测试套件：

python -m pytest tests/

安全性

• API 密钥安全地存储在环境变量中
• 所有请求均经过身份验证
• API 通信强制使用 HTTPS
• 对所有请求执行输入验证
• Docker 容器以非 root 用户身份运行
• 健康检查确保容器正常运行

参与贡献

1. Fork 此仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

许可证

本项目采用 MIT License 授权——详情请参阅 LICENSE 文件。

MIT License 是一项宽松、简明扼要的许可证。只要注明出处且不追究你的责任，任何人都可以随意使用代码。

你可以如何使用此代码：

• 用于商业用途
• 修改
• 分发
• 私下使用
• 再许可

你必须做到：

• 包含原始版权声明
• 包含许可证文本
• 明确注明原始来源
• 在任何衍生作品中保留出处声明

你不能：

• 追究作者的损害赔偿责任
• 删除或隐去出处声明
• 将作品声称为自己的

如需了解 MIT License 的更多信息，请访问 choosealicense.com/licenses/mit/。