Twilio Agent Payments MCP Server

Twilio Agent Payments MCP 서버

Twilio API를 통해 에이전트 지원 결제를 처리할 수 있는 MCP(모델 컨텍스트 프로토콜) 서버로, 비동기 콜백과 상황에 맞는 프롬프트를 통한 안내 워크플로우를 위한 향상된 기능을 제공합니다.

특징

• Twilio를 통해 음성 통화 중에 안전한 결제를 처리하세요
• 결제 정보(카드 번호, 보안 코드, 만료일)를 수집합니다.
• PCI 규정 준수를 위한 결제 정보 토큰화
• MCP 리소스를 통한 비동기 콜백
• 결제 프로세스의 각 단계에 대한 MCP 프롬프트를 사용한 가이드 워크플로
• 결제 정보 재입력 지원
• Claude Desktop과 같은 MCP 클라이언트와 통합됩니다.
• 보안 자격 증명 처리
• 보안 강화를 위해 Twilio API 키를 사용합니다.
• 이벤트 기반 로깅 아키텍처

설치

npx를 통해 이 서버를 직접 사용할 수 있습니다.

지엑스피1

또는 전역적으로 설치하세요.

환경 매개변수

서버를 설치할 때 다음 매개변수를 제공해야 합니다.

1. 명령줄 인수 (필수):
   • accountSid : Twilio 계정 SID
   • apiKey : Twilio API 키
   • apiSecret : Twilio API 비밀번호
2. 환경 변수 (서버 실행 전에 설정):
   • TOKEN_TYPE : 결제에 사용할 토큰 유형(예: '재사용 가능', '일회용')
   • 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 : 결제에 사용할 토큰 유형(예: '재사용 가능', '일회용')
• 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에 대한 Singleton 패턴을 사용하는 것입니다.

이 접근 방식의 이점:

• 애플리케이션 전체에서 TwilioAgentPaymentServer 인스턴스가 하나만 있는지 확인합니다.
• 여러 함수를 통해 인스턴스를 전달할 필요성이 없어집니다.
• 더 간단한 함수 서명으로 더 깔끔한 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 통화를 처리할 때는 어떤 통화 레그(leg)의 통화 SID를 사용하는지 파악해야 합니다. Twilio Payments는 PSTN 측 통화 레그에 연결해야 합니다. Twilio 클라이언트 측에 적용되는 경우 DTMF 숫자가 캡처되지 않습니다. 따라서 이 MCP 서버는 올바른 통화 레그가 사용되고 있다고 가정합니다. 일반적으로 다음과 같이 확인합니다.

보고:

• paymentSid : 새로운 결제 세션에 대한 Twilio 결제 SID

캡처카드번호

결제 카드 번호 캡처를 시작합니다.

매개변수:

• callSid : 활성 호출에 대한 Twilio 호출 SID
• paymentSid : 결제 세션에 대한 Twilio 결제 SID
• captureType : '결제 카드 번호'로 설정

보고:

• 카드번호 캡처 작업 상태

captureSecurityCode

카드 보안 코드 캡처를 시작합니다.

매개변수:

• callSid : 활성 호출에 대한 Twilio 호출 SID
• paymentSid : 결제 세션에 대한 Twilio 결제 SID
• captureType : 'security-code'로 설정

보고:

• 보안 코드 캡처 작업 상태

캡처만료일

카드 만료일 캡처를 시작합니다.

매개변수:

• callSid : 활성 호출에 대한 Twilio 호출 SID
• paymentSid : 결제 세션에 대한 Twilio 결제 SID
• captureType : '만료일'로 설정

보고:

• 만료일 캡처 작업 상태

결제 완료 캡처

결제 캡처 세션을 완료합니다.

매개변수:

• callSid : 활성 호출에 대한 Twilio 호출 SID
• paymentSid : 결제 세션에 대한 Twilio 결제 SID

보고:

• 결제 완료 작업 상태

사용 가능한 리소스

결제://{callSid}/{paymentSid}/상태

결제 세션의 현재 상태를 JSON 객체로 가져옵니다. 이 리소스는 다음을 포함하여 결제 캡처 프로세스의 현재 상태에 대한 자세한 정보를 제공합니다.

• 결제 SID
• 결제 카드 번호(마스킹)
• 결제 카드 종류
• 보안 코드 상태
• 유효기간
• 결제 확인 코드
• 결제 결과
• 결제 토큰

MCP 프롬프트

서버는 LLM이 결제 흐름의 각 단계를 안내할 수 있도록 상황에 맞는 프롬프트를 제공합니다.

캡처 시작 프롬프트

다음을 포함하여 결제 수집 프로세스를 시작하는 방법에 대한 지침을 제공합니다.

• 고객에게 결제 정보를 제공할 준비가 되었는지 묻는 지침
• 보안 처리 및 토큰화에 대한 설명
• startPaymentCapture 도구를 사용하는 단계
• 중요 : 사용자는 MCP 클라이언트 측에서 호출 SID를 입력해야 합니다. 이는 필수 매개변수입니다.

카드번호 프롬프트

다음을 포함하여 카드 번호 수집 프로세스를 처리하는 방법에 대한 LLM 지침을 제공합니다.

• 고객에게 필요한 정보를 설명하기 위한 지침
• 고객 질문이나 우려 사항을 처리하기 위한 팁
• captureCardNumber 도구를 사용하는 단계

보안 코드 프롬프트

