MyFatoorah MCP

MyFatoorah API를 위한 LLM 친화적인 Model Context Protocol 서버입니다. Claude, VS Code, Cursor 및 기타 MCP 호스트가 전용 도구를 통해 결제 수단을 탐색하고, 결제 링크를 생성하고, 결제를 검증하고, 청구서를 조회하고, 환불을 관리할 수 있게 해줍니다.

이는 공식 MyFatoorah 제품이 아닌 독립적인 커뮤니티 프로젝트입니다. 라이브 계정을 사용하기 전에 샌드박스에서 테스트하세요.

단계별 호스트 설정, Inspector 테스트, 에이전트 프롬프트, 결제 검증, 환불 및 문제 해결에 대한 자세한 내용은 사용 가이드를 참조하세요.

요구 사항

• Node.js 20 이상

• 사용하는 도구에 필요한 권한만 가진 MyFatoorah API 토큰

Related MCP server: AgentPay

설정

npm install
cp .env.example .env
npm run build

MCP 호스트의 환경에서 MYFATOORAH_API_TOKEN을 설정하세요. 서버는 .env 파일을 자동으로 로드하지 않지만, VS Code 디버그 구성은 로드합니다.

환경 변수

쿠웨이트는 바레인, 요르단, 오만의 공용 API 오리진도 포함합니다. 다중 국가 계정은 국가별로 별도의 토큰을 사용합니다.

MCP 호스트 연결

호스트 구성에서는 절대 경로를 사용하세요. /absolute/path/to/myfatoorah-mcp와 토큰 자리 표시자를 로컬에서 교체하세요.

Claude Desktop

Claude Desktop의 MCP 구성에 이 서버를 추가하세요:

{
  "mcpServers": {
    "myfatoorah": {
      "command": "node",
      "args": ["/absolute/path/to/myfatoorah-mcp/dist/index.js"],
      "env": {
        "MYFATOORAH_API_TOKEN": "YOUR_TOKEN",
        "MYFATOORAH_ENVIRONMENT": "test"
      }
    }
  }
}

구성을 저장한 후 Claude Desktop을 다시 시작하세요.

Claude Code

프로젝트 범위 구성은 .mcp.json을 사용할 수 있습니다(토큰이 포함된 경우 커밋하지 마세요):

{
  "mcpServers": {
    "myfatoorah": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/myfatoorah-mcp/dist/index.js"],
      "env": {
        "MYFATOORAH_API_TOKEN": "YOUR_TOKEN",
        "MYFATOORAH_ENVIRONMENT": "test"
      }
    }
  }
}

VS Code / GitHub Copilot

포함된 .vscode/mcp.json은 빌드된 서버를 실행하고 토큰을 안전하게 입력하도록 요청합니다. 한 번 빌드하고, MCP 서버 보기를 연 다음 myfatoorah를 시작하세요. 토큰은 저장소에 저장되지 않습니다.

Cursor 및 일반 stdio 호스트

Claude Desktop 예시와 동일한 command, args, env 값을 사용하세요. MCP 프로토콜 메시지는 stdin/stdout을 사용하며, 서버 진단 메시지는 stderr를 사용해야 합니다.

npm에 게시한 후에는 호스트가 npx -y myfatoorah-mcp로 대신 실행할 수 있습니다.

도구

서버는 또한 다음을 제공합니다:

• 리소스 myfatoorah://configuration: 환경, 기본 URL, 제한 시간 및 토큰 구성 여부 — 토큰 자체는 절대 포함하지 않습니다.

• 프롬프트 create-payment-safely: 재사용 가능한 안내형 결제 링크 워크플로입니다.

성공한 도구는 간결한 텍스트 요약과 MyFatoorah 응답이 포함된 기계 판독 가능한 structuredContent를 반환합니다.

안전한 결제 워크플로

1. myfatoorah://configuration을 읽고 테스트 환경과 라이브 환경을 확인하세요.

2. 게이트웨이를 선택하는 경우 myfatoorah_get_payment_methods를 호출하고 해당 ApiName을 사용하세요.

3. 금액, 통화, 고객, 알림 방법 및 콜백 URL을 확인하세요.

4. myfatoorah_create_payment을 호출하고 고객에게 해당 PaymentURL을 제공하세요.

5. 콜백 후 반환된 PaymentId로 myfatoorah_get_payment을 호출하세요. 리다이렉트는 결제 증거가 아닙니다. 청구서 상태 PAID와 거래 상태 SUCCESS를 요구하세요.

환불은 라이브 모드에서 실제 자금을 이동시킵니다. confirm: true를 전달하기 전에 정확한 PaymentId와 금액에 대한 명시적인 사용자 승인을 받으세요.

개발

npm run format
npm run lint
npm run typecheck
npm test
npm run build
npm run inspect

npm run inspect는 컴파일된 stdio 서버를 대상으로 공식 MCP Inspector를 시작합니다. VS Code에는 빌드/테스트 작업과 디버그 구성도 포함되어 있습니다.

테스트는 모든 MyFatoorah 요청을 모의(mock) 처리하며, 네트워크 호출을 하지 않고 토큰도 필요하지 않습니다.

보안

• 최소 권한의 MyFatoorah API 키를 사용하고 정기적으로 교체하세요.

• 자격 증명은 호스트 환경이나 비밀 관리자에 두고, 소스 제어나 모델 컨텍스트에는 절대 두지 마세요.

• 일반 요청 도구는 자격 증명 유출을 방지하기 위해 절대 URL, 프로토콜 상대 URL, 경로 탐색 및 /v2/와 /v3/ 외부의 경로를 거부합니다.

• API 오류와 Bearer 값은 모델에 도달하기 전에 마스킹됩니다.

• 지원되는 변경 작업에는 멱등성 키를, 안정적인 주문 식별자를 우선 사용하세요.

• 이 stdio 프로세스를 인증되지 않은 네트워크 서비스로 노출하지 마세요.

• 직접 카드 처리는 의도적으로 전용 도구로 모델링하지 않았으며, PCI 규정 준수가 필요합니다.

API 범위 및 참조

전용 도구는 2026년 8월 기준 MyFatoorah의 문서화된 v3 경로를 사용합니다:

• GET /v3/payment-methods

• POST /v3/payments

• GET /v3/payments/{paymentId}

• GET /v3/invoices/{invoiceId}

• GET /v3/invoices/externalIdentifier/{externalIdentifier}

• POST /v3/refunds

• GET /v3/refunds/{refundId}

참조:

• MyFatoorah API 키 및 지역 URL

• MCP TypeScript SDK v2

• Model Context Protocol 명세

라이선스

MIT