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

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

• спроектировать платежный flow;

• написать интеграцию под стек проекта;

• проверить запросы по OpenAPI без отправки;

• спроектировать и проверить чеки с учетом технических требований 54-ФЗ;

• провести read-only диагностику тестового магазина;

• сделать code review существующей интеграции.

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

Что входит

Пять skills:

Тринадцать 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

Related MCP server: @theyahia/yookassa-mcp

Установка в 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.