Twilio Agent Payments MCP Server

Twilio エージェント支払い MCP サーバー

Twilio API 経由でエージェント支援による支払いを処理できるようにする MCP (Model Context Protocol) サーバー。非同期コールバックの機能が強化され、コンテキスト プロンプトによるワークフローのガイドも提供されます。

特徴

• Twilio 経由で音声通話中に安全な支払いを処理
• 支払い情報（カード番号、セキュリティコード、有効期限）を取得します
• PCIコンプライアンスのために支払い情報をトークン化する
• MCPリソース経由の非同期コールバック
• 支払いプロセスの各ステップでMCPプロンプトによるガイド付きワークフロー
• 支払い情報の再入力のサポート
• Claude DesktopなどのMCPクライアントと統合
• 安全な資格情報の取り扱い
• セキュリティ強化のためTwilio APIキーを使用
• イベントベースのログ記録アーキテクチャ

インストール

このサーバーは npx 経由で直接使用できます。

または、グローバルにインストールします。

環境パラメータ

サーバーをインストールするときは、次のパラメータを指定する必要があります。

1. コマンドライン引数（必須）:
   • accountSid : Twilio アカウントの SID
   • apiKey : Twilio APIキー
   • apiSecret : Twilio APIシークレット
2. 環境変数（サーバーを実行する前に設定）：
   • TOKEN_TYPE : 支払いに使用するトークンの種類（例：「再利用可能」、「1回限り」）
   • CURRENCY : 支払い通貨（例: 'USD'、'EUR'）
   • PAYMENT_CONNECTOR : Twilioで使用する支払いコネクタ
   • NGROK_AUTH_TOKEN : Ngrok認証トークン（コールバック処理に必要）
   • NGROK_CUSTOM_DOMAIN : Ngrok のオプションのカスタムドメイン

環境変数を使用した例:

これらのパラメータの詳細については、以下の構成セクションを参照してください。

構成

サーバーには次のパラメータが必要です。

• accountSid : Twilio アカウントの SID (「AC」で始まる必要があり、検証されます)
• apiKey : Twilio API キー ('SK' で始まる)
• apiSecret : Twilio APIシークレット

環境変数

構成には次の環境変数が使用されます。

• TOKEN_TYPE : 支払いに使用するトークンの種類（例：「再利用可能」、「1回限り」）
• 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 ) に以下を追加します。

値を実際の Twilio の資格情報と設定に置き換えます。

npmに公開した後

パッケージが npm に公開されると、次の構成を使用できます。

ホストアプリケーションとの統合

モデルコンテキストプロトコル（MCP）の主な利点の一つは、LLMコンテキストの詳細な手動設定が不要になることです。MCPサーバーは、LLMクライアントに必要なすべてのツール定義、リソーステンプレート、および機能を自動的に提供します。

ホストアプリケーションの設定

この MCP サーバーを独自のホスト アプリケーションに統合するには:

1. MCP クライアントを実装する: 既存の MCP クライアント ライブラリを使用するか、アプリケーションに MCP クライアント プロトコルを実装します。
2. MCP サーバーに接続: Twilio Agent Payments MCP サーバーに接続するようにアプリケーションを構成します。
3. 残りはプロトコルに任せましょう: MCP サーバーは自動的に次の処理を行います。
   • ツールとリソースをクライアントに登録する
   • すべてのツールに入力スキーマを提供する
   • 支払いフローを通じて LLM をガイドするためのコンテキストプロンプトを提供する

LLM のコンテキストではツールやリソースを手動で定義する必要はありません。MCP プロトコルがこの検出を自動的に処理します。

統合コードの例

MCP クライアントと統合する方法の簡略化された例を次に示します。

最小限のLLMコンテキストが必要

LLMは、支払い処理にTwilio Agent Payments MCPサーバーを使用できることを認識するだけで済みます。システムプロンプトに簡単な指示を入力するだけで十分です。

