@theyahia/aprovodka

🇬🇧 English version: README.md

ℹ️ Где живёт код: здесь и живёт — разработка, тесты и релизы в npm пакета @theyahia/aprovodka идут из монорепозитория WWmcp. Отдельный репозиторий theYahia/aprovodka — витрина проекта (на него ведёт редирект со старого адреса theYahia/1c-rest-mcp); дерево кода, которое там пока лежит, — это версия 3.2.0 до переименования. Issue и PR заводите здесь.

Переименование в 4.0.0: @theyahia/1c-rest-mcp → @theyahia/aprovodka. Старый пакет помечен deprecated и заморожен на 3.2.0. Причина регуляторная, а не техническая — см. CHANGELOG.

MCP-сервер для 1С:Предприятие через REST API (OData 3.0) — справочники, документы, регистры, бухгалтерия, константы, отчёты, пакетные операции и отслеживание изменений плюс discovery метаданных. Версия 4.2.0: 34 инструмента в 11 модулях. Аутентификация HTTP Basic. Транспорты stdio и Streamable HTTP.

Переход с @theyahia/1c-rest-mcp (v3.x → v4.0.0)

Пакет переименован в @theyahia/aprovodka. @theyahia/1c-rest-mcp объявлен устаревшим и заморожен на версии 3.2.0.

• Ставьте новый пакет: npx -y @theyahia/aprovodka.
• Бинарник переименован: 1c-rest-mcp → aprovodka. aprovodka --http и HTTP_PORT=3000 aprovodka работают как прежде.
• Имя сервера в MCP-рукопожатии теперь aprovodka — поправьте ключ в конфиге клиента, если вы его фиксировали.

Всё остальное не изменилось: все 32 имени инструментов, их аргументы и форматы ответов, три промпта, переменные окружения ONEC_* (и обратно совместимые псевдонимы 1C_*). Переименование пакета не требует правок конфигурации сверх самой команды запуска.

Переход с v1.x

Если вы пользовались v1.x, в релизе v2.0.0 было несколько ломающих изменений:

• Переменная окружения HTTP-транспорта переименована: PORT=3000 → HTTP_PORT=3000.
• Отдельный HTTP-бинарник убран: 1c-rest-mcp-http больше нет. Используйте aprovodka --http или HTTP_PORT=3000 aprovodka.
• Одна точка входа bin: dist/http.js больше не публикуется.
• Внутренний клиент: теперь наследует BaseHttpClient из @theyahia/mcp-core со стратегией BasicAuthStrategy. Экспортируемый функциональный API (oneCGet/oneCPost/oneCPatch/buildODataPath) не изменился, код инструментов продолжает работать.
• Ошибки инструментов: возвращаются как CallToolResult по спецификации MCP с isError: true (через withErrorHandling из @theyahia/mcp-core). Совместимо со всеми MCP-клиентами.

Имена инструментов, аргументы, форматы ответов и переменные ONEC_* не изменились.

Инструменты (34)

Инструменты сгруппированы в модули. По умолчанию регистрируются все; переменная ONEC_SERVICES ограничивает набор загружаемых опциональных модулей (discovery-модуль meta включён всегда). См. Переменные окружения.

Discovery — meta (включён всегда)

| Инструмент | Описание | |------------|----------| | list_entities | Список всех доступных OData-сущностей базы 1С. Фильтр type по группам: catalogs, documents, registers (все четыре вида регистров), charts (ChartOf*), constants, journals, reports или all. С него стоит начинать работу с незнакомой базой. | | get_document_by_number | Найти документ 1С по его номеру (например, накладную ТД-00123 от 2026-03-01). Удобная обёртка над $filter. | | get_metadata | Вернуть сырой OData-документ $metadata (EDMX/XML) с описанием всех сущностей, полей и типов. | | describe_entity | Список полей сущности по одной образцовой записи ($top=1) — дешевле, чем читать полный $metadata. | | get_config_preset | Курированная схема типовой конфигурации 1С (БП 3.0, УТ 11, ЗУП 3.1, ERP 2): ключевые OData-сущности с русскими описаниями, готовые примеры запросов и частые ловушки. Данные локальные, запроса к базе не делает — работает офлайн, ONEC_BASE_URL не нужен. У каждой сущности есть confidence: verified — имя встречено в цитируемом источнике, common — типовое имя из практики, первоисточником не подтверждённое (проверьте его через list_entities перед использованием). |

Справочники — catalogs

| Инструмент | Описание | |------------|----------| | get_catalogs | Чтение данных справочников 1С. Поддерживает $filter, $select, $orderby, $top, $skip. | | create_catalog_item | Создать элемент справочника через OData POST (например, добавить Контрагента или Номенклатуру). | | update_catalog_item | Изменить элемент справочника через OData PATCH (по GUID Ref_Key). |

