Twilio Agent Payments MCP Server

🚀 Twilio 音声 MCP サーバープラグイン開発ドキュメント

この MCP サーバープラグインは、Twilio の音声 API と支払い処理機能を統合するために使用されます。以下の核心機能を提供します：

• 支払いキャプチャの開始
• カード番号のキャプチャ
• セキュリティコードのキャプチャ
• カードタイプのキャプチャ
• 支払いステータスの取得

すべての実際の支払いデータの処理と保存は、Twilio のセキュリティプロセスによって行われ、PCI コンプライアンスが保証されます。

✨ 主な機能

🔧 核心ツールクラス

支払いキャプチャの開始

interface StartPaymentCaptureParams {
    accountSid: string;
    apiKey: string;
    apiSecretKey: string;
}

class StartPaymentCaptureTool extends EventEmitter {
    constructor(params: StartPaymentCaptureParams) {
        super();
        // 初期化 Twilio クライアント
    }

    async startPaymentCapture(callSid: string, amount: string): Promise<PaymentSession> {
        // 呼び出し Twilio 音声 API 支払いキャプチャセッションの開始
        // 新しい PaymentSession オブジェクトを返す
    }
}

カード番号のキャプチャ

interface CaptureCardNumberParams {
    accountSid: string;
    apiKey: string;
    apiSecretKey: string;
}

class CaptureCardNumberTool extends EventEmitter {
    constructor(params: CaptureCardNumberParams) {
        super();
    }

    async captureCardNumber(callSid: string): Promise<PaymentData> {
        // 呼び出し Twilio 音声 API カード番号のキャプチャ
        // 返された支払いデータを処理する
    }
}

その他のツールクラス

• CaptureSecurityCodeTool - セキュリティコードのキャプチャ
• CaptureCardTypeTool - カードタイプのキャプチャ
• GetPaymentStatusTool - 支払いステータスの取得

💸 支払いコールバックデータ構造

初期コネクタデータ

{
  "PaymentConnector": "PGP_MOCK",
  "DateCreated": "2021-08-10T03:55:53.408Z",
  "PaymentMethod": "credit-card",
  "CallSid": "CAzzzzz",
  "ChargeAmount": "9.99",
  "AccountSid": "ACxxxxx",
  "Sid": "PKxxxx"
}

キャプチャデータ

{ 
  "SecurityCode": "xxx",          // セキュリティコード
  "PaymentCardType": "visa",      // カードタイプ（例：visa、mastercard など）
  "Sid": "PKxxxx",                // 支払いセッション ID
  "PaymentConfirmationCode": "ch_a9dc6297cd1a4fb095e61b1a9cf2dd1d",
  "CallSid": "CAxxxxx",           // 呼び出し ID
  "Result": "success",            // 支払い結果
  "AccountSid": "AC75xxxxxx",     // アカウント ID  
  "DateCreated": "2021-08-10T03:55:53.408Z",
  "ChargeAmount": "9.99"
}

📝 ログアーキテクチャ

すべてのツールクラスは EventEmitter を継承し、統一されたログイベントインターフェースを定義しています：

interface LogEvent {
    timestamp: string;
    level: 'info' | 'error' | 'debug';
    message: string;
    context?: object;
}

ログエミッタの実装：

class Logger extends EventEmitter {
    log(level: 'info' | 'error' | 'debug', message: string, context?: object): void {
        const event: LogEvent = {
            timestamp: new Date().toISOString(),
            level,
            message,
            context
        };
        this.emit('log', event);
    }
}

🛠️ MCP プロトコル互換性

プラグインは以下の MCP 標準インターフェースを実装しています：

• startPaymentCapture
• captureCardNumber
• captureSecurityCode
• getPaymentStatus
• handlePaymentComplete

すべての操作は、イベントエミッタを介して MCP マネージャーに通知されます。

📦 インストール

npm install twilio-mcp-server-plugin

💻 使用例

プラグインの初期化

import { StartPaymentCaptureTool } from 'twilio-mcp-server-plugin';

const params = {
    accountSid: process.env.TWILIO_ACCOUNT_SID,
    apiKey: process.env.TWILIO_API_KEY,
    apiSecretKey: process.env.TWILIO_API_SECRET_KEY
};

const paymentCapture = new StartPaymentCaptureTool(params);

支払いプロセスの処理

async function handleVoiceCallStarted(callSid: string, amount: string) {
    try {
        const session = await paymentCapture.startPaymentCapture(callSid, amount);
        // 後続の音声インタラクションを監視する
    } catch (err) {
        console.error('支払いキャプチャの開始時にエラーが発生しました:', err);
    }
}

⚠️ 重要提示

1. すべての API 呼び出しには、有効な Twilio アカウントの認証情報が必要です。
2. 支払いプロセスは、信頼できるネットワーク環境で行う必要があります。
3. コールバックデータは適切に処理し、検証する必要があります。
4. 障害のトラブルシューティングを容易にするため、ログ記録を完全に行うようにしてください。