Cursor + MCP для 1С-разработчика: 15 проверенных шагов от пустой папки до рабочего агента

При настройке связки Cursor и 1С через протокол Model Context Protocol (MCP) инженеры регулярно сталкиваются с нештатным поведением среды. Сервер не запускается из-за смены путей после обновления, агент галлюцинирует по составу реквизитов, а в журнале вызовов появляются ошибки MODULE_NOT_FOUND или таймауты подключения к порту.

В предыдущих публикациях мы рассмотрели общую идею интеграции. Однако при разборе откликов коллег выявились конкретные технические расхождения:

1. MCP-сервер добавляется в Cursor в выключенном состоянии;
2. Сервер запускается через бинарный файл node, отсутствие которого в системной переменной PATH приводит к аварийному завершению процесса;
3. Расширения vscode-1c-platform-tools и mcp-1c-platform-tools созданы community-командой yellow-hammer под лицензией MIT; одноимённый инструментарий фирмы «1С» - это отдельный программный продукт;
4. Сервер MCP предоставляет инструменты вызова команд платформы, однако не передаёт в контекст модели готовую объектную схему метаданных. Структуру объектов агент должен считывать непосредственно из текстовой XML-выгрузки.

Чтобы исключить любые расхождения, я развернула чистый тестовый стенд на Windows 11 с платформой 1С:Предприятие 8.3.27.2130, зафиксировала версии компонентов, составила пошаговый инженерный регламент и разработала скрипт автономной диагностики doctor.ps1.

🔬 Что делает MCP-сервер и чего он не делает

Перед запуском важно строго разграничить зоны ответственности компонентов.

Что делает связка расширений

• Предоставляет агенту набор MCP-инструментов: проверка состояния окружения (env_status), инициализация базы данных (infobase_initFromSrc), запуск синтаксического контроля модулей (syntaxCheck_run), управление зависимостями OneScript;
• Обеспечивает межпроцессное взаимодействие (IPC) между окном редактора и платформенными утилитами через локальный сокет 127.0.0.1:40241;
• Позволяет агенту запускать компиляцию исходников и получать отчёты об ошибках компиляции.

Чего сервер не делает

• Сервер не парсит деревья метаданных во внутренние JSON-структуры;
• Сервер не инжектирует в системный промпт модели состав справочников, документов и регистров;
• Сервер не заменяет синтакс-помощник платформы.

Агент получает представление о конфигурации исключительно через файловый контекст рабочей области. Если проект не выгружен в исходники XML и BSL, агент оказывается полностью изолирован от прикладного решения.

📋 Пятнадцать шагов развёртывания рабочего места

Шаг 1. Проверка базовых компонентов хоста

Для запуска требуются четыре системных компонента:

• Установленный редактор Cursor (версия 3.x);
• Среда Node.js LTS (команда node должна быть доступна в консоли, так как запуск MCP-сервера прописан через Node.js runtime);
• Технологическая платформа 1С:Предприятие 8.3;
• Распределённая система контроля версий Git.

Снимок 1. Терминал проверки хоста: Node.js v22.13.0, Git 2.47.1, 1С 8.3.27 и Cursor.

Шаг 2. Установка базового расширения редактора

В панели расширений Cursor найдите и установите пакет: yellow-hammer.vscode-1c-platform-tools Пакет предоставляет подсветку синтаксиса BSL, интеграцию с платформой и базовый IPC-сервер.

Снимок 2. Расширение 1C: Platform Tools в каталоге Open VSX.

Шаг 3. Установка MCP-адаптера

В каталоге расширений установите зависимый компонент: yellow-hammer.mcp-1c-platform-tools Манифест этого расширения содержит явную зависимость от первого пакета и регистрирует точку входа MCP-сервера в файле out/index.js.

Снимок 3. Расширение 1C: Platform Tools MCP с зависимостью от основного пакета.

Шаг 4. Инициализация рабочего каталога

Создайте пустой каталог проекта и выполните инициализацию репозитория:

1

git init

Скопируйте в корень файлы .gitignore и .gitattributes. В файле .gitattributes обязательно зафиксируйте нормализацию окончаний строк для исходников платформы:

1
2
3

* text=auto
*.bsl text eol=crlf
*.xml text eol=crlf

Снимок 4. Файл .gitattributes стенда с фиксацией CRLF для модулей BSL и XML.

Шаг 5. Выгрузка конфигурации в XML-исходники

Выполните выгрузку конфигурации из информационной базы в каталог src/cf/ стандартной командой платформы:

1

1cv8.exe DESIGNER /F "./build/ib" /DumpConfigToFiles "./src/cf"

Убедитесь, что в каталоге src/cf/ присутствует корневой файл Configuration.xml и подкаталоги модулей.

Снимок 5. Дерево файлов конфигурации с корневым Configuration.xml.

Шаг 6. Инициализация дескриптора пакета

Вызовите палитру команд Cursor (сочетание клавиш Ctrl+Shift+P) и выберите команду: 1С: Зависимости: Инициализировать проект Команда создаст в корне файл packagedef, определяющий проект для пакетного менеджера OneScript.

