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);
    }
}

✨ 主要特性

• 开始支付捕获
• 捕获卡号
• 捕获安全码
• 捕获卡片类型
• 获取支付状态

📦 安装指南

使用 npm 进行安装：

npm install twilio-mcp-server-plugin

💻 使用示例

基础用法

开始支付捕获

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 类来实现事件的监听和触发，统一的日志事件接口方便了日志的记录和管理。在与 Twilio 语音 API 交互时，使用有效的 Twilio 账户凭证进行 API 调用，确保支付流程的安全性和合规性。

📄 注意事项

⚠️ 重要提示

1. 所有 API 调用都需要有效的 Twilio 账户凭证
2. 支付流程必须在受信任的网络环境中进行
3. 回调数据需要妥善处理和验证
4. 确保日志记录完整，便于故障排查