다음을 포함하여 카드 보안 코드를 캡처하는 방법에 대한 지침을 제공합니다.

• 보안 코드가 무엇인지 설명하는 지침
• 고객 질문이나 우려 사항을 처리하기 위한 팁
• captureSecurityCode 도구를 사용하는 단계

만료일 프롬프트

다음을 포함하여 카드 만료일을 파악하는 방법에 대한 LLM 지침을 제공합니다.

• 필요한 형식(MM/YY)을 설명하기 위한 지침
• 고객 질문이나 우려 사항을 처리하기 위한 팁
• captureExpirationDate 도구를 사용하는 단계

캡처 완료 프롬프트

다음을 포함하여 결제 수집 프로세스를 완료하는 방법에 대한 지침을 제공합니다.

• 모든 정보가 수집되었는지 확인하기 위한 지침
• completePaymentCapture 도구를 사용하는 단계

완료 프롬프트

결제가 성공적으로 처리된 후 LLM이 수행해야 할 작업에 대해 안내합니다. 여기에는 다음이 포함됩니다.

• 결제 성공 확인 안내
• 대화의 다음 단계에 대한 제안

오류 프롬프트

다음을 포함하여 결제 수집 프로세스 중 발생하는 오류를 처리하는 방법에 대한 지침을 제공합니다.

• 고객에게 오류를 설명하기 위한 지침
• 일반적인 문제 해결을 위한 제안
• 결제 캡처 프로세스를 다시 시도하기 위한 단계

건축학

이 MCP 서버는 결제 흐름을 처리하기 위한 향상된 아키텍처를 구현합니다.

이벤트 기반 아키텍처

서버는 구성 요소 간 통신을 위해 EventEmitter를 사용하는 이벤트 기반 아키텍처를 사용합니다.

• 각 도구, 리소스 및 서버 구성 요소는 EventEmitter를 확장합니다.
• 구성 요소는 로깅 및 콜백을 위해 이벤트를 방출합니다.
• 이벤트 리스너는 로그를 MCP 서버의 로깅 시스템으로 전달합니다.

콜백 처리

서버는 @deshartman/mcp-status-callback 패키지를 사용하여 Twilio의 비동기 콜백을 처리합니다.

• Ngrok을 사용하여 콜백을 수신하기 위한 보안 터널을 생성합니다.
• 다양한 결제 단계에 대한 콜백을 처리합니다.
• 콜백 데이터를 기반으로 상태 저장소를 업데이트합니다.
• 오류 조건 및 재진입 시나리오를 처리합니다.

국가 관리

결제 상태는 지도 기반 스토어를 통해 관리됩니다.

• statusCallbackMap은 결제 SID로 인덱싱된 결제 세션 데이터를 저장합니다.
• 각 콜백은 최신 정보로 상태를 업데이트합니다.
• PaymentStatusResource는 이 상태 데이터에 대한 액세스를 제공합니다.

MCP 통합

서버는 다음을 통해 MCP 프로토콜과 통합됩니다.

• 도구: 입력 검증을 위해 Zod 스키마로 정의됨
• 리소스: 결제 상태 데이터에 대한 액세스 제공
• 프롬프트: 결제 흐름의 각 단계에 대한 상황별 안내
• 로깅: 이벤트 기반 로깅이 MCP 서버로 전달됨

개발

프로젝트를 빌드하려면:

필수 조건

• 노드.js 18+
• Express(콜백 처리용)
• 트윌리오 SDK
• 인증 토큰이 있는 Ngrok 계정

수동으로 서버 실행

테스트를 위해 서버를 수동으로 시작하려면(Claude Desktop 외부):

서버가 시작되어 MCP 클라이언트 연결을 기다립니다.

Claude Desktop과 함께 사용하는 경우, Claude가 구성 파일을 로드하면 서버가 자동으로 시작됩니다. 수동으로 시작할 필요가 없습니다.

PCI 규정 준수

이 서버는 결제 카드 정보를 토큰화하여 PCI 규정 준수를 지원합니다. 실제 카드 데이터는 Twilio에서 처리되며 시스템에 저장되지 않습니다. Twilio의 PCI 규정 준수에 대한 자세한 내용은 Twilio의 보안 결제 관련 문서를 참조하세요.

특허

MIT

MCP 검사기 호환성

이 서버를 MCP Inspector와 함께 사용할 경우, 모든 로깅은 console.log() 대신 MCP 로깅 기능을 통해 수행됩니다. 이는 JSON 통신에 stdout을 사용하는 MCP 프로토콜과의 호환성을 위해 의도적으로 설정된 기능입니다.

이 서버를 확장하거나 문제를 디버깅하는 경우:

1. LOG_EVENT 이벤트를 내보내 이벤트 기반 로깅 시스템을 사용합니다.
2. MCP 프로토콜의 stdout JSON 메시지를 방해할 수 있으므로 console.log() 사용하지 마십시오.
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 호환성을 위해 자동으로 '정보'로 변환됨)

결제 콜백 데이터 구조

서버는 Twilio에서 두 가지 주요 유형의 콜백 데이터를 처리합니다.

초기 커넥터 데이터

결제 세션이 처음 생성되면 Twilio는 커넥터 데이터를 보냅니다.

데이터 캡처

결제 정보가 수집되면 Twilio는 업데이트된 데이터를 전송합니다.

서버는 이 데이터를 결제 SID로 인덱싱된 statusCallbackMap에 저장하고 PaymentStatusResource를 통해 사용할 수 있도록 합니다.