Снимок 6. Созданный файл packagedef в корне проекта.

Шаг 7. Активация канала IPC

По умолчанию межпроцессное взаимодействие в расширении выключено. Откройте файл .vscode/settings.json и добавьте параметр:

1
2
3
4

{
  "1c-platform-tools.ipc.enabled": true,
  "1c-platform-tools.ipc.port": 40241
}

Порт 40241 используется расширением для приёма команд от MCP-сервера.

Снимок 7. Активация параметра ipc.enabled и порта 40241.

Шаг 8. Генерация файла конфигурации MCP

В палитре команд вызовите: 1C: Platform Tools MCP: Настроить MCP для Cursor (.cursor/mcp.json) Расширение сформирует в каталоге .cursor/ файл mcp.json следующего содержания:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "mcpServers": {
    "1c-platform-tools": {
      "command": "node",
      "args": [
        "C:/Users/Admin/.cursor/extensions/yellow-hammer.mcp-1c-platform-tools-0.3.0/out/index.js"
      ],
      "env": {
        "ONE_C_PLATFORM_TOOLS_PORT": "40241"
      }
    }
  }
}

Снимок 8. Сформированный конфигурационный файл .cursor/mcp.json.

Шаг 9. Включение сервера в настройках Cursor

Перейдите в меню Cursor Settings -> Features -> MCPs. При первичной генерации сервер часто регистрируется выключенным. Переведите переключатель напротив 1c-platform-tools в активное положение. Индикатор состояния должен смениться на зелёный маркер подключения.

Снимок 9. Зелёный индикатор подключенного MCP-сервера в Cursor.

Шаг 10. Проверка отклика агента

Откройте панель диалога с моделью (Composer) и передайте инструкцию: Вызови инструмент env_status и выведи текущее состояние окружения 1С Агент выполнит вызов инструмента и вернёт структуру с версией платформы и статусом готовности порта.

Снимок 10. Вызов инструмента env_status и успешный ответ агента.

Шаг 11. Установка инструментов OneScript

Для запуска фонового контроля модулей установите пакетный менеджер OneScript и утилиту vanessa-runner:

1

opm install vanessa-runner

Это позволит выполнять проверку модулей без открытия графического окна Конфигуратора.

Снимок 11. Установка пакета vanessa-runner через opm.

Шаг 12. Настройка профиля базы данных

Создайте в корне файл autumn-properties.json:

1
2
3
4
5

{
  "v8version": "8.3.27.2130",
  "ibconnection": "/F ./build/ib",
  "src": "./src/cf"
}

Файл связывает команды расширения с конкретной версией платформы и локальной тестовой базой.

Снимок 12. Профиль базы autumn-properties.json.

Шаг 13. Тестовый прогон синтаксического контроля

Выполните через агента вызов инструмента syntaxCheck_run. Сервер запустит платформенную проверку модулей по конфигурации и вернёт список замечаний компилятора.

Снимок 13. Успешный синтаксический контроль модулей стенда.

Шаг 14. Подключение BSL Language Server

Для статического анализа кода установите расширение Language 1C (BSL) и добавьте в корень файл .bsl-language-server.json:

1
2
3
4
5
6

{
  "$schema": "https://raw.githubusercontent.com/1c-syntax/bsl-language-server/master/src/main/resources/configuration/schema.json",
  "diagnostics": {
    "computeTrigger": "onSave"
  }
}

Это обеспечивает мгновенную подсветку синтаксических неточностей прямо при сохранении файлов модулей.

Снимок 14. Подсветка кода и диагностика BSL Language Server при сохранении.

Шаг 15. Фиксация системных инструкций агента

В каталоге .cursor/rules/ создайте правила с расширением .mdc:

• 1c-cycle.mdc: протокол внесения изменений (чтение XML -> правка BSL -> синтакс-контроль -> коммит);
• 1c-metadata.mdc: запрет выдумывания несуществующих реквизитов и предписание читать структуру объектов из XML;
• 1c-safety.mdc: запрет деструктивных операций над информационными базами.

Снимок 15. Терминал с выполнением doctor.ps1: все 12 проверок пройдены со статусом OK.

🛠 Разбор типичных отказов стенда

Отказ 1. Ошибка MODULE_NOT_FOUND

Симптом: При обращении к MCP-серверу Cursor выводит ошибку Cannot find module ... out/index.js. Причина: После автоматического обновления расширения в Open VSX папка версии меняется (например, с 0.3.0 на 0.3.1). Путь в ранее сгенерированном файле .cursor/mcp.json продолжает указывать на удалённый каталог старой версии. Решение: Повторно вызовите команду Настроить MCP для Cursor из шага 8 либо отредактируйте абсолютный путь к index.js в файле mcp.json.

Отказ 2. Зависание вызовов на порту 40241

