wtctl

wtctl — клиент сервера WebSoft HCM (WebTutor) для LLM-агентов и скриптов: MCP-сервер, CLI и SDK. Работает через API админки. На сервер ничего ставить не нужно: ни обработчиков, ни шаблонов, ни библиотек.

Неофициальный проект. Компания WebSoft его не разрабатывает, не одобряет и не поддерживает. «WebSoft HCM» и «WebTutor» — обозначения их правообладателя. Здесь они только указывают, с каким сервером работает клиент.

Альфа-версия. Использование — на свой риск: права и риски, состояние проекта.

Что умеет

Что покрыто из API админки:

• каталоги и документы объектов: поиск, чтение, создание, правка, удаление;
• формы: типы объектов и их поля, включая настраиваемые;
• выполнение кода, запросы XQuery, функции библиотек, агенты сервера, фоновые задачи;
• логи, файлы, документы как XML, сведения о сервере;
• остальные операции вызываются по ID, всего их около девяноста.

Что добавлено поверх API:

• условия поиска в JSON вместо XQuery и чтение страницами; различия MS SQL и PostgreSQL учтены в клиенте или описаны в гайде;
• правка по путям полей: предпросмотр, защита от чужой правки, сверка после записи; остальное в документе не трогается;
• три исхода записи: не отправлено, подтверждено, не определён; сама запись не повторяется;
• права подключения: по умолчанию только чтение;
• ошибки с кодом, причиной и подсказкой по-русски, похожие имена при опечатке;
• большие ответы сохраняются локально и читаются частями;
• логи разбираются на события, за логом можно следить;
• гайд для агента встроен в MCP-сервер и CLI.

Как используется

Основной способ работы — агентный: агент получает задачу словами и сам доводит её до результата.

У трёх интерфейсов одно ядро: одни и те же операции, аргументы, ответы и проверка прав. MCP-сервер — для агента в чате. CLI и SDK дают то же самое без чата: в скриптах, автотестах, задачах по расписанию и в своих программах.

Интерфейс	Для чего
MCP-сервер	Для агента в Claude Code, Codex и других приложениях с поддержкой MCP. В Claude Code и Codex ставится плагином, вместе с навыком (skill).
CLI wtctl	Для скриптов и разовых вызовов из терминала.
SDK	Для своего кода на JavaScript и TypeScript.

На что это рассчитано:

• реализовать задачу целиком: разобраться, как устроены данные на этом сервере, написать код на SP-XML, выполнить его, прочитать ошибку в логе, исправить и повторить;
• подготовить тестовые данные: создать объекты для проверки и убрать их после неё;
• написать автотесты на SDK или CLI: скрипт создаёт данные, запускает проверяемый код и сверяет результат на сервере и в логах;
• найти причину ошибки: воспроизвести, прочитать логи, сопоставить с кодом и данными;
• изменить много объектов: найти, показать план, выполнить скриптом, проверить каждый;
• собрать выгрузку или сверку, для которой в админке нет готового отчёта.

Простейшие запросы к агенту, на один-два вызова:

Запрос	Что вызывает агент
«Какие настраиваемые поля есть у сотрудника?»	hcm_schema
«Найди работающих сотрудников без e-mail, покажи ФИО и подразделение»	hcm_types и hcm_schema — узнать каталог и поля, hcm_query — найти
«Переименуй группу sales в „Отдел продаж“. Сначала покажи, что изменится»	hcm_query, затем hcm_object_patch: сначала с preview, потом без
«Запусти агента сервера my_import и покажи, что он написал в лог»	hcm_api_execute с операцией agents.run, затем hcm_logs_search
«Найди в логах, почему сервер отказал при сохранении карточки»	hcm_logs_follow по логу xhttp за сегодня

То же из терминала:

npx -y wtctl types --search сотрудник
npx -y wtctl schema collaborator --origin custom
npx -y wtctl query --catalog collaborators --fields id,fullname --limit 5

CLI отвечает JSON: {"ok":true,"data":…} или {"ok":false,"error":{"code","message","hint"}}. После npm install -g wtctl те же команды пишутся без npx -y.

И из своего кода:

import { loadConfig, withHcmClient, unwrap } from "wtctl";

await withHcmClient(loadConfig(), async (client) => {
  const page = unwrap(
    await client.query({ catalog: "collaborators", where: { is_dismiss: false }, fields: ["id", "fullname"], limit: 5 }),
  );
  for (const row of page.items) console.log(row.id, row.fullname);
});

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

Что нужно:

• Node.js 22.16 или новее;
• git: через него Claude Code и Codex скачивают плагин;
• учётная запись, которую сервер HCM пускает в админку.

1. Создать подключение. Команда спросит адрес сервера, логин и пароль.

   npx -y wtctl config init

   Подключение сохраняется в ~/.wtctl/connections.json, его читают все приложения на компьютере. Новое подключение умеет только читать.

2. Проверить подключение.

   npx -y wtctl check

   Команда идёт по шагам: вход, версия, запрос, чтение документа и так далее. Если шаг не прошёл, в ответе будет причина.

3. Поставить плагин в Claude Code или Codex. В плагине MCP-сервер и навык.

   Claude Code:

   claude plugin marketplace add ysamtme/wtctl
   claude plugin install wtctl@wtctl

   Codex:

   codex plugin marketplace add ysamtme/wtctl
   codex plugin add wtctl@wtctl

