Answer42

Answer42 — MCP-инструмент для интерактивного управления UI 1С:Предприятия через клиент тестирования. Он позволяет AI-агенту открывать формы 1С, нажимать кнопки, заполнять поля, выбирать ссылки из форм выбора, работать с таблицами, динамическими списками и табличными документами.

The Answer to Life, Universe, and 1C — UI Driver

Проект даёт AI-агенту три способности:

1. Интерактивное управление UI 1С — открыть форму, кликнуть кнопку, активировать поле, заполнить значение, выбрать строку, провести сценарий через /TESTMANAGER + /TESTCLIENT.
2. Доказательная запись клиентского тестирования — записывать аннотированные PDF-слайды с MCP method/request/response и скриншотами окна 1С.
3. RAG-индекс метаданных — локальный SQLite/FTS индекс конфигураций 1С (EDT, XML-выгрузка Конфигуратора, base + extensions), включая подсказки для ui_tree и dynamic-list settings.

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

# Рекомендуется для обычной установки из PyPI
pipx install 'answer42[screenshot,linux-window-control]'

# Альтернатива без pipx
python3 -m venv .venv
. .venv/bin/activate
pip install 'answer42[screenshot,linux-window-control]'

# Разработка из git checkout
pip install -e '.[screenshot,dev,linux-window-control]'

# Windows: запускать из интерактивной пользовательской сессии, не как service
# pipx install "answer42[screenshot,windows-window-control]"
# pip install "answer42[screenshot,windows-window-control]"

# Запуск MCP-сервера (transport: stdio)
answer42 --ws-host 127.0.0.1 --ws-port 8765

Запуск сессии и подключение тестируемой базы выполняются одним MCP-вызовом:

start_session(
  session_id="my-session",
  base_url="<TARGET_INFOBASE_URL>",
  idle_timeout_minutes=60,
  execute="/path/to/external.epf",  # опционально: /Execute
  command_parameter="InitScenario" # опционально: /C
)

start_session определяет версию 1С по base_url, поднимает инфраструктуру Answer42 (на Linux — Xvfb, если нужен headless; на Windows — интерактивная desktop-сессия), свободные порты, WebSocket bridge, файловую базу менеджера и test-manager. Если доступны серверные компоненты 1С (ibsrv), менеджер и встроенная тестовая база публикуются через автономный сервер; если доступен только тонкий клиент и ibcmd, Answer42 автоматически использует fallback file-direct (/F) для файловых баз менеджера и клиента. После idle_timeout_minutes минут неактивности сессия автоматически завершается; значение по умолчанию — 60 минут. Для запуска клиента можно передать extra_args, execute (параметр командной строки /Execute) и command_parameter (параметр /C); если /C уже указан в extra_args, значения склеиваются через ;.

Логин/пароль рекомендуется не передавать явно: start_session умеет брать их из локального credentials-файла по base_url. Параметры username/password остаются в API для разовых сценариев и обратной совместимости, но при передаче в MCP-вызове они видны вызывающему агенту в аргументах tool-call.

ui_tree profiles and output formats

ui_tree is optimized for form-structure diagnostics. The default profile="navigation" returns a compact visible UI tree without data presentations, RAG enrichment, or command-panel subtrees. The tree is not depth-limited.

Useful modes:

• ui_tree(parent_name=...) serializes only the subtree under a known parent element, useful for large/complex forms.
• ui_tree(name=.../title=.../type=...) returns a flat objects list instead of a nested tree; on current managers filtering is performed on the 1C side; simple exact name/type queries may use the platform fast path before falling back to flat traversal.
• profile="diagnostic" includes command panels without enabling expensive data reads.
• profile="data" enables node data presentations; prefer targeted field_value_text, table_rows, tabular_document_text, or tabular_document_save unless you really need data for many nodes.
• profile="full" gives the closest historical verbose result.
• fields="minimal|navigation|diagnostic|data|full" (or a comma-separated custom field list) controls node payload without truncating the tree.
• command_panels="include|exclude|only" controls command-panel serialization explicitly; only returns a deduplicated flat list.
• group_mode="include|flatten|flatten_layout|exclude|exclude_empty|pages_only" controls whether group nodes are kept, lifted, or omitted.
• format="json|outline|yaml|yml" keeps JSON as the default structured result and offers readable text views for inspection. Invalid profile/group/command-panel/format values are rejected; every result includes metrics with timings/payload counters; tree_summary.types_count reports node counts by broad family (buttons, fields, tables, groups, etc.) and exact 1C test-client type.

Large ui_tree snapshots as resources