Документы — documents

| Инструмент | Описание | |------------|----------| | get_documents | Чтение документов 1С с полной фильтрацией OData. | | create_document | Создать документ через OData POST. | | update_document | Изменить существующий документ через OData PATCH (по GUID Ref_Key). | | post_document | Провести документ через связанное OData-действие Post(). Параметр operational включает оперативное проведение. | | unpost_document | Отменить проведение документа через Unpost(). | | delete_document | Физически удалить документ через OData DELETE. Для обратимого удаления предпочтительнее set_deletion_mark. | | get_document_lines | Прочитать табличную часть документа (строки, например Товары) по Ref_Key через $expand. Имя табличной части зависит от конфигурации — узнайте его через get_metadata / describe_entity. |

Регистры — registers

| Инструмент | Описание | |------------|----------| | get_register | Чтение данных регистра сведений или регистра накопления. | | write_information_register | Записать запись в независимый регистр сведений (POST на InformationRegister_*). | | get_accumulation_balance | Остатки регистра накопления через виртуальный OData-метод Balance(Period=…,Condition=…). |

Бухгалтерия — accounting

| Инструмент | Описание | |------------|----------| | get_accounting_register | Чтение записей регистра бухгалтерии (AccountingRegister_*, например Хозрасчетный — проводки). | | get_accounting_balance | Виртуальные таблицы регистра бухгалтерии: Balance, Turnovers, BalanceAndTurnovers, RecordsWithExtDimensions, ExtDimensions. Не путать с get_accumulation_balance, который работает с AccumulationRegister_*, — здесь речь о двойной записи (счета, субконто). Таблицы оборотов Дт/Кт сознательно не включены: их точное имя ни одним прочитанным источником не подтверждено, сверяйте по get_metadata своей базы. |

Константы — constants

| Инструмент | Описание | |------------|----------| | get_constant | Прочитать значение константы 1С (Constant_*). | | set_constant | Записать значение константы через OData PATCH (поле Value). |

Быстрые операции — shortcuts

| Инструмент | Описание | |------------|----------| | find_by_description | Нечёткий поиск элементов по подстроке поля Description (OData substringof). | | get_by_key | Получить одну запись по её Ref_Key (GUID). | | count_entities | Подсчёт записей сущности ($inlinecount, $top=0) с необязательным фильтром. | | set_deletion_mark | Установить или снять DeletionMark у элемента справочника либо документа (обратимая пометка на удаление). | | get_recent_documents | Последние документы указанного типа, отсортированные по Date desc (опционально — только проведённые). |

Отчёты — reports

| Инструмент | Описание | |------------|----------| | get_report | Получить отчёт 1С по относительному URL HTTP-сервиса (/hs/...). Ограничен origin'ом из ONEC_BASE_URL. |

Произвольный OData — odata

| Инструмент | Описание | |------------|----------| | odata_query | Выполнить произвольный запрос OData 3.0. Поддерживает $filter, $select, $expand, $orderby, $top, $skip, $inlinecount. |

Пакетные операции — batch

В 1С нет штатной точки входа OData $batch. Эти инструменты отправляют N запросов параллельно (с ограничением конкурентности) и отчитываются об успехе или ошибке по каждому элементу — частичная неудача никогда не прерывает пакет.

| Инструмент | Описание | |------------|----------| | batch_create_documents | Создать N документов (1..100) одного типа параллельно. | | batch_update_catalog_items | Обновить N элементов справочника через PATCH по Ref_Key параллельно. | | batch_query | Выполнить N GET-запросов OData (1..50) параллельно; результаты объединяются на стороне клиента. |

Отслеживание изменений — changes

В 1С нет вебхуков и подписок на события — только опрос (polling).

| Инструмент | Описание | |------------|----------| | poll_changes_since | Забрать строки, изменённые после отметки времени ($filter по полю даты); возвращает next_cursor для следующего опроса. | | list_subscriptions | Явная заглушка, документирующая отсутствие вебхуков в 1С; перенаправляет на poll_changes_since. |

О пишущих инструментах и проведении. post_document/unpost_document/delete_document, get_accumulation_balance (виртуальный Balance) и write_information_register следуют спецификации 1С:Предприятие OData 3.0. Форму URL и параметров стоит сверить с $metadata вашей конкретной конфигурации (инструмент get_metadata), прежде чем полагаться на них в продакшене.

Промпты

Сервер поставляется с тремя MCP-промптами — это готовые многошаговые сценарии, которые клиент может вызвать напрямую (они едут вместе с npm-пакетом, отдельный скилл ставить не нужно):

