@payretailers/mcp

Официальный сервер Model Context Protocol (MCP) для PayRetailers Payments API.

Превратите любого MCP-совместимого ИИ-ассистента в эксперта по интеграции с PayRetailers. Этот сервер предоставляет официальные руководства, тактические навыки, справочник по конечным точкам и инструменты интеграции (поиск, валидация для конкретных стран, плейбук вебхуков) как первоклассные MCP-ресурсы, инструменты и промпты.

Работает с Cursor, Claude Desktop, Claude Code, Windsurf, Antigravity, Zed, VS Code + Copilot, JetBrains IDEs, Continue.dev, Cline и любым другим клиентом, поддерживающим MCP через stdio.

Зачем это использовать

Когда вы устанавливаете этот сервер, ваш ИИ-ассистент перестаёт гадать о PayRetailers и начинает обращаться к первоисточнику на каждом шаге.

• Правильный код с первой попытки. Ассистент читает реальную структуру OpenAPI для каждой конечной точки (get_endpoint_spec), поэтому сгенерированный код использует фактические имена полей, типы и обязательные комбинации — а не что-то заимствованное из другого PSP.

• С учётом страны с самого начала. Спросите о PIX-платеже — и ассистент знает, что PIX доступен только в Бразилии, ожидает BRL, требует действительный 11-значный CPF, и что QR-код быстро истекает. Спросите о SPEI — и он знает, что Мексике нужен CURP или RFC, MXN, и что CLABE предоставляется асинхронно. Всё это обеспечивается через get_country_rules.

• Полезные нагрузки проверяются до попадания в песочницу. validate_payload выполняет реальную проверку контрольных сумм для CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE — плюс сквозные правила (целые младшие единицы, HTTPS-URL уведомлений, соответствие валюты и страны, совместимость метода и страны, ключи идемпотентности, матрица обязательных полей клиента, форма AmountModel для подписок, контракт повторных попыток PIX Automático). Вы ловите ошибки в редакторе, а не в ответе 400 INVALID_MODEL_SCHEMA.

• Правильно спроектированные приёмники вебхуков. get_webhook_playbook возвращает канонический словарь событий, политики повторных попыток и контракт подписи/воспроизведения. validate_webhook_handler выявляет шесть самых разрушительных анти-паттернов (подтверждение после обработки, отсутствие дедупликации по eventId, бизнес-ошибки как 500, отключённая подпись в продакшене, предположения о порядке по времени, отсутствие HTTPS) до того, как вы напишете хотя бы строку кода приёмника.

• Слэш-команды для сложных сценариев. Введите /integrate-pix-payin, /integrate-subscriptions, /implement-webhook-handler, /integrate-payout-fx, /build-checkout, /debug-401-auth или /reconcile-with-graphql — и получите реализацию, готовую к продакшену, в выбранном вами стеке.

• Ноль конфигурации, ноль сети, работает офлайн. Всё поставляется в составе релизного zip-архива. Никакого аккаунта, API-ключа или исходящих вызовов, чтобы просто ответить на вопрос о документации. Учётные данные нужны только для (планируемого) инструмента simulate_transaction.

Под капотом у вас 7 инструментов, 7 промптов, 158 документационных ресурсов (руководства + навыки + справочник + рецепты + концептуальные документы), все зеркально скопированы из репозитория payretailers-ai-docs.

Related MCP server: Payman AI Documentation MCP Server

Что он предоставляет

Ресурсы

Структурированный, удобный для LLM доступ к документации PayRetailers.

Полный список объявляется динамически при подключении — клиенты могут просматривать его через свой выбор ресурсов.

Инструменты

Действия, которые LLM может вызывать вместо предположений.

Промпты

Готовые шаблоны, которые разработчик может выбрать с помощью / в Cursor / Claude Desktop / и т.д.

Установка

Два поддерживаемых пути. Выберите один:

• Вариант A — Готовый zip-архив из GitHub Releases (рекомендуется на данный момент): не нужен аккаунт npm, не нужна компиляция, работает полностью офлайн после загрузки. Это официально поддерживаемый способ распространения, пока @payretailers/mcp ещё не опубликован на npm.

• Вариант B — Сборка из исходников: для контрибьюторов и для развёртываний с повышенными требованиями к безопасности, где нужно проверить код перед запуском.