4. В новом чате попросить агента вызвать hcm_status. В ответе должны быть версия сервера HCM и права подключения.

Другие приложения, установка без плагина, подключение без файла, обновление, удаление и разбор неполадок — в docs/installation.md.

Права и риски

Проект в альфа-версии. Подключать его к боевому серверу — тому, где настоящие данные и работают люди, — крайне не рекомендуется: ошибиться может и агент, и сам клиент. Агент может поменять или удалить не тот объект, выполнить на сервере не тот код. Если запись разрешена, клиент от этого не защитит.

Клиент входит на сервер под учётной записью из файла подключений и делает те же вызовы, что и админка. Отдельного пользователя «агент» для сервера нет: всё, что делает агент, сервер считает действиями этой учётной записи, с её правами.

Клиент может эти права только сузить. Новое подключение умеет только читать. Запись и выполнение кода на сервере включаются отдельно: права.

Лицензия — MIT: программа даётся «как есть», без каких-либо гарантий. Автор не отвечает за потерю или порчу данных, простой сервера и любые другие последствия её использования.

Подробнее о правах, паролях и о том, как понять, прошла ли запись, — в docs/security.md.

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

Страница	О чём
Установка	плагин для Claude Code и Codex, MCP-сервер в других приложениях, обновление, удаление, разбор неполадок
Подключения и права	файл подключений, несколько серверов, переменные окружения, права, большие ответы
Инструменты MCP	список инструментов, порядок работы, вид ответа
CLI	установка, первые вызовы, команды, ввод и вывод, несколько операций одним вызовом
SDK	методы, чтение страницами, запись, типы
Справочник SDK	каждый метод, функция, ошибка и тип SDK с аргументами и полями ответа
Логи сервера	чтение, поиск и слежение
Сведения о сервере	версия, база данных, проверка служб
Безопасность	что разрешают права, исход записи, пароли, данные сервера
Совместимость	что отличается между версиями сервера и базами, что не работает, что не проверено
Как устроен клиент	слои, модули и операции — для тех, кто меняет сам клиент

Как решать задачи — условия поиска, правка объектов, код на сервере, разбор отказов — описано в гайде. Агент получает его от MCP-сервера инструментом hcm_guide, в терминале его печатает wtctl guide, а с плагином он приходит ещё и навыком wtctl. Гайд написан для агента, примеры в нём — вызовы инструментов MCP.

Темы гайда: запросы, объекты, код и функции библиотек, логи, файлы, CLI и SDK, ошибки.

История изменений — в CHANGELOG.

Совместимость

	Проверено	Не проверено
Версия сервера	2025.1.1171, 2025.1.1333, 2025.2.1470, 2025.2.1535	другие версии, в том числе старше 2025.1
Сервер	под Windows	под Linux
База данных	MS SQL, PostgreSQL; на файловой базе — самопроверка, файлы и код на сервере (2025.2.1535)	остальное на файловой базе
Адрес и вход	http://, логин и пароль учётной записи с доступом в админку	https://, reverse proxy, вход через SSO
Клиент	Windows, Node.js 24	Linux, macOS
Приложения (харнессы)	Claude Code, Codex	Cursor, VS Code с Copilot, Copilot CLI, Gemini CLI и другие приложения с поддержкой MCP
Объём данных	—	каталоги на сотни тысяч записей, длинные очереди фоновых задач

Каждый пример вызова из документации и гайда выполнен на этих серверах на обеих базах. Чем поиск на MS SQL отличается от поиска на PostgreSQL, написано в гайде по запросам.

Если что-то из непроверенного не работает, wtctl check покажет, на каком шаге проблема.

Что отличается между версиями и базами и что не работает ни на одном проверенном сервере — в docs/compatibility.md.

Состояние проекта

Альфа-версия.

• API сервера. Клиент делает те же вызовы, что и админка. WebSoft не описывает их как открытый API и может поменять в любом обновлении сервера.
• Версии клиента. До версии 1.0 имена инструментов, команд и аргументов могут меняться. Все такие изменения перечислены в CHANGELOG.
• Подход. Проект вайбкодится: код пишут LLM-агенты, автор его построчно не читает; проверка — автотесты и прогоны на серверах из таблицы совместимости. Возражения против подхода не принимаются.
• На что рассчитан. Проект в основном делается под сильные модели и под работу вместе с двумя непубличными инструментами автора: документацией по платформе для агента и линтером кода. На моделях слабее и отдельно от этих инструментов он проверялся мало. Доработки в эту сторону возможны и планируются, сроков нет.
• Поддержка. Об ошибках и пожеланиях можно написать в issues; что приложить к сообщению, сказано в CONTRIBUTING. Активной поддержки и доработок по запросу автор не обещает, но они возможны.

Разработка

npm ci
npm run build
node dist/cli/bin.js version

npm run build собирает CLI в один файл dist/cli/bin.js без внешних зависимостей, npm run verify запускает все проверки. Как устроен клиент, написано в docs/architecture.md.

Собранный плагин лежит в ветке plugin. Плагин из папки с исходниками Claude Code загружает на один сеанс: claude --plugin-dir ..

Лицензия

MIT. Программу можно использовать, менять и распространять, в том числе в коммерческих целях, если сохранить текст лицензии и указание автора. Гарантий нет, за ущерб автор не отвечает. Силу имеет английский текст в файле LICENSE.

В собранный CLI встроены сторонние пакеты, их лицензии лежат в dist/THIRD-PARTY-LICENSES.txt.