| Промпт | Аргументы | Что делает | |--------|-----------|------------| | inventory-database | — | get_config_preset → list_entities по группам → count_entities → describe_entity: составляет карту незнакомой базы. | | find-and-post-document | query, document_type? | Находит документ, показывает его поля и строки, затем проводит его только после явного подтверждения человеком. | | reconcile-balances | register_name, period? | Сверяет get_accumulation_balance (остатки) с движениями из get_register и сообщает о расхождениях. |

Быстрый старт

Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "aprovodka": {
      "command": "npx",
      "args": ["-y", "@theyahia/aprovodka"],
      "env": {
        "ONEC_BASE_URL": "http://server:8080/base",
        "ONEC_LOGIN": "your_login",
        "ONEC_PASSWORD": "your_password"
      }
    }
  }
}

Cursor / Windsurf

Тот же блок конфигурации в разделе mcpServers настроек MCP вашей IDE.

VS Code (Copilot)

Добавьте в .vscode/mcp.json:

{
  "servers": {
    "aprovodka": {
      "command": "npx",
      "args": ["-y", "@theyahia/aprovodka"],
      "env": {
        "ONEC_BASE_URL": "http://server:8080/base",
        "ONEC_LOGIN": "your_login",
        "ONEC_PASSWORD": "your_password"
      }
    }
  }
}

Транспорт Streamable HTTP

Для удалённых и мультитенантных развёртываний сервер запускается как HTTP-служба:

HTTP_PORT=3000 \
ONEC_BASE_URL=http://server:8080/base \
ONEC_LOGIN=admin \
ONEC_PASSWORD=secret \
npx @theyahia/aprovodka
# или: npx @theyahia/aprovodka --http

Точки входа:

• POST /mcp — MCP-запросы
• GET /mcp — поток событий SSE (для сессии)
• DELETE /mcp — завершение сессии
• GET /health — { status: "ok", version, tools, uptime, memory_mb }

Включает управление сессиями (заголовок mcp-session-id), CORS и корректное завершение работы.

Переменные окружения