Вариант C — установка из npm как @payretailers/mcp — запланирован, но пока недоступен. Когда пакет будет опубликован, фрагменты npx -y @payretailers/mcp в разделе Настройка по клиенту заработают без дополнительных действий.

Вариант A — Установка из GitHub Releases

Предварительные требования: Node.js 20 или новее (node --version). Больше ничего не нужно — zip-архив релиза самодостаточен.

1. Откройте страницу Releases и скачайте последний payretailers-mcp-vX.Y.Z.zip из раздела «Assets» верхнего релиза.

2. Распакуйте его в любое место. Часто используемые расположения:

   • Windows: C:\Tools\payretailers-mcp

   • macOS / Linux: ~/tools/payretailers-mcp

3. Добавьте сервер в ваш MCP-клиент (см. Настройка по клиенту ниже или пошаговые руководства по ссылкам там). Укажите абсолютный путь к dist/index.js внутри распакованной папки.

4. Перезагрузите / перезапустите ваш MCP-клиент. Сервер появится рядом с вашими остальными инструментами.

Пошаговые руководства по настройке со скриншотами и проверочными запросами:

• Cursor

• Claude Code CLI

• Claude Desktop

• VS Code + GitHub Copilot

Необязательная быстрая проверка до или после подключения — подтверждает, что сборка полностью работоспособна:

cd /path/to/payretailers-mcp-X.Y.Z
node scripts/smoke-test.mjs

Ожидаемый результат: PASS ✅ в конце, с объявленными 7 инструментами, 158 ресурсами, 7 промптами, 5 шаблонами ресурсов.

Вариант B — Сборка из исходников

Для контрибьюторов или если ваша политика безопасности требует проверить код перед запуском. Предварительные требования: Node.js 20 или новее, git.

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js (bundle + runtime deps)
npm start              # optional: run over stdio manually (Ctrl+C to stop)

data/ (Guides, Skills, Reference, Recipes, концепт-документы, курируемый JSON) включён в репозиторий — вам не нужен npm run sync:docs, если только вы не зеркалируете обновлённый checkout payretailers-ai-docs на той же машине.

Затем подключите dist/index.js к вашему MCP-клиенту так же, как в варианте A.

Настройка по клиенту

Предпочитаете полное прохождение с проверочными запросами и устранением неполадок? См. пошаговые руководства в docs/setup/ для Cursor, Claude Code, Claude Desktop и VS Code + Copilot. Фрагменты ниже — это минимальный JSON, если вы уже знаете свой клиент.

Каждый клиент принимает одни и те же три элемента информации: команду (node), массив args с абсолютным путём к dist/index.js и необязательный блок env для будущего инструмента simulate_transaction.

Замените C:/Tools/payretailers-mcp/dist/index.js ниже на абсолютный путь, куда вы распаковали релиз. В Windows используйте прямые слэши в JSON — обратные слэши нужно экранировать, и они вызывают запутанные ошибки.

Cursor

Добавьте в ~/.cursor/mcp.json (глобально) или .cursor/mcp.json (для проекта):

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"],
      "env": {
        "PAYRETAILERS_ENV": "sandbox",
        "PAYRETAILERS_SHOP_ID": "your_sandbox_shop_id",
        "PAYRETAILERS_SECRET_KEY": "your_sandbox_secret_key",
        "PAYRETAILERS_SUBSCRIPTION_KEY": "your_sandbox_subscription_key"
      }
    }
  }
}

Блок env необязателен — Resources, search_docs и все валидаторы работают без каких-либо учётных данных.

Claude Desktop

Добавьте в ваш claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Windsurf

Добавьте в ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

VS Code + Copilot

Добавьте в .vscode/mcp.json (для рабочей области) или откройте пользовательский файл через Command Palette → MCP: Open User Configuration:

{
  "servers": {
    "payretailers": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Примечание: VS Code — исключение — корневой ключ называется "servers" (а не "mcpServers"). MCP-инструменты работают только в режиме Agent в Copilot Chat.

Zed

Добавьте в ~/.config/zed/settings.json:

{
  "context_servers": {
    "payretailers": {
      "command": {
        "path": "node",
        "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
      }
    }
  }
}

Continue.dev

Добавьте в ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "payretailers",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  ]
}

JetBrains AI Assistant

Откройте Settings → AI Assistant → MCP Servers → Add и введите:

• Name: payretailers

