Twilio Agent Payments MCP Server

🚀 Twilio 語音 MCP 服務器插件開發文檔

本插件用於集成 Twilio 的語音 API 和支付處理功能，能實現開始支付捕獲、捕獲卡號等操作，且所有支付數據處理和存儲由 Twilio 安全流程完成，確保 PCI 合規性。

🚀 快速開始

安裝插件

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('Error starting payment capture:', err);
    }
}

✨ 主要特性

• 與 Twilio 的語音 API 和支付處理功能集成。
• 提供開始支付捕獲、捕獲卡號、捕獲安全碼、捕獲卡片類型和獲取支付狀態等核心功能。
• 所有實際的支付數據處理和存儲均由 Twilio 安全流程完成，確保 PCI 合規性。

📦 安裝指南

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('Error starting payment capture:', err);
    }
}

📚 詳細文檔

核心工具類

開始支付捕獲

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 管理器。

🔧 技術細節

日誌架構

所有工具類繼承自 EventEmitter，定義了統一的日誌事件接口 LogEvent，包含時間戳、日誌級別、消息和上下文等信息。日誌發射器 Logger 實現了日誌記錄功能，通過 emit 方法觸發 log 事件。

MCP 協議兼容性

插件實現了多個 MCP 標準接口，所有操作通過事件發射器通知 MCP 管理器，確保與 MCP 協議的兼容性。

📄 許可證

文檔中未提及相關信息。

⚠️ 重要提示

1. 所有 API 調用都需要有效的 Twilio 賬戶憑證。
2. 支付流程必須在受信任的網絡環境中進行。
3. 回調數據需要妥善處理和驗證。
4. 確保日誌記錄完整，便於故障排查。