# WATA MCP + Skills

MCP-сервер и набор скиллов, дающие AI-агенту доступ к платёжной системе
[wata.pro](https://wata.pro): личному кабинету мерчанта (кошелёк, выплаты,
терминалы, транзакции, чарджбеки, поддержка) и публичному API эквайринга и
цифровых товаров.

Работает в Claude Code, OpenAI Codex CLI и Google Antigravity — устанавливается
одной командой. Транспорт только stdio, отдельного HTTP-сервера нет.

## Зачем это нужно

Публичный API WATA выдаёт токен **на терминал**: он не покрывает кошелёк,
вывод средств, чарджбеки и настройки мерчанта в целом. Для этого сервер умеет
работать напрямую с личным кабинетом через сессию (email + пароль или
cookie), а для того, что публичный API умеет — использует его напрямую, без
эмуляции браузера.

## Установка

Нужен **Node.js 20 или новее** — проверьте `node -v`. На более старых версиях
сборка падает: код собирается под ES2022 с резолвингом модулей NodeNext.

```bash
git clone https://github.com/votsie/wata-mcp.git
cd wata-mcp
npm install && npm run build
node dist/cli.js install
```

Порядок важен: `install` прописывает в конфиги агентов путь к `dist/server.js`,
поэтому сборка должна пройти раньше.

`install` находит установленных агентов и прописывает сервер:

| Агент | Файл конфигурации |
|---|---|
| Claude Code | `.mcp.json` в корне репозитория |
| OpenAI Codex CLI | `~/.codex/config.toml`, секция `[mcp_servers.wata]` |
| Google Antigravity | `~/.gemini/config/mcp_config.json` |

Существующие настройки сохраняются — перезаписывается только запись `wata`.

## Вход в кабинет

Нужен только для инструментов кабинета (терминалы, кошелёк, выплаты и т.д.).
Публичный API эквайринга и цифровые товары работают по токену терминала
(`WATA_ACQ_TOKEN`) и входа не требуют.

Кабинет защищён вторым фактором: код приходит на почту.

```bash
node dist/cli.js login
```

Неинтерактивно (для агентов и CI):

```bash
node dist/cli.js login --start
node dist/cli.js login --code 123456
```

Через MCP: `wata_auth_login`, затем `wata_auth_verify`.

Сессия сохраняется в `~/.wata-mcp/session.json`, живёт около 60 дней и
продлевается сама при каждом запросе.

### Без пароля

Если не хотите хранить пароль, скопируйте cookie-строку из DevTools в
переменную `WATA_COOKIE`. Достаточно `auth_cookie` и `XSRF-TOKEN`.

## Проверка

```bash
node dist/cli.js doctor
```

## Возможности

90 инструментов по доменам:

| Домен | Кол-во | Что покрывает |
|---|---|---|
| Авторизация | 4 | вход, статус сессии, выход, смена пароля |
| Личный кабинет | 61 | терминалы и их настройки, транзакции, ссылки, подписки, финансы, кошелёк, чарджбеки, поддержка, заказы цифровых товаров, `wata_raw_request` для всего остального |
| Эквайринг (публичный API) | 10 | платёжные ссылки, поиск/получение транзакций, возвраты, баланс терминала, прямая оплата СБП/T-Pay/картой |
| Вебхуки | 3 | публичный ключ, проверка подписи, справка по приёму уведомлений |
| Цифровые товары | 12 | Steam, Telegram Stars, Top-Up, ваучеры |

В кабинете теперь можно не только смотреть, но и менять настройки терминала
и вебхуков: адрес уведомлений, страницы успеха и ошибки, какие типы
вебхуков отправлять.

Полные карты эндпоинтов: [`docs/api-map.md`](docs/api-map.md) (кабинет) и
[`docs/public-api.md`](docs/public-api.md) (публичный API).

### Публичный API эквайринга

Базовый адрес `https://api.wata.pro/api/h2h`, авторизация — JWT-токен
конкретного терминала (`WATA_ACQ_TOKEN` или выпуск через
`wata_terminal_api_token_create`). Покрыты создание платёжных ссылок, поиск и
получение транзакций, возвраты, баланс терминала на дату, прямая оплата
СБП/T-Pay/картой и подписки. Поиск ссылок — постраничная пагинация
(SkipCount/MaxResultCount), поиск транзакций — курсорная; это два разных
подхода в одном API, не путайте их.

### Цифровые товары