• Command: node

• Arguments: C:/Tools/payretailers-mcp/dist/index.js (абсолютный путь)

Другие клиенты

Любой клиент, поддерживающий MCP через stdio, может использовать этот сервер. Укажите node <абсолютный-путь>/dist/index.js — и готово.

Когда npm станет доступен

Когда @payretailers/mcp будет опубликован на npm, те же конфигурации заработают с более короткой формой:

{ "command": "npx", "args": ["-y", "@payretailers/mcp"] }

Никаких изменений в env, не нужно хранить распакованную папку.

Проверка работоспособности

После перезагрузки MCP-клиента вы должны увидеть в статусе сервера примерно следующее:

7 инструментов · 158 ресурсов · 7 промптов · 5 шаблонов ресурсов

• Cursor: Ctrl+Shift+P → Customize → вкладка MCPs. Найдите payretailers с зелёной точкой и разверните его.

• Claude Desktop: проверьте панель инструментов в новом чате; инструменты PayRetailers должны появиться рядом с другими вашими MCP.

• VS Code / Zed / Continue.dev / Windsurf: обратитесь к документации каждого клиента по панели статуса MCP.

Если кажется, что ваш ассистент не вызывает инструменты, принудительно вызовите их один раз, начав промпт с «Используй PayRetailers MCP, чтобы...». После того как инструмент будет вызван один раз в беседе, ассистент обычно продолжает это делать.

Устранение неполадок

Сервер не запускается. Запустите сборку вручную из терминала:

node /path/to/payretailers-mcp/dist/index.js

Если он молча ожидает ввода — сборка в порядке, проблема на стороне клиента (опечатка в пути в конфиге, прямые слэши vs обратные в Windows, перезапущен не тот процесс). Если выводится ошибка, самые частые причины — Node < 20 (обновите Node) или повреждённая загрузка (скачайте zip заново).

Клиент показывает старые счётчики (например, 5 инструментов, 89 ресурсов). Некоторые клиенты кэшируют перечисление MCP-инструментов и ресурсов. Переключите сервер OFF → ON на панели MCP клиента или добавьте неиспользуемую запись env в конфиг (например, "MCP_VERSION": "0.4.1"), чтобы принудительно перезапустить процесс.

Модель, похоже, не вызывает ни одного MCP-инструмента. Убедитесь, что чат находится в режиме Agent (не Ask / режиме только для чтения). Некоторые лёгкие модели менее охотно вызывают инструменты — переключитесь на модель верхнего уровня для первых вызовов, и ассистент запомнит, что инструменты доступны на протяжении остальной беседы.

Где логи? У каждого MCP-клиента есть панель логов MCP, которая фиксирует JSON-RPC handshake, ошибки парсинга и stderr сервера. В Cursor: Ctrl+Shift+U → выпадающий список → MCP Logs.

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

Необязательные — требуются только для будущего инструмента simulate_transaction (фаза 4). Всё остальное (Resources, search_docs, Prompts) работает без каких-либо учётных данных.

Безопасность: сервер никогда не логирует учётные данные и не сохраняет их. Они хранятся в памяти на время сессии и отправляются только на api-sandbox.payretailers.com или api.payretailers.com, когда вы вызываете simulate_transaction.

Пример использования

После настройки задайте вашему ИИ-ассистенту вопрос на простом языке:

«Создай мой первый PIX payin в песочнице на R$50 в Бразилии. Используй Node.js.»

Под капотом ассистент:

1. Вызовет search_docs({ query: "pix payin brazil" }) → найдёт навык brazil-pix-payin.

2. Прочитает payretailers://skill/brazil-pix-payin для точных шагов.

3. Сгенерирует исполняемый код с правильным endpoint, заголовками, минорными единицами и форматом CPF.

Или используйте промпт /integrate-pix-payin напрямую для полностью структурированного ответа.

Проверка payload перед отправкой

Когда ассистент подготовил payload, он может проверить его перед обращением к API:

// tools/call → validate_payload
{
  "operation": "create-transaction",
  "country": "BR",
  "method": "PIX",
  "payload": {
    "trackingId": "abc-12345678",
    "amount": 100.50,              // will be flagged: use 10050 (minor units)
    "currency": "USD",             // will be flagged: BR expects BRL
    "notificationUrl": "http://example.com/wh", // will be flagged: must be HTTPS
    "customer": {
      "firstName": "Ana",
      "lastName": "Santos",
      "email": "ana@example.com",
      "personalId": "12345678900"  // will be flagged: invalid CPF checksum
    }
  }
}

