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 上: venvScriptsactivate

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

1. 或者直接使用 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": "Team Meeting", "participants": ["+1234567890", "+0987654321"] } } }### 发送聊天消息 json { "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. 更新文档

测试

运行测试套件： bash python -m pytest tests/

安全性

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

贡献

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

许可证

本项目根据MIT许可证授权 - 详情请参阅LICENSE文件。

MIT许可证是一种宽松的许可证，简短而直接。它允许人们在提供归因并免除您责任的前提下自由使用代码。

您可以对这段代码做什么：

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

您必须做什么：

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

您不能做什么：

• 因损害而追究作者的责任
• 删除或模糊归因
• 声称作品是您自己的

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