PageFly 환불 MCP 서버

Crisp의 Hugo AI 에이전트가 PageFly 환불 요청을 엔드투엔드로 처리하기 위한 MCP(Model Context Protocol) 서버입니다.

이 서버는 3개의 계층으로 그룹화된 9개의 도구를 제공합니다:

조회 (모의 데이터)

• check_subscription → 스토어 또는 이메일의 현재 플랜 확인

• get_billing_history → 스토어의 모든 청구 내역 / 예정된 결제 목록 확인

순수 로직

• classify_refund_case → 컨텍스트를 7가지 플레이북 사례(TH1–TH7) 중 하나로 매핑

• calculate_refund → 30일 일할 계산 또는 다중 주기 환불 계산 및 공제 처리

• collect_refund_info → 다음 질문 결정 및 차단 요소 파악

• generate_refund_message → PageFly 템플릿을 사용하여 고객 응답 초안 작성

상태 (Turso / libSQL)

• get_case_state → 스토어 URL로 사례 재개

• save_case_state → 모든 의미 있는 단계에서 진행 상황 저장

• list_pending_cases → 관리자, 고객 또는 결제 대기 중인 사례 검토

@modelcontextprotocol Typescript SDK로 구축되었습니다.

환경 설정

.env.example을 .env로 복사하고 Turso 자격 증명을 입력하세요:

TURSO_DATABASE_URL=libsql://<your-db>.turso.io
TURSO_AUTH_TOKEN=<token>
PORT=3000

마이그레이션은 서버 시작 시 자동으로 실행되며, 안전하게 재실행할 수 있습니다.

Related MCP server: Spaceship MCP

I. 설치 및 실행

이 MCP 서버를 시작하려면 로컬에서 실행하거나 호스팅된 버전을 사용할 수 있습니다.

호스팅된 버전 사용

이 MCP 서버는 이미 호스팅되어 있으며, 빠르게 테스트하고 싶다면 Crisp 워크스페이스에 바로 연결할 수 있습니다. 다음 주소에서 액세스할 수 있습니다: https://crisp-mcp-demo.fly.dev/mcp

로컬에서 실행

사전 요구 사항:

• Node.js 24.x 설치

• 키보드 (선택 사항이지만 권장)

1단계 — 저장소 복제

원하는 폴더에서 터미널을 열고 다음을 실행하세요:

git clone https://github.com/NTHieu002/refund-crisp-mcp.git
cd refund-crisp-mcp

2단계 — 서버 실행

서버를 빌드하고 시작하거나, 개발 모드에서 직접 실행할 수 있습니다.

서버를 빌드하고 실행하려면 다음을 사용하세요:

npm ci
npm run build
npm run start

또는 tsx(감시 모드)를 사용하여 개발 모드에서 실행하려면 다음을 사용하세요:

npm ci
npm run dev

3단계 — 서버 노출 (로컬에서 실행 시)

로컬에서 서버를 실행하려면 Crisp가 접근할 수 있도록 터널을 통해 노출해야 합니다. 이 패키지는 Cloudflared를 사용하도록 사전 구성되어 있지만, 선호하는 터널링 솔루션을 사용할 수 있습니다.

머신에 Cloudflared가 설치되어 있지 않다면, 이 링크를 따라 OS별 설치 지침을 확인하세요:

설치가 완료되면 새 터미널을 열고 다음을 실행하세요:

npm run tunnel

터널 URL을 방문하여 작동 여부를 확인할 수 있습니다. 환영 메시지가 표시되어야 합니다.

사용 가능한 스크립트

• npm run dev → 개발 서버 (감시 모드)

• npm run build → TypeScript 컴파일

• npm run start → 컴파일된 서버 실행

• npm run tunnel → Cloudflare Tunnel을 통해 localhost 노출

• npm run inspect → @modelcontextprotocol Inspector 실행

II. Crisp에 연결

이 섹션은 이 MCP 서버를 Crisp 워크스페이스에 연결하기 위한 퀵스타트 가이드입니다. 더 자세한 지침은 공식 문서를 확인하는 것을 권장합니다.

사전 요구 사항:

• Crisp 계정

• Essentials 또는 Plus 플랜의 Crisp 워크스페이스

1단계 — app.crisp.chat으로 이동

2단계 — AI Agent 메뉴에서 AI Agent → Automate → Integrations & MCP → External MCP servers로 이동한 후 Add MCP server 영역을 클릭하세요.

3단계 — MCP 서버의 URL(호스팅된/터널링된 URL 또는 호스팅된 버전)을 입력하고 Add MCP Server를 누르세요.

4단계 — MCP 서버 구성:

1. 이름 지정

2. 도구가 자동으로 가져와지지 않은 경우 Refresh tools from server 클릭

3. MCP 서버 활성화

4. Save changes 버튼 클릭

5단계 — 이제 MCP 서버가 등록되어 사용할 준비가 되었습니다!

III. MCP 서버 테스트

*여전히 Automations 메뉴에서 Playground로 이동하여 MCP 서버와 다양한 AI 모델을 테스트할 수 있습니다. 질문을 해보세요!*

Playground 예시

단일 질문:

내 주문 OID_002의 환불이 처리되었는지 확인해 줄 수 있나요?

안녕하세요, 제 계정 baptiste@acme.com에 알림이 활성화되어 있나요?

AI는 여러 도구 호출을 연결할 수 있습니다 (예: 계정 찾기, 최근 주문 나열 및 제품 세부 정보 가져오기):

내 주문 OID_001의 품목들이 아직 보증 기간 내에 있나요?

가장 최근 주문은 언제 배송되나요? 제 이메일은 chris@acme.com입니다.

부분적인 질문을 시도하고 AI가 추가 정보를 요청하도록 할 수도 있습니다:

마지막 주문 금액이 얼마였나요?

운송장 번호를 찾을 수 없는데, 도와줄 수 있나요?

사용 가능한 계정 및 주문

• chris@acme.com

  • OID_003

  • OID_006

• baptiste@acme.com

  • OID_001

  • OID_004

• dinis@acme.com

  • OID_002

  • OID_005

  • OID_007

MCP 모범 사례

MCP 설계

• 서버 설명: MCP 서버의 일반적인 목적을 설명하세요.

• 도구 명명: 명확하고 명시적인 이름을 사용하세요 (예: orderLookup 대신 get_order 사용).

• 도구 설명: 도구가 무엇을 하는지, 언제 호출해야 하는지 간결하게 설명하고, 선택적으로 사용 사례 예시를 제공하세요.

• 스키마: 올바른 사용을 보장하기 위해 도구 입력에 대한 정확한 스키마를 제공하세요.

사용자 인증

MCP 서버 구성에서 AI가 MCP 도구를 호출하기 전에 사용자가 스스로 인증하도록 선택적으로 요구할 수 있습니다. 이는 민감한 작업에 대한 보안을 강화합니다.

사용자가 아직 인증되지 않은 경우, Crisp는 AI가 MCP 도구를 호출하도록 허용하기 전에 이메일이나 SMS를 통해 OTP 코드를 전송합니다.

이를 수행하려면 MCP 서버로 이동하여 Manage를 누르세요. 각 도구에서 Require user identification verification 옵션을 토글할 수 있습니다.

서버 인증

프로덕션 환경에서는 MCP 서버에 대한 액세스를 제한하고 무단 사용을 방지하는 것이 좋습니다. 두 가지 인증 방법을 사용할 수 있습니다:

• Bearer Token: 각 요청의 Authorization 헤더에 전송되는 정적 토큰

• Basic Auth: 각 요청의 Authorization 헤더에 전송되는 사용자 이름과 비밀번호