Ответ перечисляет все проблемы с code, severity, path, message и часто с hint и suggestion — LLM может исправить payload, не тратя сетевой запрос впустую.

Разработка

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js
npm test               # 93 unit tests
node scripts/smoke-test.mjs   # end-to-end stdio handshake + tool calls
npm start              # optional: run the server manually on stdio

data/ (Guides, Skills, Reference, Recipes, концепт-документы, курируемый JSON) включён в репозиторий. Запускайте npm run sync:docs только если у вас есть checkout ../payretailers-ai-docs и вы хотите обновить зеркало.

Сервер можно проверить с помощью официального MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Релизы (для мейнтейнеров)

Релизы автоматизированы через GitHub Actions при пуше тега (v*.*.*). Процесс:

1. Запускает lint, typecheck, unit-тесты, сборку и smoke-тест.

2. Запускает npm run pack:release для создания release/payretailers-mcp-vX.Y.Z.zip (собранный dist/index.js + зеркало data/ + README + LICENSE + CHANGELOG + smoke-тест).

3. Создаёт GitHub Release и прикрепляет zip.

4. Публикует на npm как @payretailers/mcp только если настроен секрет репозитория NPM_TOKEN — в противном случае релиз доступен только на GitHub.

Чтобы выпустить релиз локально, затем запушьте тег:

# 1. Bump version in package.json, config.ts, CHANGELOG.md
# 2. Verify locally
npm run clean && npm ci && npm test && npm run build
node scripts/smoke-test.mjs
npm run pack:release        # writes release/payretailers-mcp-vX.Y.Z.zip

# 3. Commit + tag + push
git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z      # this triggers .github/workflows/release.yml

Семантическое версионирование строго соблюдается: патч-релизы исправляют ошибки, минорные релизы добавляют инструменты/промпты/ресурсы без нарушения существующих, мажорные релизы — только для переименований/удалений.

Дорожная карта

• 0.1 ✅ Resources (Guides, Skills), search_docs, промпт integrate-pix-payin.

• 0.2 ✅ Resources (Reference, Recipes), get_country_rules, get_test_data, get_endpoint_spec, промпты integrate-payout-fx, build-checkout, debug-401-auth, reconcile-with-graphql.

• 0.3 ✅ validate_payload с реальной проверкой контрольных сумм для CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE + сквозные правила (минорные единицы, валюта/страна, HTTPS webhook, метод/страна, идемпотентность).

• 0.4 ✅ Категория ресурсов концепт-документов, get_webhook_playbook, validate_webhook_handler, расширенный validate_payload для операций подписки, промпты implement-webhook-handler, integrate-subscriptions.

• 0.4.1 ✅ Выравнивание схемы подписок (AmountModel, перечисление frequency, authorizationType) — CHANGELOG.md.

• 0.5 — simulate_transaction (пробный прогон против песочницы), get_error_code, расширенное покрытие стран.

• 1.0 — Стабильный публичный релиз + включение в официальный MCP Registry + публикация на npm.

Подробности см. в CHANGELOG.md.

Связанные материалы

• Пошаговые руководства по настройке для Cursor, Claude Code, Claude Desktop и VS Code + Copilot: docs/setup/.

• Репозиторий сопутствующей документации: payretailers-dev/payretailers-ai-docs — источник Guides, Skills и зеркала документации.

• Официальная документация: www.payretailers.dev.

• Руководство по разработке с LLM: www.payretailers.dev/docs/develop-with-llms.

• Model Context Protocol: modelcontextprotocol.io.

Лицензия

Исходный код: MIT. См. LICENSE.

Документация, включённая в data/ (Guides, Skills, Reference, Recipes), лицензирована по CC BY-ND 4.0, унаследована из репозитория payretailers-ai-docs. Курируемые файлы данных (data/country-rules.json, data/test-data.json) также выпущены под CC BY-ND 4.0.

Участие в разработке

Отчёты об ошибках и запросы функций приветствуются через GitHub Issues. Pull request'ы от сообщества рассматриваются, но объединяются по усмотрению команды PayRetailers — см. CONTRIBUTING.md, когда он появится.