| Переменная | Обязательна | Описание | |------------|-------------|----------| | ONEC_BASE_URL | да | Базовый URL HTTP-сервера 1С (например, http://localhost:8080/base). | | ONEC_LOGIN | да | Логин для HTTP Basic auth. | | ONEC_PASSWORD | да | Пароль для HTTP Basic auth. | | ONEC_SERVICES | нет | Список модулей через запятую (по умолчанию all). | | ONEC_WRITE_MODE | нет | Гейт безопасности записи: off (по умолчанию) / preview / approval. См. Безопасность записи. | | ONEC_APPROVAL_TTL_SEC | нет | Время жизни ожидающего подтверждения, в секундах (по умолчанию 300). | | ONEC_AUDIT_LOG | нет | Путь к JSONL-журналу аудита для каждой записи, прошедшей через гейт. Работает fail-closed: если строку не удалось записать, операция отменяется. | | ONEC_AUDIT_ACTOR | нет | Имя субъекта, записываемое в журнал (по умолчанию — ONEC_LOGIN). | | HTTP_PORT | нет | Если задана, сервер работает в режиме HTTP на этом порту. |

Обратная совместимость: 1C_BASE_URL, 1C_LOGIN, 1C_PASSWORD также принимаются как запасной вариант.

Фильтрация модулей (ONEC_SERVICES)

Ограничивает набор регистрируемых инструментов, чтобы экономить контекст модели. Модули: catalogs, documents, registers, accounting, constants, shortcuts, reports, odata, batch, changes (плюс всегда включённый meta).

ONEC_SERVICES=catalogs,documents npx @theyahia/aprovodka

Discovery-модуль meta (list_entities, get_document_by_number, get_metadata, describe_entity, get_config_preset) регистрируется всегда — без него агент не сможет разобраться в структуре базы.

Безопасность: ставьте MCP_DISABLE_SANITIZE=true, только если доверяете источнику данных — по умолчанию вывод инструментов проверяется на паттерны prompt-инъекций. HTTP-клиент отклоняет абсолютные URL, чей origin отличается от ONEC_BASE_URL. Аргументы Ref_Key валидируются как GUID, а строковые значения в get_document_by_number экранируются по правилам OData; сырые $filter/$select/$orderby пробрасываются намеренно, поэтому ограничивать то, что сервер может прочитать или записать, нужно ролью пользователя 1С, а не этими аргументами.

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

По умолчанию выключена: если ONEC_WRITE_MODE не задана, сервер ведёт себя ровно как раньше и записи уходят в 1С сразу. Два более строгих режима существуют потому, что модель, пишущая в живой учёт, — это другой класс риска, чем модель, которая его читает.

| Режим | Поведение | |-------|-----------| | off (по умолчанию) | Записи выполняются немедленно. Побайтово то же поведение, что до 4.1. | | preview | Ничего никогда не записывается. Каждая изменяющая операция возвращает конверт «сухого прогона»: метод, разрешённый путь, диff from → to и op_hash. | | approval | Каждая изменяющая операция первый раз отклоняется с выдачей op_hash и выполняется только после вызова approve_write с этим хешем. Подтверждения одноразовые и имеют срок жизни (ONEC_APPROVAL_TTL_SEC). |

Пока гейт включён, появляются два дополнительных инструмента (в режиме off их нет):

| Инструмент | Описание | |------------|----------| | approve_write | Погасить op_hash и один раз выполнить отложенную запись. | | rollback_write | Отменить выполненную запись по её rollback-токену: проведение ↔ отмена проведения, пометка на удаление или PATCH обратно к записанным прежним значениям. |

Точка перехвата — одна функция в client.ts, поэтому ни один инструмент, существующий или будущий, не сможет записать в обход гейта. Создание записи и физический DELETE честно помечаются полем irreversible_reason, а не получают rollback-токен, который они не смогли бы отработать.

Задайте ONEC_AUDIT_LOG, чтобы каждая прошедшая через гейт операция дописывалась в JSONL-журнал до её выполнения. Если журнал записать не удалось, операция отменяется, так что отсутствие записи в журнале никогда не означает молчаливое изменение данных.

Аутентификация

REST API 1С:Предприятия использует HTTP Basic auth. Реквизиты запросите у администратора 1С:

1. Включите публикацию HTTP-сервисов и OData в конфигураторе 1С.
2. Заведите пользователя 1С с ролью, дающей права на чтение и запись нужных сущностей.
3. Логин и пароль этого пользователя укажите в ONEC_LOGIN / ONEC_PASSWORD.
4. ONEC_BASE_URL — это URL опубликованной информационной базы (тот же адрес, что вы открываете в веб-клиенте 1С, без суффикса /odata/...).

Конечная точка OData будет ${ONEC_BASE_URL}/odata/standard.odata/.

Демо-промпты

Попробуйте эти запросы на естественном языке в своём MCP-клиенте:

«Перечисли все типы документов в базе 1С, в названии которых есть „Реализация“.»

«Найди накладную ТД-00123 от 2026-03-01 — покажи её строки и общую сумму.»

«Дай последние 50 документов продаж за неделю, отсортированные по дате по убыванию.»

«Прочитай регистр сведений „Цены номенклатуры“ для товара с UUID abc-123.»

«Создай документ RealizationOfGoodsAndServices для контрагента „ООО Ромашка“ с двумя строками товаров.»

«Выполни OData-запрос: Catalog_Номенклатура, где Description содержит „кофе“, разверни Производитель, top 20.»

«Получи отчёт по остаткам с /hs/reports/balance?date=2026-04-01 и подведи итог.»

Разработка

pnpm install
pnpm --filter @theyahia/aprovodka build
pnpm --filter @theyahia/aprovodka test
pnpm --filter @theyahia/aprovodka dev   # режим наблюдения tsx

Структура проекта:

servers/aprovodka/
├── src/
│   ├── index.ts            — точка входа (runServer; версия + docstring)
│   ├── server.ts           — фабрика сервера, конфигурация модулей, регистрация инструментов
│   ├── client.ts           — функциональный API + buildKeyedPath + buildVirtualTablePath
│   │                         + escapeODataString + проверка GUID
│   ├── validation.ts       — общие zod-схемы полей (refKeySchema, odataDate, odataDateTime, normaliseEntity)
│   ├── types.ts            — TypeScript-типы OData
│   ├── lib/
│   │   ├── errors.ts       — разбор русских ошибок 1С → категория + подсказка по восстановлению
│   │   └── write-safety.ts — гейт записи: preview, подтверждения, аудит-журнал, rollback-токены
│   ├── presets/            — курированные схемы конфигураций
│   │   ├── index.ts        ├── types.ts   ├── common.ts
│   │   ├── bp30.ts         ├── ut11.ts    ├── zup31.ts    └── erp2.ts
│   └── tools/
│       ├── catalogs.ts     ├── documents.ts    ├── registers.ts
│       ├── accounting.ts   ├── constants.ts    ├── shortcuts.ts
│       ├── metadata.ts     — discovery (list_entities, get_document_by_number, get_metadata, describe_entity)
│       ├── presets.ts      — get_config_preset
│       ├── safety.ts       — approve_write, rollback_write
│       ├── batch.ts        ├── change-tracking.ts
│       ├── odata-query.ts  └── reports.ts
└── tests/
    ├── client.test.ts      ├── server.test.ts        ├── tools.test.ts
    ├── batch.test.ts       ├── change-tracking.test.ts ├── error-parsing.test.ts
    ├── presets.test.ts     └── write-safety.test.ts

Лицензия

MIT — см. LICENSE.