Симптом: Агент ожидает ответа инструмента до истечения таймаута. Причина: Параметр 1c-platform-tools.ipc.enabled не включен в настройках, либо порт занят другим экземпляром редактора. Решение: Проверьте флаг в .vscode/settings.json. Если открыто несколько рабочих пространств, назначьте каждому отдельный порт через переменную окружения ONE_C_PLATFORM_TOOLS_PORT.

📦 Автоматическая самодиагностика окружения через doctor.ps1

Чтобы автоматизировать проверку всех параметров окружения и исключить ручной поиск расхождений, я написала диагностический скрипт doctor.ps1.

Скрипт написан на PowerShell, не требует установки внешних библиотек и выполняет 12 последовательных тестов:

• D01: Доступность бинарного файла Cursor и проверка версии;
• D02: Наличие расширений yellow-hammer и отсутствие конфликтующих дублей версий;
• D03: Синтаксическая валидность .cursor/mcp.json и физическое существование скрипта index.js;
• D04: Доступность исполняемого файла node в переменной среды PATH;
• D05: Статус настройки ipc.enabled и мониторинг порта 40241;
• D06: Наличие файла packagedef в корне проекта;
• D07: Поиск установленной платформы 1С и сверка с профилем autumn-properties.json;
• D08: Наличие файлов выгрузки конфигурации (Configuration.xml и модули .bsl);
• D09: Конфигурация BSL Language Server;
• D10: Наличие git-репозитория и файла .gitattributes;
• D11: Доступность OneScript;
• D12: Наличие файлов системных правил агента в каталоге .cursor/rules/.

Запуск скрипта в корне проекта:

1

powershell -ExecutionPolicy Bypass -File doctor.ps1

🧭 Ограничения

1. Стенд проверялся на операционной системе Windows 11 с платформой 1С:Предприятие 8.3.27.2130 и средой Node.js 22.13.0 LTS. Для рабочих станций на базе Linux пути к бинарным файлам платформы и запуск диагностического скрипта требуют наличия PowerShell Core (pwsh).
2. Расширение yellow-hammer предоставляет сетевой транспорт и инструменты запуска платформы, но не преобразует внутренние типы метаданных в компактную JSON-схему для контекста модели. Информацию об объектах агент извлекает исключительно из текстовых XML-исходников конфигурации.
3. Фоновый запуск синтаксического контроля модулей через syntaxCheck_run опирается на пакет vanessa-runner и утилиту OneScript. Без предварительной инициализации OneScript агент возвращает ошибку отсутствия команды сборщика.

📚 Источники

• Спецификация Model Context Protocol: https://modelcontextprotocol.io (архитектура stdio и формат JSON-RPC);
• Исходные коды расширений yellow-hammer: https://github.com/yellow-hammer (пакеты vscode-1c-platform-tools и mcp-1c-platform-tools);
• Справочник параметров технологической платформы 1С:Предприятие 8.3.27.2130: https://its.1c.ru/db/v8327doc (ключи командной строки Конфигуратора /DumpConfigToFiles и /CheckModules);
• Публикации коллег на Infostart:
  • «Cursor + MCP: собираем идеальное рабочее место 1С-разработчика за 15 минут» (публикация 2795749);
  • «Cursor + MCP для 1С: работающая инструкция с картинками» (публикация 2800301);
  • «Вызываем LLM из нативного кода 1С: Предприятие» (публикация 2807724);
  • «Синтакс-помощник 1С как MCP-инструмент: индекс из справки платформы и сервер на Python SDK» (публикация 2804420).

📎 Файл к статье

В архиве к статье 16.1-companion.zip (доступен за 1 StartMoney):

1. doctor.ps1: полный автономный скрипт самодиагностики на PowerShell (12 проверок окружения: пути, порт IPC 40241, Node.js, 1cv8, расширения yellow-hammer, правила .mdc, статус OneScript);
2. test-doctor.ps1: комплект автоматических модульных тестов с 5 фикстурами дефектов окружения для проверки диагностической логики без изменения рабочих настроек;
3. template/: готовый эталонный каркас проекта 1С для Cursor с предварительно настроенными файлами .cursor/mcp.json, .vscode/settings.json (включен сокет IPC), дескриптором packagedef, профилем autumn-properties.json и правилом .cursor/rules/1c-cycle.mdc;
4. README.md: пошаговый регламент развёртывания шаблона и быстрого запуска диагностики в новом проекте.

🏁 Резюме

Полноценная интеграция Cursor и платформы 1С требует точной координации четырёх звеньев: среды исполнения Node.js, локального IPC-канала на порту 40241, актуальной XML-выгрузки метаданных и дисциплинирующих системных правил для языковой модели. Использование скрипта doctor.ps1 позволяет зафиксировать эталонное состояние рабочего места за несколько секунд и исключить галлюцинации агента по структуре конфигурации.

 

Нинель Адольевна Щербакова (Ninel_S)

Архитектор • SRE & DevOps инженер • HighLoad 1С

Автор 69 публикаций на Infostart. Разработчик NOPik, SRE-Suite-for-1C и мультиагентных ассистентов для экосистемы 1С:Предприятие.

Каталог статей и открытых репозиториев Ninel_S