YooKassa MCP Server

ЮKassa: ИИ-агент технической интеграции для Codex

Устанавливаемый Codex-плагин, который помогает разработчику:

• спроектировать платежный flow;
• написать интеграцию под стек проекта;
• проверить запросы по OpenAPI без отправки;
• спроектировать и проверить чеки с учетом технических требований 54-ФЗ;
• провести read-only диагностику тестового магазина;
• сделать code review существующей интеграции.

Это развитие ранее созданного YooKassa MCP. MVP намеренно исключает финансовые write-инструменты: агент не создает, не подтверждает, не отменяет платежи, не делает возвраты и не меняет webhook. Такой код агент пишет и тестирует в приложении разработчика, а MCP дает документацию, офлайн-валидацию и безопасную диагностику.

Что входит

Пять skills:

| Skill | Назначение | |---|---| | integration-planner | Архитектура, статусы, идемпотентность, webhook, чеки и тест-план | | implementation | Production-код интеграции и тесты под текущий стек | | receipts-54fz | Техническая проверка чеков, ФФД и маркировки | | diagnostics | Диагностика только тестового магазина | | integration-review | Ревью безопасности, корректности и готовности к запуску |

Тринадцать read-only MCP tools:

yookassa_search_documentation
yookassa_api_search
yookassa_api_details
yookassa_validate_request
yookassa_explain_error
yookassa_diagnose_connection
yookassa_get_payment
yookassa_list_payments
yookassa_get_refund
yookassa_list_refunds
yookassa_get_receipt
yookassa_list_receipts
yookassa_get_payment_method

Установка в Codex из GitHub

После merge в main:

codex plugin marketplace add Belolipetsky/YooKassa-MCP --ref main
codex plugin add yookassa-integration-agent@yookassa

Для проверки текущего draft PR:

codex plugin marketplace add Belolipetsky/YooKassa-MCP --ref codex/yookassa-integration-plugin
codex plugin add yookassa-integration-agent@yookassa

После установки откройте новую задачу Codex, чтобы skills и MCP появились в контексте.

Тестовый магазин

Офлайн-поиск, проектирование и валидация работают без ключей. Для живой read-only диагностики задайте реквизиты именно тестового магазина до запуска Codex:

export YOOKASSA_SHOP_ID="<shopId тестового магазина>"
export YOOKASSA_SECRET_KEY="<secret key тестового магазина>"
codex

Плагин проверяет среду по официальному признаку test=true в объекте платежа:

• test=true — диагностика разрешена;
• пустой магазин — соединение подтверждено, тестовый режим еще не подтвержден;
• test=false — данные не возвращаются, процесс блокируется до замены реквизитов и перезапуска Codex.

Секреты не передаются в skill-промпты и не выводятся MCP-инструментами.

Примеры запросов

Спроектируй интеграцию ЮKassa для подписки в этом Next.js-проекте.
Реализуй двухстадийный платеж с идемпотентностью и webhook.
Проверь JSON платежа и чека перед тестовым запросом.
Проведи диагностику тестового магазина: почему платеж остался pending?
Проверь частичный возврат и связанный чек.
Сделай ревью интеграции ЮKassa перед запуском.

Локальная разработка

cd plugins/yookassa-integration-agent/server
npm ci
npm run check
npm test
npm run build
node --check dist/index.js

Сборка создает один server/dist/index.js. Он включается в git, поэтому пользователю плагина не нужен npm install.

Проверка skills и manifests:

python3 "$HOME/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py" \
  plugins/yookassa-integration-agent

for skill in plugins/yookassa-integration-agent/skills/*; do
  python3 "$HOME/.codex/skills/.system/skill-creator/scripts/quick_validate.py" "$skill"
done

node scripts/validate-plugin.mjs

Источники

• API ЮKassa
• OpenAPI ЮKassa
• Формат взаимодействия и идемпотентность
• Webhook ЮKassa
• Тестирование
• Чеки
• 54-ФЗ через ЮKassa
• 54-ФЗ на сайте ФНС
• Stripe: Agents and AI
• Stripe: Agent skills
• Stripe MCP

Полный реестр источников и правила работы агента находятся в AGENTS.md.

Ограничения

• Плагин не выполняет финансовые операции.
• MCP поддерживает только stdio и не поднимает HTTP-сервер.
• Каталог API — проверенная выборка из официального OpenAPI-снимка от 29 июля 2026 года; перед релизом агент обязан проверять changelog.
• Проверка чеков не заменяет консультацию юриста, бухгалтера или специалиста по ККТ.
• В тестовом режиме ЮKassa доступны не все способы оплаты настоящего магазина.

Подробная модель угроз: docs/security-model.md.