Базовый адрес `https://dg-api.wata.pro/api`: пополнение Steam, покупка
Telegram Stars, Top-Up игровых позиций, ваучеры. Два способа оплаты:

- `acquiring` — платит покупатель по ссылке;
- `deposit` — списывается с депозитного баланса мерчанта
  (`wata_dg_deposit_balance`), без участия покупателя.

### Вебхуки

Заголовок `X-Signature`, алгоритм **SHA512withRSA** (не SHA-256), подпись в
base64. Ключ — `GET /api/h2h/public-key` (без авторизации). Проверять нужно
**сырое тело** запроса, до разбора JSON: после `JSON.parse` подпись уже не
сойдётся. `wata_webhook_verify` и `wata_webhook_guide` объясняют это подробнее.

Предоплатный вебхук требует ответа за 10 секунд — иначе транзакция
отклоняется без обращения в банк; постоплатный и возвратный WATA повторяет
с нарастающим интервалом до 32 часов, поэтому обработчик обязан быть
идемпотентным.

### Песочница

`WATA_ENV=sandbox` переключает и кабинет (`merchant-sandbox.wata.pro`), и
эквайринг (`api-sandbox.wata.pro`) на тестовое окружение. У песочницы **свой**
публичный ключ для вебхуков — общий кэш ключа на два окружения ломает
проверку подписи после переключения.

У песочницы отдельные учётные данные: боевые логин и пароль там не работают,
вход нужно выполнять заново — `WATA_ENV=sandbox node dist/cli.js login`.
Сессии хранятся раздельно, в `~/.wata-mcp/session.json` и
`~/.wata-mcp/session.sandbox.json`, поэтому переключение контура не рушит
вход в другой.

`doctor` первой строкой печатает текущее окружение (`БОЕВОЕ` / `ПЕСОЧНИЦА`) и
адрес кабинета. Перед операциями с деньгами стоит проверить контур через
`doctor` — перепутанное окружение здесь самая дорогая ошибка.

## Скиллы

В `skills/` — одиннадцать скиллов по доменам, от `wata-setup` до
`wata-webhooks`. Они объясняют агенту не только какие инструменты вызывать,
но и где легко ошибиться: разница оборота и выручки, трёхшаговый вывод
средств, курсорная и постраничная пагинация в разных частях API.

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

- Секреты хранятся в `~/.wata-mcp/` (права `600`), а не в репозитории
- `.gitignore` закрывает `.env`, файлы сессий и куки
- Все изменяющие операции пишутся в `~/.wata-mcp/audit.log`
- Вывод средств трёхшаговый: `calculate-commission` возвращает `orderId` и
  `quoteId`, `initiate` создаёт заявку и возвращает `credentialTokenId`,
  `confirm` отправляет деньги по коду подтверждения. Пропустить первый шаг
  нельзя — без его идентификаторов заявку не создать. Последний шаг
  необратим и не должен вызываться без явного решения человека.
  Изменение автосеттлмента — двухшаговое: `initiate`, затем `confirm`.
- Возвраты необратимы и подтверждения на стороне WATA не имеют, поэтому
  требуют явного `confirm: true` в вызове.

## Тесты и CI

```bash
npm test
```

29 юнит-тестов. Они компилируются отдельно в `dist-test/` (см. `pretest`),
поэтому в `dist/` и в npm-пакет не попадают. Покрыты самые хрупкие места:
разбор `Set-Cookie`, проверка подписи вебхука, троттлинг запросов, проверка
путей и правка чужих конфигов установщиком.

В CI (`.github/workflows/ci.yml`) на каждый push и PR прогоняются typecheck,
тесты и сканирование секретов — по рабочему дереву и по всей истории коммитов.

## Настройки

| Переменная | Назначение | По умолчанию |
|---|---|---|
| `WATA_EMAIL`, `WATA_PASSWORD` | вход в кабинет | — |
| `WATA_COOKIE` | готовая cookie-строка вместо пароля | — |
| `WATA_ACQ_TOKEN` | JWT терминала для публичного API | — |
| `WATA_ENV` | `sandbox` переключает кабинет и эквайринг на песочницу | боевое окружение |
| `WATA_MIN_REQUEST_INTERVAL_MS` | пауза между запросами (DDoS-Guard) | `350` |
| `WATA_MAX_RETRIES` | повторы при сбоях | `3` |
| `WATA_HOME` | каталог сессии и журнала | `~/.wata-mcp` |

## Лицензия

MIT