内容
# BolnaVoiceAI MCP 服务器与 FastMCP
本仓库提供一个基于 Python 的 **MCP（模型上下文协议）** 服务器，该服务器与 **Bolna AI** 的 API 集成，用于处理语音代理和发起语音呼叫。服务器使用 **FastMCP** 和 **httpx** 构建，用于异步操作。它包括用于从 Bolna 创建、检索、更新、删除和执行语音 AI 代理的工具。
此外，本仓库还包括如何通过配置 JSON 文件将 MCP 服务器与 **Claude Desktop** 集成的说明。
## 功能特点
- **创建、检索、更新和删除代理**，使用 Bolna API。
- **执行代理操作**，使用 `/executions/{agent_id}` 端点。
- 使用 **FastMCP** 服务器，带有易于集成的工具。
- 通过 `httpx` 实现**异步 HTTP 请求**，以高效处理 API 调用。
## 前置条件
- Python 3.7 或更高版本
- 安装所需的依赖项：
```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
```
- **Bolna API 密钥**：您需要从 [Bolna AI 平台](https://platform.bolna.ai) 获取 API 密钥，以验证 API 请求。
## 设置说明
### 1. 克隆仓库
```bash
git clone https://github.com/your-repository/BolnaVoiceAI-MCP.git
cd BolnaVoiceAI-MCP
```
### 2. 安装依赖项
```bash
# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate
uv add "mcp[cli]" httpx
```
### 3. 配置 Bolna API 密钥
在 `bolna_mcp_server.py` 文件中，设置用于验证 Bolna API 的 **API 密钥**：
```python
API_KEY = "your_bolna_api_key" # 替换为实际的 Bolna API 密钥
```
### 4. 运行 MCP 服务器
完成所有设置后，您可以运行服务器：
```bash
uv run bolna.py
```
服务器将启动并暴露以下工具供交互：
- `/agent/create`（POST）
- `/agent/all`（GET）
- `/agent/{agent_id}`（GET）
- `/agent/{agent_id}`（PUT）
- `/agent/{agent_id}`（DELETE）
- `/executions/{agent_id}`（POST）
- `/executions/status/{execution_id}`（GET）
## MCP 服务器中的工具
### 1. **create_agent**
创建新的语音 AI 代理。
**端点**：`/agent/create`（POST）
```json
{
"name": "代理名称",
"description": "代理描述"
}
```
### 2. **get_agents**
检索所有语音 AI 代理。
**端点**：`/agent/all`（GET）
### 3. **get_agent**
通过 ID 检索特定的语音 AI 代理。
**端点**：`/agent/{agent_id}`（GET）
### 4. **update_agent**
更新现有的语音 AI 代理。
**端点**：`/agent/{agent_id}`（PUT）
```json
{
"name": "更新的代理名称",
"description": "更新的代理描述"
}
```
### 5. **delete_agent**
通过 ID 删除语音 AI 代理。
**端点**：`/agent/{agent_id}`（DELETE）
### 6. **execute_agent**
执行特定的代理，并带有执行数据。
**端点**：`/executions/{agent_id}`（POST）
```json
{
"data": "执行数据"
}
```
### 7. **get_execution_status**
通过 ID 检索执行的狀態。
**端点**：`/executions/status/{execution_id}`（GET）
---
## 与 **Claude Desktop** 集成
要将此 MCP 服务器与 **Claude Desktop** 集成，您需要配置一个 JSON 文件，允许 Claude 与 MCP 服务器通信。
### 1. **配置文件（`claude_config.json`）**
创建一个 `claude_config.json` 文件，结构如下：
```json
{
"mcpServers": {
"bolna": {
"command": "uv",
"args": [
"--directory",
"/Users/admin/Documents/bolna",
"run",
"bolna.py"
]
}
}
}
```
**字段解释**：
- **`claude_mcp_server`**：您的 MCP 服务器运行的 URL（默认为 `http://localhost:8000`）。
- **`api_key`**：您的 Bolna API 密钥，用于验证请求。
- **`agent_id`**：您要交互的语音 AI 代理的 ID。
- **`phone_number`**：将用于呼叫的电话号码。
- **`call_message`**：呼叫时要播放的消息。
### 2. **在 Claude Desktop 中使用配置**
准备好 `claude_config.json` 文件后，您可以通过读取此配置文件来配置 **Claude Desktop** 使用 MCP 服务器。确保 Claude 可以访问 MCP 服务器，无论是本地还是通过网络。
- **配置 Claude Desktop**，使用 `claude_config.json` 中定义的设置调用 MCP 服务器的 `make_call` 工具。
- Claude Desktop 将发送呼叫请求，并带有适当的数据，MCP 服务器将使用 Bolna 的 API 发起呼叫。
---
## 故障排除
### 1. **错误处理**
确保您已为 MCP 服务器中的 HTTP 请求设置了正确的错误处理。这包括在向 Bolna 的 API 发送请求时捕获任何异常。
### 2. **身份验证**
如果您遇到身份验证问题，请确保您的 API 密钥有效，并且具有访问相关 Bolna API 端点的正确权限。
### 3. **防火墙/网络问题**
如果无法从 Claude Desktop 连接到 MCP 服务器，请确保 MCP 服务器正在运行并且可访问。如果必要，请调整防火墙或网络设置，以允许 Claude 和服务器之间的通信。
---
## 许可证
该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
---
## 结论
此 **BolnaVoiceAI MCP 服务器** 为管理 Bolna AI 的语音代理和发起语音呼叫提供了强大的接口。通过使用 **FastMCP** 和 **httpx**，它确保了与 Bolna API 的高效、异步通信。通过可配置的 JSON 文件与 **Claude Desktop** 集成，您可以轻松自动化语音呼叫和代理交互。
