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 密钥密文
• statusCallback: Twilio 用于发送支付状态更新的 URL

环境变量

需要以下环境变量：

• TOKEN_TYPE: 用于支付的令牌类型（例如，'reusable'，'one-time'）
• CURRENCY: 支付的货币（例如，'USD'，'EUR'）
• PAYMENT_CONNECTOR: 与 Twilio 一起使用的支付连接器

安全提示

此服务器使用 API 密钥和密钥，而不是 Auth Tokens，以提高安全性。 这种方法提供了更好的访问控制，并且能够在需要时撤销凭据。 有关更多信息，请参见 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",
        "+1234567890",
        "https://your-callback-url.com/payment-status"
      ],
      "env": {
        "TOKEN_TYPE": "reusable",
        "CURRENCY": "USD",
        "PAYMENT_CONNECTOR": "your_connector_name"
      }
    }
  }
}

将这些值替换为您实际的 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",
        "+1234567890",
        "https://your-callback-url.com/payment-status"
      ],
      "env": {
        "TOKEN_TYPE": "reusable",
        "CURRENCY": "USD",
        "PAYMENT_CONNECTOR": "your_connector_name"
      }
    }
  }
}

与宿主应用程序集成

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

设置您的宿主应用程序

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

1. 实现 MCP 客户端：使用现有的 MCP 客户端库或在您的应用程序中实现 MCP 客户端协议。

2. 连接到 MCP 服务器：配置您的应用程序以连接到 Twilio Agent Payments MCP 服务器。

3. 让协议处理其余的事情：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 Call SID

返回：

• paymentSid: 新支付会话的 Twilio Payment SID
• prompt: 一个 markdown 格式的提示，用于指导 LLM 完成后续步骤

updatePaymentField

使用特定的捕获类型更新支付字段。

参数：

• callSid: 活动呼叫的 Twilio Call SID
• paymentSid: 支付会话的 Twilio Payment SID
• captureType: 要执行的捕获类型（例如，'payment-card-number'、'security-code'、'expiration-date'）

返回：

• success: 指示成功的布尔值
• prompt: 一个 markdown 格式的提示，用于指导 LLM 完成后续步骤

resetPaymentField

当客户出错时，重置支付字段以重新输入。

参数：

• callSid: 活动呼叫的 Twilio Call SID
• paymentSid: 支付会话的 Twilio Payment SID
• field: 要重置的字段（'cardNumber'、'securityCode' 或 'expirationDate'）

返回：

• success: 指示成功的布尔值
• prompt: 一个 markdown 格式的提示，用于指导 LLM 完成重新输入过程

completePaymentCapture

完成支付捕获会话。

参数：

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

返回：

• success: 指示成功的布尔值
• token: 支付令牌（如果成功）
• prompt: 一个 markdown 格式的提示，用于指导 LLM 完成完成

getPaymentStatus

获取支付会话的当前状态。

参数：

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

返回：

• 有关支付会话的详细状态信息
• 所有支付字段的当前状态
• prompt: 一个 markdown 格式的提示，用于根据当前状态指导 LLM

可用资源

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

以 JSON 对象形式获取支付会话的当前状态。

payment://{callSid}/{paymentSid}/prompt

获取当前支付状态的 markdown 格式提示，以指导 LLM 完成后续步骤。

架构

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

状态管理

服务器维护支付会话的内存状态存储，跟踪：

• 会话状态（'initialized'、'in-progress'、'complete'、'error'）
• 卡号状态（掩码值、完成状态、重新输入需求）
• 安全码状态
• 有效期状态
• 支付令牌（完成时）

回调处理

Express 服务器处理来自 Twilio 的异步回调：

• 侦听配置的端口（默认：3000）
• 处理不同支付阶段的回调
• 根据回调数据更新状态存储
• 处理错误情况和重新输入场景

MCP 资源

动态资源提供对支付状态的访问：

• payment://{callSid}/{paymentSid}/status: 当前支付状态为 JSON
• payment://{callSid}/{paymentSid}/prompt: 当前状态的上下文提示

MCP 提示

上下文提示指导 LLM 完成支付流程：

• 启动捕获提示
• 卡号捕获提示
• 安全码捕获提示
• 有效期捕获提示
• 完成提示
• 错误处理提示
• 用于更正场景的重新输入提示

开发

要构建项目：

npm install
npm run build

先决条件

• Node.js 14+
• Express（用于回调处理）
• Twilio SDK

手动运行服务器

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

# 使用实际凭据运行
node build/index.js "your_account_sid_here" "your_api_key_here" "your_api_secret" "+1234567890" "https://your-callback-url.com/payment-status"

# 或者使用 npm 脚本（它使用 ts-node 进行开发）
npm run dev -- "your_account_sid_here" "your_api_key_here" "your_api_secret" "+1234567890" "https://your-callback-url.com/payment-status"

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

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

PCI 合规性

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

许可证

MIT

MCP Inspector 兼容性

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

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

1. 使用 console.error() 进行所有日志记录，以确保日志转到 stderr
2. 避免使用 console.log()，因为它会干扰 MCP 协议在 stdout 上的 JSON 消息
3. 保持日志记录最小化，以避免使终端输出混乱

这种方法确保 MCP Inspector 可以正确解析服务器和客户端之间交换的 JSON 消息，而不会受到日志消息的干扰。

MCP 服务器日志记录

日志记录配置

Twilio Agent Payments MCP 服务器根据 MCP 规范 实现了日志记录功能。 初始化 MCP 服务器时，必须显式配置日志记录：

const mcpServer = new McpServer(SERVER_CONFIG, {
    capabilities: {
        logging: {}
    }
});

此配置至关重要 - 如果没有它，任何使用日志记录功能的尝试都将导致运行时错误，并显示如下消息：

Error: Server does not support logging (required for notifications/message)

基于事件的日志记录架构

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

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

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

   // 设置回调处理程序日志的事件侦听器
   callbackHandler.on('log', forwardLogToMcp);
   
   // 设置 Twilio 代理支付服务器日志的事件侦听器
   twilioAgentPaymentServer.on('log', forwardLogToMcp);
   

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

   const forwardLogToMcp = (data: { level: string, message: string }) => {
       // 仅使用有效的日志级别：info、error、debug
       // 如果级别为“warn”，则将其视为“info”
       const mcpLevel = data.level === 'warn' ? 'info' : data.level as "info" | "error" | "debug";
   
       // 将日志消息发送到 MCP 服务器的底层服务器实例
       mcpServer.server.sendLoggingMessage({
           level: mcpLevel,
           data: data.message,
       });
   };
   

支持的日志级别

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

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

解决日志记录问题

如果您遇到与日志记录相关的错误：

1. 检查 MCP 服务器配置：确保服务器已使用正确的日志记录功能进行初始化，如上所示。

2. 验证 MCP SDK 版本：确保您使用的是支持日志记录功能结构的兼容版本的 MCP SDK。

3. 检查错误消息：查找可能指示配置问题的特定错误消息：

   • Server does not support logging (required for notifications/message)：这表明日志记录功能未正确配置。

4. 检查事件侦听器：确保正确设置了事件侦听器，以将日志从您的组件转发到 MCP 服务器。

5. 回退日志记录：在开发环境中，您可能希望在 MCP 日志记录失败时实现回退日志记录到 console.error()，但请注意这可能会使输出混乱。