# Invoicebox MCP Server

Сервер Model Context Protocol для Инвойсбокса: ассистент выставляет счёт организации, ИП или
физическому лицу, проверяет оплату, подтверждает отгрузку — а по ней формируются закрывающие
документы, — и возвращает деньги. Всё по просьбе человека и с его подтверждением.

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

## Быстрый старт на демо-магазине

Демонстрационный магазин опубликован в документации ([авторизация](https://docs.invoicebox.ru/docs/api/auth/)),
поэтому попробовать можно без своего договора. Он общий для всех читателей: пробные счета видны всем,
поэтому реальные реквизиты и персональные данные в демо не вводите.

```
INVOICEBOX_API_TOKEN=b37c4c689295904ed21eee5d9a48d42e INVOICEBOX_MERCHANT_ID=ffffffff-ffff-ffff-ffff-ffffffffffff INVOICEBOX_ENV=demo npx -y @invoicebox/mcp-server
```

Записи включаются явно: `INVOICEBOX_TOOLSETS=write` добавляет счёт, отмену и отгрузку, `refund` —
возврат. Токен можно не держать в переменной окружения: `invoicebox-mcp-server login <токен>` кладёт его
в файл с правами только для владельца.

Пример конфигурации клиента MCP:

```json
{
  "mcpServers": {
    "invoicebox": {
      "command": "npx",
      "args": ["-y", "@invoicebox/mcp-server@0.2.1"],
      "env": {
        "INVOICEBOX_API_TOKEN": "b37c4c689295904ed21eee5d9a48d42e",
        "INVOICEBOX_MERCHANT_ID": "ffffffff-ffff-ffff-ffff-ffffffffffff",
        "INVOICEBOX_ENV": "demo",
        "INVOICEBOX_TOOLSETS": "read"
      }
    }
  }
}
```

Версию указывайте всегда: у платёжного инструмента `latest` означает, что набор инструментов может
измениться между двумя запусками одного и того же диалога.

## Инструменты

| Инструмент | Что делает | Подтверждение |
|---|---|---|
| `lookup_company_by_inn` | Реквизиты организации или ИП по ИНН | нет |
| `get_order` | Счёт по идентификатору или по своему номеру | нет |
| `find_orders` | Срез по счетам: номер, статус, даты, суммы | нет |
| `find_shipments` | Что по заказу отгружено и в каком статусе | нет |
| `create_order` | Выставляет счёт, возвращает ссылку на оплату | двухфазное |
| `cancel_order` | Отменяет неоплаченный счёт | двухфазное |
| `create_shipment` | Подтверждает отгрузку, по ней идут акт, счёт-фактура и УПД | двухфазное |
| `create_refund` | Возвращает деньги полностью или по составу | двухфазное |

Полный справочник с параметрами — https://docs.invoicebox.ru/mcp/tools/

## Что важно знать до первого счёта

- **Суммы — целые копейки строкой:** `"12200"` это 122,00 ₽. Так модель не теряет копейку на числе с
  плавающей точкой.
- **Цена — за единицу, сумма — за количество.** `amount` и `amount_wo_vat` в позиции относятся к одной
  единице, `total_amount` и `total_vat_amount` — ко всему количеству.
- **Все записи двухфазные.** Первый вызов ничего не отправляет в API: возвращает сводку и одноразовый
  токен на 15 минут, привязанный к параметрам. Второй вызов с этим токеном исполняет операцию.
- **Крупная сумма подтверждается отдельно.** Выше порога (по умолчанию 100 000 ₽) сервер спрашивает
  человека, а не довольствуется числом, которое подставила модель.
- **Повтор не создаёт дубль.** Номер операции выводится из содержимого запроса; повтор того же вызова
  возвращает прежний результат.
- **Покупатель — юрлицо, ИП или физлицо.** В API типа два: `legal` (у ИП ИНН из 12 цифр и без КПП) и
  `private`.
- **Закрывающие документы идут по отгрузке.** Отдельного «сформировать УПД» нет: акт, ТОРГ-12,
  счёт-фактуру и УПД запускает `create_shipment`.

## Настройки

| Переменная | Обязательна | Назначение |
|---|---|---|
| `INVOICEBOX_API_TOKEN` | да, если нет файла токена | Токен из личного кабинета, вкладка «Интеграция (API)» |
| `INVOICEBOX_ENV` | да | `demo` или `production`; демо — магазин в тестовом режиме |
| `INVOICEBOX_MERCHANT_ID` | для операций магазина | Идентификатор магазина |
| `INVOICEBOX_COUNTERPARTY_ID` | для операций организации | Идентификатор организации |
| `INVOICEBOX_TOOLSETS` | нет | `read` по умолчанию, плюс `write` и `refund` |
| `INVOICEBOX_STATE_DIR` | нет | Каталог журнала и защиты от дублей; без него она живёт только в пределах запуска |
| `INVOICEBOX_RATE_LIMIT` | нет | Свой ограничитель, `запросы/секунды`; по умолчанию `60/30` |
| `INVOICEBOX_LIMITS` | нет | Суточные потолки, JSON |
| `INVOICEBOX_CONFIRM_THRESHOLD` | нет | Порог суммы в копейках для отдельного подтверждения |
| `INVOICEBOX_LOG_LEVEL` | нет | `error`, `warn`, `info`, `debug` |
| `INVOICEBOX_GRAYLOG_URL`, `INVOICEBOX_SENTRY_DSN` | нет | Внешние приёмники журнала; выключены по умолчанию |
| `INVOICEBOX_TOKEN_FILE` | нет | Свой путь к файлу токена |
| `INVOICEBOX_HTTP_PORT` | нет | Задан — транспорт Streamable HTTP на этом порту, иначе stdio |
| `INVOICEBOX_HTTP_HOST` | нет | Адрес привязки HTTP; по умолчанию `127.0.0.1` |
| `INVOICEBOX_HTTP_ALLOWED_HOSTS`, `INVOICEBOX_HTTP_ALLOWED_ORIGINS` | нет | Белые списки `Host` и `Origin`; по умолчанию наружу закрыто |
| `INVOICEBOX_HTTP_SESSION_IDLE_MS`, `INVOICEBOX_HTTP_MAX_SESSIONS` | нет | Срок жизни сессии (30 минут) и их потолок (200) |

Полный список настроек — https://docs.invoicebox.ru/mcp/quickstart/

## Расход контекста

Набор по умолчанию занимает около 1 100 токенов описаний, полный набор с возвратами — около 4 000.
Выборка двадцати счетов стоит примерно 1 200 токенов в кратком формате и 2 900 в подробном. Ответы
усекаются с явной пометкой, страница ограничена пятьюдесятью записями. Замеры и приёмы —
https://docs.invoicebox.ru/mcp/tokens/

## Разработка

```
npm ci
npm run typecheck
npm run lint
npm test
npm run build
```

## Документация

- Раздел о сервере: https://docs.invoicebox.ru/mcp/
- Справочник инструментов: https://docs.invoicebox.ru/mcp/tools/
- Безопасность и подтверждения: https://docs.invoicebox.ru/mcp/security/
- Лимиты, ошибки и журнал: https://docs.invoicebox.ru/mcp/faq/
- Расход токенов: https://docs.invoicebox.ru/mcp/tokens/
- Ассистенты без MCP: https://docs.invoicebox.ru/mcp/functions/
- API Инвойсбокса: https://docs.invoicebox.ru/docs/api/

## История изменений

Что менялось между версиями — в файле `CHANGELOG.md` внутри пакета (`npm view
@invoicebox/mcp-server versions` покажет список выпусков). Версию в конфигурации
указывайте явно: у платёжного инструмента `latest` означает, что набор инструментов
может измениться между двумя запусками одного диалога.

## Поддержка

Вопросы и доступ к бете — https://www.invoicebox.ru/ru/contacts