Ю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

Источники

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

Ограничения

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

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