MCP-сервер и редакторы

Работа с elemctl из ИИ-агента по MCP, плюс плагины и расширение VS Code.

MCP-сервер

Сервер отдаёт операции платформы как MCP-инструменты (транспорт stdio):

pip install "elemctl[mcp]"
claude mcp add elemctl -- elemctl mcp

Реквизиты подключения сервер берёт из тех же переменных ELEMENT_* / .env.

Инструменты

Рядом с ними встают инструменты, которые приносят плагины (см. ниже).

Одним окружением дело не ограничено: у каждого инструмента, обращающегося к платформе, есть необязательный env_file - путь к .env другого стенда. Так один сервер работает и с облаком, и с локальной установкой, без перезапуска с другими реквизитами. list_apps по умолчанию отдаёт краткие карточки (id, имя, статус, uri, применённая версия): полные карточки пространства - это десятки тысяч символов в ответе агенту, за ними - brief=false; параметр name фильтрует по подстроке имени без учёта регистра на клиенте (платформа query-параметр игнорирует). Так же ведёт себя list_projects (id, имя, вид проекта, пространство, счётчик приложений, признак удаления): name у него тоже фильтрует по подстроке, а проекты с признаком удаления скрыты, пока не задан include_deleted, – на стенде, живущем не первый месяц, их в перечне сотни против единиц живых. list_builds тоже отвечает краткими карточками (ид, версии, дата, ветка, коммит) и десятью свежими сборками, пока limit не скажет иного (0 снимает срез): у давнего проекта сборок тысячи. get_app, delete_app, start_app, stop_app и debug_info принимают ид приложения (UUID) либо его точное имя - не-UUID резолвится по списку, несколько совпадений - ошибка, а не угадывание. create_app и ensure_app добавляют к ответу поле sign-in - адрес и учётную запись, которой входят в только что созданное приложение (запись ПАНЕЛИ УПРАВЛЕНИЯ; учётные записи других приложений там не работают): агент видит только JSON.

Плагины

elemctl подхватывает внешние пакеты через точки расширения importlib.metadata: сам он в своём pyproject.toml о плагинах ничего не объявляет, а читает их при обращении. Так непубликуемые вендорские артефакты живут отдельным пакетом, а ядро elemctl остаётся чистым и общедоступным.

elemctl.debug_adapter - пакет-плагин объявляет каталог debug-адаптера платформы (проприетарные jar 1С, в состав elemctl не входят). Значение точки расширения - путь либо функция без аргументов, возвращающая путь; путь указывает на каталог с подкаталогом repo/, где лежат jar-файлы адаптера.

elemctl.commands - пакет-плагин приносит собственные команды. Значение точки расширения - Command, их список либо функция без аргументов, возвращающая одно из этого. ОДНО объявление даёт обе поверхности: elemctl строит по нему подкоманду CLI и инструмент MCP с настоящей схемой, а о том, что команда делает, ничего не знает. Там и место команде, которая знает про ваше окружение - внутренние контуры, смежные системы, ваши стенды - и потому в публичном ядре жить не может.

# pyproject.toml пакета-плагина
[project.entry-points."elemctl.debug_adapter"]
имя = "мой_пакет:adapter_root"     # () -> Path на каталог, содержащий repo/

[project.entry-points."elemctl.commands"]
имя = "мой_пакет.commands:commands"   # () -> list[Command]

# мой_пакет/commands.py
from elemctl.plugins import Argument, Command

def warm_up(context, stand="", force=False):
    context.log(f"прогреваем {stand}")          # прогресс: stderr в CLI, поле log в MCP
    card = context.client.get_app(stand)        # клиент строится при первом обращении
    return {"ok": True, "status": card.get("status")}

def commands():
    return [Command(
        name="warm-up",
        help="открыть админку свежего стенда",
        handler=warm_up,
        arguments=[Argument("--stand", help="приложение"), Argument("--force", type=bool)],
    )]

Результат обработчика обязан быть JSON-сериализуемым: CLI его печатает, инструмент MCP возвращает. Результат-словарь с "ok": false даёт в CLI код возврата 1 - та же конвенция, что у отчётов deploy и probe. Типы аргументов - str, int, float и bool (флаг); env_file к инструменту MCP добавляет сам elemctl, поэтому команда плагина дотягивается до других окружений ровно так же, как инструменты ядра. Занять имя, которое уже есть у ядра, команда не может - это ошибка, а не молчаливая подмена.

# путь к адаптеру от установленного плагина (для расширения VS Code):
# {"path": "...", "found": true} либо {"path": null, "found": false}
elemctl debug-adapter

# что приносят плагины - каталоги адаптера и команды
elemctl plugins

Сам адаптер (проприетарные jar 1С) извлекается из дистрибутива платформы скриптом tools/extract_adapter.py - в каталог для ручной настройки xbsl.debug.adapterPath либо для сборки пакета-плагина. Скрипт в дистрибутив пакета не входит.

Обнаружение плагинов отключается переменной ELEMCTL_NO_PLUGINS=1 (прогон только со штатными возможностями ядра).

VS Code

С редактором elemctl связывает расширение-спутник:

• XBSL (проект xbsl) – подсветка, линтер, конструктор форм, дерево метаданных, кнопка “XBSL: деплой на стенд”, запускающая elemctl deploy терминальной задачей с проверкой применения, и отладка приложений 1С:Элемента штатным DAP-адаптером платформы, данные сессии для которой даёт elemctl apps debug. Отладка была отдельным расширением XBSL Debug в репозитории elemctl; с версии XBSL 0.57 она часть одного расширения, а в репозитории осталась только сторона elemctl.

Оно публикуется и в Open VSX.