By default delivery="auto" keeps small results inline and automatically stores large results as resources when the estimated token count exceeds ONEC_MCP_UI_TREE_RESOURCE_AUTO_THRESHOLD_TOKENS (default 50k). Use delivery="inline" to force the selected JSON/outline/yaml directly in the response. Use delivery="resource" to force resource storage for large diagnostics:

r = ui_tree(profile="full", include_hidden=true, delivery="resource")

When auto switches to resource, or when delivery="resource" is forced, the inline response contains only resource_uri, snapshot_id, summary, metrics, byte size, estimated tokens, threshold reason and a small preview. The full JSON snapshot is stored under the Answer42 runtime data directory and registered as an MCP resource (answer42://ui-tree/<session>/<snapshot_id>). Do not load that whole resource into the agent context unless you really need the raw file; use targeted snapshot tools instead:

• ui_tree_resource_search(resource_uri=..., name/title/type/text=...) — find a few controls in a saved snapshot and get their path/index_path.
• ui_tree_resource_get_node(resource_uri=..., index_path=...) — read exactly one node.
• ui_tree_resource_children(resource_uri=..., index_path=..., depth=1|2) — read a small subtree.
• ui_tree_diff(before_resource_uri=..., after_resource_uri=...) — compare snapshots before/after a UI action.
• ui_tree_resource_action(resource_uri=..., index_path=..., action="focus|click_button|activate_field|field_value_text|field_info") — reuse a node selector from the snapshot and execute a first-class live UI tool.

index_path is the preferred stable address inside one snapshot. path is human-readable and useful for reports, but less reliable when several controls have the same captions.

Встроенные рекомендации для агентов

Answer42 больше не поставляет и не устанавливает bundled skills. Рекомендации по UI-автоматизации, RAG, Универсальному отчёту и экспорту табличных документов находятся в descriptions соответствующих MCP-инструментов и встроенных MCP prompts.

Команды answer42 install-skills и answer42 skills-install сохранены как совместимые no-op: они ничего не копируют и выводят сообщение о новой модели.

Инструкция для AI-агентов

Если вы AI-агент и пользователь просит установить Answer42, используйте отдельную инструкцию: docs/agent-installation.md.

Коротко:

1. установите пакет через pipx или virtualenv;
2. подготовьте ONEC_MCP_CREDENTIALS_FILE вне репозитория;
3. зарегистрируйте MCP-сервер в агентском клиенте;
4. проверьте установку через credentials_check, затем smoke-сессию start_session → active_window → stop_session.

Linux display prerequisite

На Linux start_session использует живую X11-сессию, если процесс Answer42 унаследовал непустой DISPLAY: test manager и test client запускаются на этом дисплее, поэтому их окна и скриншоты видны на desktop.

Если DISPLAY не задан (headless service, SSH без X11 forwarding и т. п.), Answer42 поднимает два собственных изолированных Xvfb-дисплея: один для test manager и второй для test client. В этом режиме пакет xvfb обязателен:

# Debian / Ubuntu
sudo apt install xvfb

# Fedora / RHEL
sudo dnf install xorg-x11-server-Xvfb

Если не задан ни доступный DISPLAY, ни Xvfb, start_session завершается до создания ресурсов с понятной подсказкой по установке. Чтобы desktop-сервис видел живой X11, его launcher/service должен передать корректный DISPLAY и права доступа к X server (обычно через XAUTHORITY).

Скриншоты: stdio и StreamableHTTP

screenshot сохраняет PNG на MCP-хосте и больше не помещает его base64-представление в результат tool-call.

• В stdio возвращаются только path, размер и диагностические поля. Агентский хост при необходимости прикладывает файл по пути.
• В StreamableHTTP добавляется непрозрачная одноразовая ссылка url на PNG. Она действует один час по умолчанию (ONEC_MCP_SCREENSHOT_URL_TTL_SECONDS), исчезает после первого скачивания и существует не дольше процесса сервера. Для внешнего reverse proxy укажите публичный base URL через ONEC_MCP_SCREENSHOT_URL_BASE.

Транспорты: stdio и StreamableHTTP

По умолчанию Answer42 использует stdio MCP transport (запускается MCP-хостом как subprocess). Для удалённого deployment доступен StreamableHTTP режим с MCP auth:

answer42 --http --http-host 0.0.0.0 --http-port 8080 \
  --http-token "static-secret-token" \
  --http-account-id "tenant-42"

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

export ONEC_MCP_HTTP=1
export ONEC_MCP_HTTP_HOST=0.0.0.0
export ONEC_MCP_HTTP_PORT=8080
export ONEC_MCP_HTTP_TOKEN="static-secret-token"
export ONEC_MCP_ACCOUNT_ID="tenant-42"
answer42

• Каждый MCP-запрос должен содержать заголовок Authorization: Bearer <token>.
• account_id определяет namespace для credentials. Если не задан, вычисляется как стабильный хеш токена (token-<16hex>).
• Режим по умолчанию stateless (--http-stateless/ONEC_MCP_HTTP_STATELESS default 1); для resumable sessions передай --http-stateless/0.

Безопасное хранение логинов и паролей

Чтобы креды были доступны MCP-серверу, но не попадали в чат и аргументы tool-call, храните их в локальном файле за пределами репозитория и передайте путь в окружение процесса Answer42:

export ONEC_MCP_CREDENTIALS_FILE=/secure/path/credentials.json

Если переменная окружения не задана, MCP-сервер читает файл по умолчанию:

~/.answer42-credentials.json

Формат файла v2 (аккаунт-bound):

{
  "version": 2,
  "accounts": {
    "tenant-42": {
      "entries": [
        {
          "url": "https://example.invalid/infobase",
          "username": "<USERNAME>",
          "password": "<PASSWORD>",
          "title": "dev-example",
          "aliases": ["dev42"]
        },
        {
          "url": "https://*.example.invalid/*",
          "username": "<WILDCARD_USERNAME>",
          "password": "<WILDCARD_PASSWORD>",
          "title": "wildcard-example",
          "aliases": ["we"]
        }
      ]
    }
  }
}

Устаревший v1 формат (flat entries) автоматически загружается в account legacy и мигрирует в v2 при следующем сохранении. Рекомендуется явно задать account_id (через HTTP auth claim или ONEC_MCP_ACCOUNT_ID в stdio) и перенести записи в соответствующий account.

Рекомендуемые права на файл: 0600.

Правила матчинга внутри аккаунта: сначала точное совпадение url, затем wildcard (*, ?) через fnmatch; первое совпадение побеждает. Пароли не логируются и не возвращаются наружу.

Для сохранения или обновления записи можно использовать MCP-tool:

credentials_save(
  url="<TARGET_INFOBASE_URL>",
  username="<USERNAME>",
  password="<PASSWORD>"
)

Для удаления записи:

credentials_remove(url="<TARGET_INFOBASE_URL>")

Для проверки, что для адреса есть сохранённые креды, используйте MCP-tool:

credentials_check(base_url="<TARGET_INFOBASE_URL>")

Ответы этих tools содержат только факт наличия/изменения/удаления записи и URL; логины и пароли не возвращаются. credentials_list() дополнительно показывает статус проверки (verified / verification_status): новые или изменённые записи сохраняются как unverified, после успешного start_session с этой учёткой помечаются как verified, а unverified запись удаляется при ошибке авторизации. Tool credentials_list() оставлен в коде для локальной диагностики, но в OpenClaw-конфигурации его рекомендуется скрывать через toolFilter.exclude, чтобы агент не мог получить список URL-шаблонов.

Остановка сессии:

stop_session(session_id="my-session", clean_data=False)

Требования

• Python 3.11+
• 1С:Предприятие 8.3.27+ или 8.5+
• Пакеты Python: mcp, websockets, pydantic; для скриншотов — mss
• Linux/X11: python-xlib/wmctrl/xdotool, GUI/Xvfb для headless-сервера; OS-слой допускается для подготовки геометрии окна (resize/maximize), но не для ввода/кликов/автоматизации 1С
• Windows: интерактивная пользовательская desktop-сессия; window-control и screenshots работают через WinAPI/mss, ввод/клики/автоматизация 1С выполняются только через API клиента тестирования

Проверяйте наличие платформы 1С в стандартных каталогах: Linux /opt/1cv8/x86_64/<version>/ и /opt/1cv8/i386/<version>/; Windows C:\Program Files\1cv8\<version>\bin\ и C:\Program Files (x86)\1cv8\<version>\bin\; macOS /Applications/1cv8/<version>/ или /opt/1cv8/<version>/. Для штатной работы нужны 1cv8c и ibcmd; ibsrv желателен, но при его отсутствии Answer42 может использовать fallback /F. Если автоопределение ошиблось, задайте ONEC_PLATFORM_DIR. Для очень медленного старта web-клиента можно увеличить ONEC_MCP_TEST_CLIENT_READY_TIMEOUT и timeout MCP-клиента; по умолчанию Answer42 ждёт открытия -TPort 55 секунд и затем отдаёт явную ошибку с логами клиента.

Безопасность стендов и учётных данных

В репозитории не должно быть реальных URL стендов, логинов или паролей. Для штатного запуска передавайте только base_url, а логин/пароль храните в локальном credentials-файле, доступном процессу Answer42 через ONEC_MCP_CREDENTIALS_FILE.

start_session всё ещё принимает username и password напрямую для разовых сценариев и обратной совместимости. Используйте это только когда осознанно готовы раскрыть значения вызывающему агенту: параметры MCP-вызова могут попасть в историю чата, логи клиента или отладочный вывод. Если вместо реального пароля передан редактированный плейсхолдер из звёздочек (***, ******** и т.п.), Answer42 остановит запуск с явной ошибкой: нужно указать настоящий пароль или сохранить корректные креды через credentials_save().

Примеры в документации используют только плейсхолдеры (<TARGET_INFOBASE_URL>, <USERNAME>, <PASSWORD>). Перед публикацией артефактов проверяйте, что параметры вызовов заредактированы: recorder маскирует ключи вроде password, но URL и логин тоже не должны попадать в публичные материалы.

Архитектура

Поток выполнения:

1. MCP-клиент вызывает tools через stdio MCP.
2. Answer42 принимает MCP-вызовы и передаёт команды в WebSocket bridge.
3. 1С test manager подключается к bridge и выполняет BSL-dispatch.
4. Test manager управляет 1С test client через API ТестируемоеПриложение.
5. Test client выполняет интерактивные операции в целевой информационной базе.

Подробнее: docs/architecture.md.

Сборка конфигураций 1С

Конфигурация менеджера тестирования собирается из XML-исходников src/cf/ через временную файловую ИБ: ibcmd infobase config import и затем ibcmd config save (приоритетный способ). Такой путь создаёт переносимый .cf с compatibility mode XML-исходников; Конфигуратор/DESIGNER используется как fallback, если ibcmd отсутствует:

python scripts/build_cf.py src/cf build/MCPTestManager.cf

PowerShell:

python scripts/build_cf.py src/cf build/MCPTestManager.cf

Тестовая конфигурация для E2E собирается из XML-исходников src/client_cf/:

python scripts/build_cf.py src/client_cf build/MCPTestClient.cf

PowerShell:

python scripts/build_cf.py src/client_cf build/MCPTestClient.cf

В Git хранятся только XML-исходники; CF — генерируемые артефакты. start_session использует build/MCPTestManager.cf только при точном совпадении content fingerprint с src/cf/; иначе автоматически пересобирает его локальной выбранной платформой. Встроенный demo-клиент аналогично работает с build/MCPTestClient.cf и src/client_cf/. Релизный wheel получает оба CF из GitLab CI, где они собираются закреплённой платформой 1С 8.3.27.2342.

E2E можно запускать целиком или по независимым сценариям:

python3 scripts/e2e_stable.py                         # full
E2E_SCENARIO=smoke python3 scripts/e2e_stable.py       # быстрый smoke
E2E_SCENARIO=dynamic python3 scripts/e2e_stable.py     # legacy: таблицы/dynamic-list/отчёт
E2E_SCENARIO=dynamic-tables python3 scripts/e2e_stable.py
E2E_SCENARIO=dynamic-lists python3 scripts/e2e_stable.py
E2E_SCENARIO=dynamic-reports python3 scripts/e2e_stable.py
E2E_SCENARIO=coverage python3 scripts/e2e_stable.py    # diagnostic/negative tools

Для реального распараллеливания сценарий умеет сам запустить пять разные сессий (smoke, dynamic-tables, dynamic-lists, dynamic-reports, coverage), а не копии одного и того же теста. Встроенная тестовая файловая база публикуется через один общий ibsrv, когда серверные компоненты доступны; без ibsrv demo-клиент запускается через file-direct (/F):

E2E_PARALLEL=1 E2E_SESSION_ID=e2e-split python3 scripts/e2e_stable.py

start_session также переиспользует общий автономный сервер для одинаковой файловой базы. Последний stop_session освобождает refcount и завершает shared ibsrv.

Ограничения

• Форма пользовательской настройки «Изменить форму» частично недоступна для надёжной автоматизации через API клиента тестирования. В частности, команда «Добавить поля» в верхней панели формы настройки может быть видна на скриншоте и в диагностическом тексте, но не нажиматься как обычная ТестируемаяКнопкаФормы: click_button может не находить её, а focus_object может вернуть успешную фокусировку без открытия диалога добавления полей.

Лицензия

MIT

Copyright

Copyright (c) 2026 Kosolapov Stanislav aka proDOOMman prodoomman@gmail.com, Marvin (AI Assistant), 42Clouds, and contributors.

Licensed under the MIT License.