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

python -m venv venv
source venv/bin/activate  # 在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构建并运行：

# 构建并启动容器
docker-compose up --build

# 以分离模式运行
docker-compose up -d

# 停止容器
docker-compose down

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

# 构建镜像
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模式

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": "团队会议",
      "participants": ["+1234567890", "+0987654321"]
    }
  }
}

发送聊天消息

{
  "name": "send_chat_message",
  "arguments": {
    "chat_id": "chat_123",
    "body": {
      "message": "你好，今天我能为你做些什么？"
    }
  }
}

工具注释

每个工具都包含提供其行为元数据的注释：

• readOnlyHint: 表示工具仅读取数据
• destructiveHint: 表示工具修改或删除数据
• idempotentHint: 表示重复调用具有与单次调用相同的效果
• openWorldHint: 表示工具在开放世界环境中操作

错误处理

服务器包括全面的错误处理：

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

开发

添加新工具

要添加新工具：

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

测试

运行测试套件：

python -m pytest tests/

安全

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

贡献

1. 分叉仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建拉取请求

许可证

本项目根据MIT许可证发布 - 请参阅LICENSE文件获取详细信息。

MIT许可证是一个许可条款简洁明了的许可证。只要您提供原始来源的归属并不要求作者承担责任，您可以自由地使用此代码。

您可以做什么：

• 商业用途
• 修改代码
• 分发代码
• 私人使用
• 再许可

您必须做什么：

• 包含原始版权声明
• 包含许可证文本
• 明确归功于原始来源
• 在衍生作品中保持归属

您不能做什么：

• 将作者视为损害赔偿的责任方
• 删除或模糊归属
• 声称该工作是您自己的

有关MIT许可证的更多信息，请访问choosealicense.com/licenses/mit/。