MCP サーバー自体は、支払いフローを通じて LLM をガイドするための詳細なツール定義、入力スキーマ、およびコンテキスト プロンプトをすべて提供します。

開発者実装ノート

このセクションでは、使用されるアーキテクチャ パターンに焦点を当てて、MCP サーバーの実装がさまざまなコンポーネントとファイルにわたってどのように構成されているかについて説明します。

コンポーネントの構成

サーバーの実装は複数のディレクトリに分割されています。

1. src/index.ts : 次のメイン エントリ ポイント:
   • MCPサーバーを初期化します
   • TwilioAgentPaymentServerシングルトンを初期化します
   • 自動検出により、すべてのコンポーネントをMCPサーバーで検出して登録します。
   • ログ記録用のイベントリスナーを設定する
   • サーバーをトランスポート層に接続する
2. src/tools/ : 個々のツールの実装が含まれています
   • 各ツールは、名前、説明、形状、実行プロパティを持つオブジェクトを返すファクトリー関数として実装されています。
   • ツールは特定の支払い操作を処理します（例：StartPaymentCaptureTool、CaptureCardNumberTool）
   • 各ツールはZodを使用して入力スキーマを定義し、実行メソッドを実装します。
   • ツールは getInstance() を介して TwilioAgentPaymentServer シングルトンにアクセスします。
3. src/prompts/ : プロンプトの実装が含まれています
   • 各プロンプトは、名前、説明、実行プロパティを持つオブジェクトを返すファクトリー関数として実装されています。
   • プロンプトは、支払いフローの各ステップについて LLM に状況に応じたガイダンスを提供します。
   • 一部のプロンプトは、プロンプトの内容をカスタマイズするために使用できるパラメータを受け入れます。
4. src/resources/ : リソース実装が含まれています
   • リソースはデータへのアクセスを提供します（例：PaymentStatusResource）
   • 各リソースは、名前、テンプレート、説明、読み取りプロパティを持つオブジェクトを返すファクトリー関数として実装されています。
   • リソースは getInstance() を介して TwilioAgentPaymentServer シングルトンにアクセスします。
5. src/api-servers/ : Twilio APIクライアントの実装が含まれています
   • TwilioAgentPaymentServerをシングルトンとして実装する
   • Twilio APIとの通信を処理します
   • 支払いセッションの状態を管理する
   • シングルトンインスタンスにアクセスするための静的メソッドを提供します
6. src/utils/ : ユーティリティ関数が含まれています
   • autoDiscovery.tsファイルは、ツール、プロンプト、リソースの自動検出と登録を処理します。

TwilioAgentPaymentServer のシングルトンパターン

このコードベースの重要なアーキテクチャ パターンは、TwilioAgentPaymentServer のシングルトン パターンの使用です。

このアプローチの利点:

• アプリケーション全体でTwilioAgentPaymentServerのインスタンスが1つだけであることを保証します
• インスタンスを複数の関数に渡す必要がなくなります
• よりシンプルな関数シグネチャでよりクリーンなAPIを提供します
• コードベースのどこからでもTwilioAgentPaymentServerにアクセスしやすくなります

ファクトリー関数パターン

ツール、プロンプト、リソースは、ファクトリ関数パターンを使用して実装されます。

1. ツール内:
   // Example from StartPaymentCaptureTool.ts export function startPaymentCaptureTool() { // Get the TwilioAgentPaymentServer instance const twilioAgentPaymentServer = TwilioAgentPaymentServer.getInstance(); // Create an event emitter for logging const emitter = new EventEmitter(); return { name: "startPaymentCapture", description: "Start a new payment capture session", shape: schema.shape, execute: async function execute(params: z.infer<typeof schema>, extra: any): Promise<ToolResult> { // Implementation that calls Twilio API and returns result }, emitter // For attaching event listeners } }
