MCP 服务器

Twilio Agent Payments MCP Server

镜子 (jìng zi)

MCP-Mirror

开发者工具

访问服务器

README

Twilio Agent Payments MCP 服务器

一个 MCP (模型上下文协议) 服务器，它支持通过 Twilio API 处理人工辅助支付，并具有增强的异步回调功能和通过上下文提示引导工作流程的功能。

功能

通过 Twilio 在语音通话期间处理安全支付
捕获支付卡信息（卡号、安全码、有效期）
对支付信息进行令牌化以符合 PCI 标准
通过 MCP 资源进行异步回调
通过 MCP 提示引导支付过程的每个步骤
支持重新输入支付信息
与 Claude Desktop 等 MCP 客户端集成
安全凭证处理
使用 Twilio API 密钥以提高安全性
基于事件的日志记录架构

安装

您可以直接通过 npx 使用此服务器：

npx twilio-agent-payments-mcp-server <accountSid> <apiKey> <apiSecret>

或者全局安装它：

npm install -g twilio-agent-payments-mcp-server
twilio-agent-payments-mcp-server <accountSid> <apiKey> <apiSecret>

配置

服务器需要以下参数：

accountSid: 您的 Twilio 账户 SID（必须以 'AC' 开头，将会被验证）
apiKey: 您的 Twilio API 密钥（以 'SK' 开头）
apiSecret: 您的 Twilio API 密钥密文

环境变量

以下环境变量用于配置：

TOKEN_TYPE: 用于支付的令牌类型（例如，'reusable'，'one-time'）
CURRENCY: 支付的货币（例如，'USD'，'EUR'）
PAYMENT_CONNECTOR: 与 Twilio 一起使用的支付连接器
NGROK_AUTH_TOKEN: 您的 Ngrok 身份验证令牌（处理回调时需要）
NGROK_CUSTOM_DOMAIN: Ngrok 的可选自定义域名

注意：Twilio 凭证（accountSid、apiKey、apiSecret）作为命令行参数提供，而不是环境变量。

安全提示

此服务器使用 API 密钥和密钥，而不是身份验证令牌，以提高安全性。这种方法提供了更好的访问控制，并且能够在需要时撤销凭证。有关更多信息，请参阅 Twilio API 密钥文档。

与 Claude Desktop 一起使用

本地开发

对于本地开发（当软件包未发布到 npm 时），请将以下内容添加到您的 Claude Desktop 配置文件中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "twilio-agent-payments": {
      "command": "node",
      "args": [
        "/PATHTONODE/twilio-agent-payments-mcp-server/build/index.js",
        "your_account_sid_here",
        "your_api_key_here",
        "your_api_secret_here"
      ],
      "env": {
        "TOKEN_TYPE": "reusable",
        "CURRENCY": "USD",
        "PAYMENT_CONNECTOR": "your_connector_name",
        "NGROK_AUTH_TOKEN": "your_ngrok_auth_token_here",
        "NGROK_CUSTOM_DOMAIN": "your_custom_domain_here" // Optional
      }
    }
  }
}

将这些值替换为您实际的 Twilio 凭证和配置。

发布到 npm 后

将软件包发布到 npm 后，您可以使用以下配置：

{
  "mcpServers": {
    "twilio-agent-payments": {
      "command": "npx",
      "args": [
        "-y", 
        "twilio-agent-payments-mcp-server",
        "your_account_sid_here",
        "your_api_key_here",
        "your_api_secret_here"
      ],
      "env": {
        ...process.env,   // 包含现有的环境变量，以便子进程可以访问路径
        "TOKEN_TYPE": "reusable",
        "CURRENCY": "USD",
        "PAYMENT_CONNECTOR": "your_connector_name",
        "NGROK_AUTH_TOKEN": "your_ngrok_auth_token_here",
        "NGROK_CUSTOM_DOMAIN": "your_custom_domain_here" // Optional
      }
    }
  }
}

与宿主应用程序集成

模型上下文协议 (MCP) 的主要优势之一是它消除了对 LLM 上下文进行大量手动配置的需求。 MCP 服务器自动为 LLM 客户端提供所有必要的工具定义、资源模板和功能。

设置您的宿主应用程序

要将此 MCP 服务器集成到您自己的宿主应用程序中：

实现 MCP 客户端：使用现有的 MCP 客户端库或在您的应用程序中实现 MCP 客户端协议。
连接到 MCP 服务器：配置您的应用程序以连接到 Twilio Agent Payments MCP 服务器。
让协议处理其余的事情：MCP 服务器将自动：
- 向您的客户端注册其工具和资源
- 为所有工具提供输入模式
- 提供上下文提示以引导 LLM 完成支付流程

无需在 LLM 的上下文中手动定义工具或资源 - MCP 协议会自动处理此发现。

集成代码示例

这是一个简化的示例，说明如何与 MCP 客户端集成：

// 初始化您的 MCP 客户端
const mcpClient = new McpClient();

// 连接到 Twilio Agent Payments MCP 服务器
await mcpClient.connectToServer({
  name: "twilio-agent-payments",
  // 连接详细信息取决于您的特定 MCP 客户端实现
  // 这可以是 WebSocket URL、stdio 连接或其他传输
});

