MyFatoorah MCP

Удобный для LLM сервер Model Context Protocol для MyFatoorah API. Он позволяет 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

Задайте MYFATOORAH_API_TOKEN в окружении MCP-хоста. Сервер не загружает .env автоматически; это делает конфигурация отладки VS Code.

Переменные окружения

Кувейт также покрывает общую точку API Бахрейна, Иордании и Омана. В мультистрановых аккаунтах используется отдельный токен для каждой страны.

Подключение MCP-хоста

Используйте абсолютный путь в конфигурациях хоста. Замените /absolute/path/to/myfatoorah-mcp и заполнитель токена локально.

Claude Desktop

Добавьте этот сервер в MCP-конфигурацию Claude Desktop:

{
  "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-хосты

Используйте те же значения command, args и env, что и в примере для Claude Desktop. Сообщения протокола MCP используют stdin/stdout; диагностика сервера должна использовать stderr.

После публикации в npm хосты могут вместо этого запускать его с помощью npx -y myfatoorah-mcp.

Инструменты

Сервер также предоставляет:

• Ресурс myfatoorah://configuration: окружение, базовый URL, тайм-аут и факт настройки токена — но не сам токен.

• Промпт create-payment-safely: многоразовый пошаговый процесс создания платёжных ссылок.

Успешные инструменты возвращают краткую текстовую сводку, а также машиночитаемый structuredContent, содержащий ответ MyFatoorah.

Безопасный процесс оплаты

1. Прочитайте myfatoorah://configuration и убедитесь, какой режим используется: тестовый или боевой.

2. Если выбираете платёжный шлюз, вызовите myfatoorah_get_payment_methods и используйте его ApiName.

3. Подтвердите сумму, валюту, покупателя, способ уведомления и URL обратного вызова.

4. Вызовите myfatoorah_create_payment и передайте покупателю его PaymentURL.

5. После обратного вызова вызовите myfatoorah_get_payment с полученным PaymentId. Перенаправление не является доказательством оплаты; требуется статус счёта PAID и статус транзакции SUCCESS.

Возвраты переводят деньги в боевом режиме. Получите явное подтверждение пользователя на конкретный PaymentId и сумму, прежде чем передавать confirm: true.

Разработка

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

npm run inspect запускает официальный MCP Inspector для скомпилированного stdio-сервера. VS Code также включает задачи сборки/тестирования и конфигурацию отладки.

Тесты имитируют все запросы MyFatoorah; они не выполняют сетевых вызовов и не требуют токена.

Безопасность

• Используйте ключ MyFatoorah API с минимальными привилегиями и регулярно меняйте его.

• Размещайте учётные данные в окружении хоста или в менеджере секретов, но никогда в системе контроля версий или в контексте модели.

• Универсальный инструмент запросов отклоняет абсолютные URL, протокол-относительные URL, обход каталога и пути за пределами /v2/ и /v3/, чтобы предотвратить утечку учётных данных.

• Ошибки API и значения Bearer вырезаются до того, как попадут к модели.

• Отдавайте предпочтение ключам идемпотентности для поддерживаемых изменяющих операций и стабильным идентификаторам заказов.

• Не предоставляйте этот stdio-процесс как неаутентифицированный сетевой сервис.

• Прямая обработка карт намеренно не реализована в виде специализированного инструмента; она требует соответствия PCI.

Область API и справочные материалы

Специализированные инструменты используют документированные маршруты v3 MyFatoorah по состоянию на август 2026 года:

• 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