2. リソース:
   // Example from PaymentStatusResource.ts export function paymentStatusResource() { // Get the TwilioAgentPaymentServer instance const twilioAgentPaymentServer = TwilioAgentPaymentServer.getInstance(); // Create an event emitter for logging const emitter = new EventEmitter(); return { name: "PaymentStatus", template: new ResourceTemplate("payment://{callSid}/{paymentSid}/status", { list: undefined }), description: "Get the current status of a payment session", read: async (uri: URL, variables: Record<string, string | string[]>, extra: any): Promise<ResourceReadResult> => { // Implementation that retrieves and formats payment status data }, emitter // For attaching event listeners }; }
3. プロンプトの場合：
   // Example from a prompt factory function export function startCapturePrompt() { return { name: "StartCapture", description: "Prompt for starting the payment capture process", execute: (args: { callSid: string }, extra: RequestHandlerExtra): GetPromptResult | Promise<GetPromptResult> => { // Return prompt content } }; }

自動検出と登録

サーバーは自動検出メカニズムを使用して、すべてのコンポーネントを検索して登録します。

このアプローチ:

• すべてのツール、プロンプト、リソースをそれぞれのディレクトリ内で自動的に検索します
• 動的にインポートしてMCPサーバーに登録します
• メインファイルを変更せずに新しいコンポーネントを簡単に追加できます
• 定型コードを削減し、保守性を向上させる

プロンプトのパラメータ

一部のプロンプトは、プロンプトの内容をカスタマイズするためのパラメータを受け入れます。StartCapturePrompt はその良い例です。

1. パラメータ定義:
   // In the prompt factory function return { name: "StartCapture", description: "Prompt for starting the payment capture process", schema: { callSid: z.string().describe("The Twilio Call SID") }, // Parameter schema execute: (args: { callSid: string }, extra: RequestHandlerExtra) => { // Implementation } };
   • スキーマプロパティは、Zodを使用してパラメータスキーマを定義します。
   • この場合、文字列型のcallSidパラメータが必要です。
