Pular para o conteúdo
MCP ThesaurusMCP Thesaurus

invoicebox

ComunidadeIncomplete39/100Reivindicar

npm @invoicebox/mcp-serverstdioupdated 28d ago

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

CódigoSite

O que dá para fazer com invoicebox?

Invoicebox MCP Server

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

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

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

Демонстрационный магазин опубликован в документации (авторизация), поэтому попробовать можно без своего договора. Он общий для всех читателей: пробные счета видны всем, поэтому реальные реквизиты и персональные данные в демо не вводите.

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:

{
  "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

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

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

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

Поддержка

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