// 客户端将自动发现可用的工具和资源

// 当 LLM 想要使用工具时，您的应用程序可以这样处理它：
function handleLlmToolRequest(toolRequest) {
  // toolRequest 将包含：
  // - server_name: "twilio-agent-payments"
  // - tool_name: 例如，"startPaymentCapture"
  // - arguments: 例如，{ callSid: "CA1234567890abcdef" }
  
  return mcpClient.callTool(toolRequest);
}

// 资源也是如此：
function handleLlmResourceRequest(resourceRequest) {
  // resourceRequest 将包含：
  // - server_name: "twilio-agent-payments"
  // - uri: 例如，"payment://CA1234567890abcdef/PA9876543210abcdef/status"
  
  return mcpClient.accessResource(resourceRequest);
}

所需的最小 LLM 上下文

LLM 只需要知道它可以使用 Twilio Agent Payments MCP 服务器来处理支付。在您的系统提示中添加一个简单的指令就足够了：

您可以使用 Twilio Agent Payments MCP 服务器来帮助处理语音通话期间的安全支付。
当客户想要付款时，您可以使用此服务器提供的工具安全地捕获
支付信息，同时保持 PCI 合规性。

服务器将在每个步骤中通过上下文提示引导您完成支付过程。

MCP 服务器本身提供了所有详细的工具定义、输入模式和上下文提示，以引导 LLM 完成支付流程。

可用工具

startPaymentCapture

启动活动呼叫的支付捕获过程。

参数：

callSid: 活动呼叫的 Twilio 呼叫 SID

注意：在处理 Twilio 呼叫时，您需要了解您正在使用的呼叫段呼叫 SID。 Twilio Payments 需要附加到 PSTN 侧呼叫段。如果应用于 Twilio 客户端侧，则不会捕获 DTMF 数字。因此，此 MCP 服务器假设正在使用正确的呼叫段。通常按如下方式检查：

 // 伪代码：呼叫方向
  if (event.CallDirection === "toPSTN") {
    theCallSid = event.CallSid;
  }

  if (event.CallDirection == "toSIP") {
    theCallSid = event.ParentCallSid;
  }

paymentSid: 新支付会话的 Twilio 支付 SID

captureCardNumber

开始捕获支付卡号。

参数：

callSid: 活动呼叫的 Twilio 呼叫 SID
paymentSid: 支付会话的 Twilio 支付 SID
captureType: 设置为 'payment-card-number'

卡号捕获操作的状态

captureSecurityCode

开始捕获卡安全码。

参数：

callSid: 活动呼叫的 Twilio 呼叫 SID
paymentSid: 支付会话的 Twilio 支付 SID
captureType: 设置为 'security-code'

安全码捕获操作的状态

captureExpirationDate

开始捕获卡有效期。

参数：

callSid: 活动呼叫的 Twilio 呼叫 SID
paymentSid: 支付会话的 Twilio 支付 SID
captureType: 设置为 'expiration-date'

有效期捕获操作的状态

completePaymentCapture

完成支付捕获会话。

参数：

callSid: 活动呼叫的 Twilio 呼叫 SID
paymentSid: 支付会话的 Twilio 支付 SID

支付完成操作的状态

可用资源

payment://{callSid}/{paymentSid}/status

以 JSON 对象形式获取支付会话的当前状态。此资源提供有关支付捕获过程当前状态的详细信息，包括：

支付 SID
支付卡号（已屏蔽）
支付卡类型
安全码状态
有效期
支付确认码
支付结果
支付令牌

MCP 提示

服务器提供上下文提示，以引导 LLM 完成支付流程的每个步骤：

StartCapture 提示

提供有关如何启动支付捕获过程的指导，包括：

有关询问客户是否准备好提供支付信息的说明
安全处理和令牌化的说明
使用 startPaymentCapture 工具的步骤

CardNumber 提示

指导 LLM 如何处理卡号捕获过程，包括：

有关向客户解释需要哪些信息的说明
处理客户问题或疑虑的技巧
使用 captureCardNumber 工具的步骤

SecurityCode 提示

提供有关捕获卡安全码的指导，包括：

有关解释安全码是什么的说明
处理客户问题或疑虑的技巧
使用 captureSecurityCode 工具的步骤

ExpirationDate 提示

指导 LLM 如何捕获卡有效期，包括：

有关解释所需格式 (MM/YY) 的说明
处理客户问题或疑虑的技巧
使用 captureExpirationDate 工具的步骤

FinishCapture 提示

提供有关完成支付捕获过程的指导，包括：

有关确认已收集所有信息的说明
使用 completePaymentCapture 工具的步骤

Completion 提示

指导 LLM 在成功处理支付后该怎么做，包括：

有关确认支付成功的说明
对话中后续步骤的建议

Error 提示

提供有关处理支付捕获过程中错误的指导，包括：

有关向客户解释错误的说明
解决常见问题的建议
重试支付捕获过程的步骤

架构

