VoIPBin MCP Server

VoIPBin MCP サーバー

VoIPBin MCP サーバー

VoIPBin API 向けの Model Context Protocol（MCP）サーバー実装です。AI モデルが VoIP サービスを利用できるようにします。

免責事項

このソフトウェアは、明示的または黙示的を問わず、いかなる保証もなく「現状のまま」提供されます。作者は、このソフトウェアの完全性、信頼性、正確性について一切保証しません。このソフトウェアの使用はすべてご自身の責任で行ってください。作者は、このソフトウェアの使用によって生じたいかなる損害についても責任を負いません。

概要

この MCP サーバーは、AI モデルが VoIPBin の API サービスを利用するための標準インターフェースを提供します。Model Context Protocol の仕様を実装し、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  # On Windows: venv\Scripts\activate

2. 依存関係をインストールします：

pip install -r requirements.txt

3. .env ファイルを作成します：

cp .env.example .env

4. .env ファイルに VoIPBin API の認証情報を設定します：

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 モードで実行されます。コンテナは SSE 接続用にポート 8000 を公開します。

ツールの使用例

通話の作成

{
  "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：呼び出しを繰り返した場合に、1 回だけ呼び出した場合と同じ効果になるかどうかを示します
• openWorldHint：ツールがオープンワールドのコンテキストで動作するかどうかを示します

エラー処理

サーバーには、次のような包括的なエラー処理が含まれています。

• 無効な API 認証情報
• ネットワーク接続の問題
• 無効なリクエストパラメーター
• レート制限
• サーバーエラー

開発

新しいツールの追加

新しいツールを追加するには：

1. list_tools() 関数にツール定義を追加します
2. voipbin_tool() 関数にツールハンドラーを実装します
3. ドキュメントを更新します

テスト

テストスイートを実行します：

python -m pytest tests/

セキュリティ

• API キーは環境変数に安全に保存されます
• すべてのリクエストが認証されます
• API 通信には HTTPS が必須です
• すべてのリクエストで入力検証が行われます
• Docker コンテナは非 root ユーザーで実行されます
• ヘルスチェックにより、コンテナが適切に実行されていることを確認します

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

MIT ライセンスは、簡潔で要点を押さえた寛容なライセンスです。あなたへの帰属表示を行い、あなたに責任を負わせない限り、コードを自由に利用できます。

このコードでできること：

• 商用利用する
• 改変する
• 配布する
• 私的に利用する
• サブライセンスを付与する

必ず行うこと：

• 元の著作権表示を含める
• ライセンス文を含める
• 元のソースを明確に表示する
• 派生物でも帰属表示を維持する

禁止されていること：

• 損害について著者に責任を負わせる
• 帰属表示を削除または不明瞭にする
• この作品を自分のものだと主張する

MIT ライセンスの詳細については、choosealicense.com/licenses/mit/をご覧ください。