2. プロンプトでのパラメータの使用:
   execute: (args: { callSid: string }, extra: RequestHandlerExtra): GetPromptResult | Promise<GetPromptResult> => { const { callSid } = args; if (!callSid) { throw new Error("callSid parameter is required"); } return { messages: [ { role: "assistant", content: { type: "text", text: getStartCapturePromptText(callSid), // Use the parameter in the prompt text } } ] }; }
   • 実行メソッドは最初の引数としてパラメータを受け取ります
   • パラメータを検証し、それを使用してプロンプトのコンテンツをカスタマイズできます。
   • この場合、callSidはコンテキストを提供するためにプロンプトテキストで使用されます。

このパターンにより、プロンプトを動的かつ状況に応じて変更し、支払いフローの現在の状態に基づいてカスタマイズされたガイダンスを提供できるようになります。

利用可能なツール

支払いキャプチャ開始

アクティブな通話の支払いキャプチャ プロセスを開始します。

パラメータ:

• callSid : アクティブな通話のTwilio通話SID

重要: StartCapturePrompt.ts では、MCP クライアント側からユーザーがコール SID を入力する必要があります。これは必須パラメータであり、入力されていない場合はプロンプトでエラーが発生します。

注: Twilio 通話を処理する際は、どのコールレグ（Call SID）を使用しているかを把握する必要があります。Twilio Payments は PSTN 側のコールレグにアタッチする必要があります。Twilio クライアント側に適用した場合、DTMF 番号はキャプチャされません。そのため、この MCP サーバーは正しいコールレグが使用されていると想定します。通常、以下の手順で確認されます。

戻り値:

• paymentSid : 新しい支払いセッションのTwilio支払いSID

キャプチャカード番号

支払いカード番号のキャプチャを開始します。

パラメータ:

• callSid : アクティブな通話のTwilio通話SID
• paymentSid : 支払いセッションのTwilio支払いSID
• captureType : 「支払いカード番号」に設定

戻り値:

• カード番号取得操作の状況

キャプチャセキュリティコード

カードセキュリティコードのキャプチャを開始します。

パラメータ:

• callSid : アクティブな通話のTwilio通話SID
• paymentSid : 支払いセッションのTwilio支払いSID
• captureType : 「セキュリティコード」に設定

戻り値:

• セキュリティコードキャプチャ操作のステータス

キャプチャ有効期限

カード有効期限の取得を開始します。

パラメータ:

• callSid : アクティブな通話のTwilio通話SID
• paymentSid : 支払いセッションのTwilio支払いSID
• captureType : 'expiration-date' に設定

戻り値:

• 有効期限取得操作のステータス

完全な支払いキャプチャ

支払いキャプチャセッションを完了します。

パラメータ:

• callSid : アクティブな通話のTwilio通話SID
• paymentSid : 支払いセッションのTwilio支払いSID

戻り値:

• 支払い完了操作のステータス

利用可能なリソース

支払い://{callSid}/{paymentSid}/status

決済セッションの現在のステータスをJSONオブジェクトとして取得します。このリソースは、決済キャプチャプロセスの現在の状態に関する詳細な情報を提供します。これには以下が含まれます。

• 支払いSID
• 支払いカード番号（マスク）
• 支払いカードの種類
• セキュリティコードのステータス
• 有効期限
• 支払い確認コード
• 支払い結果
• 支払いトークン

MCPプロンプト

サーバーは、支払いフローの各ステップで LLM をガイドするためのコンテキスト プロンプトを提供します。

キャプチャ開始プロンプト

支払いキャプチャプロセスを開始する方法に関するガイダンスを提供します。これには以下が含まれます。

• 顧客に支払い情報を提供する準備ができているかどうかを確認する手順
• 安全な処理とトークン化の説明
• startPaymentCaptureツールの使用手順
• 重要: ユーザーはMCPクライアント側からコールSIDを入力する必要があります。これは必須パラメータです。

カード番号プロンプト

LLM にカード番号取得プロセスの処理方法を指導します。これには次の内容が含まれます。

• 顧客に必要な情報を説明する手順
• 顧客の質問や懸念に対処するためのヒント
• キャプチャカード番号ツールの使用手順

セキュリティコードプロンプト

カード セキュリティ コードの取得に関する次のようなガイダンスを提供します。

• セキュリティコードの説明
• 顧客の質問や懸念に対処するためのヒント
• キャプチャセキュリティコードツールの使用手順

有効期限プロンプト

LLM にカードの有効期限の取得について以下のガイドを提供します:

• 必要な形式（MM/YY）の説明手順
• 顧客の質問や懸念に対処するためのヒント
• captureExpirationDateツールの使用手順

キャプチャ完了プロンプト

支払いキャプチャプロセスを完了するためのガイダンスを提供します。これには以下が含まれます。

• すべての情報が収集されたことを確認するための手順
• completePaymentCaptureツールの使用手順

完了プロンプト

支払いが正常に処理された後に行うべきことについて LLM にガイドします。これには次の内容が含まれます。

• 支払いが成功したことを確認するための手順
• 会話の次のステップの提案

エラープロンプト

支払いキャプチャプロセス中のエラーの処理に関するガイダンスを提供します。

• 顧客にエラーを説明する手順
• よくある問題のトラブルシューティングの提案
• 支払いキャプチャプロセスを再試行する手順

建築

この MCP サーバーは、支払いフローを処理するための強化されたアーキテクチャを実装します。

イベントベースアーキテクチャ

サーバーは、コンポーネント間の通信に EventEmitter を使用したイベントベースのアーキテクチャを使用します。

• 各ツール、リソース、サーバーコンポーネントはEventEmitterを拡張します
• コンポーネントはログとコールバックのイベントを発行します
• イベントリスナーはログをMCPサーバーのログシステムに転送します。

コールバック処理

サーバーは、@deshartman/mcp-status-callback パッケージを使用して、Twilio からの非同期コールバックを処理します。

• コールバックを受信するためにNgrokを使用して安全なトンネルを作成します
• さまざまな支払い段階のコールバックを処理します
• コールバックデータに基づいて状態ストアを更新します
• エラー状態と再入シナリオを処理する

状態管理

支払い状態はマップベースのストアを通じて管理されます。

• statusCallbackMapは支払いSIDでインデックスされた支払いセッションデータを保存します
• 各コールバックは最新の情報で状態を更新します
• PaymentStatusResourceはこの状態データへのアクセスを提供します

MCP統合

サーバーは、次の方法で MCP プロトコルと統合します。

• ツール: 入力検証用の Zod スキーマで定義
• リソース: 支払い状態データへのアクセスの提供
• プロンプト: 支払いフローの各ステップのコンテキストガイダンス
• ログ記録: MCP サーバーに転送されるイベントベースのログ記録

発達

プロジェクトをビルドするには:

前提条件

• Node.js 18歳以上
• Express（コールバック処理用）
• Twilio SDK
• 認証トークンを持つNgrokアカウント

サーバーを手動で実行する

テストのためにサーバーを手動で起動するには (Claude Desktop の外部):

サーバーが起動し、MCP クライアントの接続を待機します。

Claude Desktop と併用する場合、Claude が設定ファイルを読み込むとサーバーが自動的に起動します。手動で起動する必要はありません。

PCIコンプライアンス

このサーバーは、決済カード情報をトークン化することでPCIコンプライアンスに準拠します。実際のカードデータはTwilioによって処理され、お客様のシステムに保存されることはありません。TwilioのPCIコンプライアンスに関する詳細は、 Twilioの安全な決済に関するドキュメントをご覧ください。

ライセンス

マサチューセッツ工科大学

MCPインスペクターの互換性

このサーバーをMCPインスペクターと併用する場合、すべてのログ記録console.log()ではなくMCPログ機能を介して行われることに注意してください。これは意図的な動作であり、JSON通信にstdoutを使用するMCPプロトコルとの互換性を保つために必要です。

このサーバーを拡張したり、問題をデバッグしたりする場合:

1. LOG_EVENTイベントを発行してイベントベースのログシステムを使用する
2. console.log()の使用は避けてください。MCP プロトコルの JSON メッセージが標準出力に表示されるためです。
3. MCPコンテキスト外でデバッグする場合は、stderrに出力するconsole.error()を使用できます。

イベントベースのログアーキテクチャ

サーバーはイベントベースのログ記録アーキテクチャを使用します。

1. イベント エミッター: すべてのツール クラスとリソース クラスは Node.js のEventEmitterを拡張し、レベルとメッセージ データを含む「ログ」イベントを出力します。
2. ログ転送: これらのイベントはイベント リスナーによってキャプチャされ、MCP サーバーのログ システムに転送されます。
   // Set up event listeners for tool logs startPaymentCaptureTool.on(LOG_EVENT, logToMcp); captureCardNumberTool.on(LOG_EVENT, logToMcp); // ... other tools
3. MCP 統合: logToMcp関数は、これらのイベントを MCP 互換のログ メッセージに変換します。
   const logToMcp = (data: { level: string, message: string }) => { // Only use valid log levels: info, error, debug // If level is 'warn', treat it as 'info' const mcpLevel = data.level === 'warn' ? 'info' : data.level as "info" | "error" | "debug"; // Send the log message to the MCP server's underlying Server instance mcpServer.server.sendLoggingMessage({ level: mcpLevel, data: data.message, }); };

サポートされているログレベル

サーバーは次のログ レベルをサポートしています。

• info : 一般情報メッセージ
• error : エラーメッセージと例外
• debug : 詳細なデバッグ情報
• warn : 警告メッセージ（MCP 互換性のため自動的に 'info' に変換されます）

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

サーバーは、Twilio からの 2 つの主な種類のコールバック データを処理します。

初期コネクタデータ

支払いセッションが最初に作成されると、Twilio はコネクタ データを送信します。

データのキャプチャ

支払い情報が取得されると、Twilio は更新されたデータを送信します。

サーバーは、このデータを支払い SID でインデックス付けして statusCallbackMap に保存し、PaymentStatusResource を通じて利用できるようにします。