此 MCP 服务器实现了增强的架构来处理支付流程：

基于事件的架构

服务器使用基于事件的架构，其中 EventEmitter 用于组件之间的通信：

每个工具、资源和服务器组件都扩展了 EventEmitter
组件发出事件以进行日志记录和回调
事件侦听器将日志转发到 MCP 服务器的日志记录系统

回调处理

服务器使用 @deshartman/mcp-status-callback 软件包来处理来自 Twilio 的异步回调：

使用 Ngrok 创建安全隧道以接收回调
处理不同支付阶段的回调
根据回调数据更新状态存储
处理错误情况和重新进入场景

状态管理

支付状态通过基于 Map 的存储进行管理：

statusCallbackMap 存储按支付 SID 索引的支付会话数据
每次回调都会使用最新信息更新状态
PaymentStatusResource 提供对此状态数据的访问

MCP 集成

服务器通过以下方式与 MCP 协议集成：

工具：使用 Zod 模式定义以进行输入验证
资源：提供对支付状态数据的访问
提示：为支付流程的每个步骤提供上下文指导
日志记录：基于事件的日志记录转发到 MCP 服务器

开发

要构建项目：

npm install
npm run build

先决条件

Node.js 18+
Express（用于回调处理）
Twilio SDK
具有身份验证令牌的 Ngrok 帐户

手动运行服务器

要手动启动服务器进行测试（在 Claude Desktop 之外）：

# 使用实际凭证运行
node build/index.js "your_account_sid_here" "your_api_key_here" "your_api_secret"

# 或者使用 npm 脚本（它使用 ts-node 进行开发）
npm run dev -- "your_account_sid_here" "your_api_key_here" "your_api_secret"

服务器将启动并等待 MCP 客户端连接。

与 Claude Desktop 一起使用时，当 Claude 加载配置文件时，服务器会自动启动。您无需手动启动它。

PCI 合规性

此服务器通过对支付卡信息进行令牌化来帮助实现 PCI 合规性。实际的卡数据由 Twilio 处理，并且永远不会存储在您的系统中。有关 Twilio PCI 合规性的更多信息，请参阅 Twilio 关于安全支付的文档。

许可证

MIT

MCP Inspector 兼容性

将此服务器与 MCP Inspector 一起使用时，请注意所有日志记录都是通过 MCP 日志记录功能完成的，而不是 console.log()。这是有意为之，并且对于与 MCP 协议的兼容性是必需的，该协议使用 stdout 进行 JSON 通信。

如果您要扩展此服务器或调试问题：

通过发出 LOG_EVENT 事件来使用基于事件的日志记录系统
避免使用 console.log()，因为它会干扰 stdout 上 MCP 协议的 JSON 消息
对于 MCP 上下文之外的调试，您可以使用 console.error()，它会输出到 stderr

基于事件的日志记录架构

服务器使用基于事件的日志记录架构：

事件发射器：所有工具和资源类都扩展了 Node.js 的 EventEmitter，并发出带有级别和消息数据的“log”事件。

日志转发：这些事件由事件侦听器捕获并转发到 MCP 服务器的日志记录系统：

// 设置工具日志的事件侦听器
startPaymentCaptureTool.on(LOG_EVENT, logToMcp);
captureCardNumberTool.on(LOG_EVENT, logToMcp);
// ... 其他工具

MCP 集成：logToMcp 函数将这些事件转换为与 MCP 兼容的日志消息：

const logToMcp = (data: { level: string, message: string }) => {
    // 仅使用有效的日志级别：info、error、debug
    // 如果级别为“warn”，则将其视为“info”
    const mcpLevel = data.level === 'warn' ? 'info' : data.level as "info" | "error" | "debug";

    // 将日志消息发送到 MCP 服务器的底层 Server 实例
    mcpServer.server.sendLoggingMessage({
        level: mcpLevel,
        data: data.message,
    });
};

支持的日志级别

服务器支持以下日志级别：

info: 常规信息消息
error: 错误消息和异常
debug: 详细的调试信息
warn: 警告消息（自动转换为“info”以实现 MCP 兼容性）

支付回调数据结构

服务器处理来自 Twilio 的两种主要类型的回调数据：

初始连接器数据

首次创建支付会话时，Twilio 会发送连接器数据：

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

捕获数据

捕获支付信息后，Twilio 会发送更新的数据：

{ 
  "SecurityCode": "xxx",
  "PaymentCardType": "visa",
  "Sid": "PKxxxx",
  "PaymentConfirmationCode": "ch_a9dc6297cd1a4fb095e61b1a9cf2dd1d",
  "CallSid": "CAxxxxx",
  "Result": "success",
  "AccountSid": "AC75xxxxxx",
  "ProfileId": "",
  "DateUpdated": "2021-08-10T03:58:27.290Z",
  "PaymentToken": "",
  "PaymentMethod": "credit-card",
  "PaymentCardNumber": "xxxxxxxxxxxx1111",
  "ExpirationDate": "1225"
}

服务器将此数据存储在 statusCallbackMap 中，按支付 SID 索引，并通过 PaymentStatusResource 提供。