1C Syntax Check MCP
by phsin
README.md
# 1C Syntax Check MCP
MCP-сервер для **штатной проверки синтаксиса 1С:Предприятие 8** в пакетном режиме
Конфигуратора (`/CheckModules`, `/CheckConfig`). Работает с конфигурациями (`.cf`),
расширениями (`.cfe`), XML-выгрузками и существующими информационными базами.
Основной клиент — **DeepSeek Harness (DSH)**; сервер также имеет CLI для CI.
## Возможности
| Tool | В DSH | Назначение |
|---|---|---|
| `check_extension` | `mcp__onec__check_extension` | Проверить расширение |
| `check_configuration` | `mcp__onec__check_configuration` | Проверить конфигурацию |
| `check_all_extensions` | `mcp__onec__check_all_extensions` | Все расширения ИБ |
| `get_run` | `mcp__onec__get_run` | Результат по `runId` |
| `cancel_run` | `mcp__onec__cancel_run` | Отменить проверку |
| `environment` | `mcp__onec__environment` | Платформа, версия, каталоги, ошибки |
Сервер создаёт временную файловую ИБ, загружает в неё конфигурацию/расширение,
запускает Конфигуратор с `/Out`, разбирает лог в диагностики
(`module`, `line`, `column`, `message`, `context`) и удаляет временные файлы.
## Требования
- Windows 10/11 или Windows Server 2019/2022.
- Node.js 20+.
- Установленная платформа 1С 8.3.24+ (проверено на 8.3.27.1644) и лицензия.
- На томе с `1cv8.exe` должны работать короткие имена 8.3 (`C:\PROGRA~1\...`):
сервер запускает Конфигуратор с verbatim-аргументами, а путь с пробелами
требует короткого имени. Проверка: `fsutil 8dot3name query C:`.
- Доступ к `%LOCALAPPDATA%\1C\1cv8` — платформа пишет туда служебные файлы.
## Проверено на реальной 1С
Windows 10, платформа 8.3.27.1644:
- `.cfe` — `ok`, `exitCode 0`;
- XML-расширение с заведомой ошибкой — `diagnostics`, `exitCode 101`,
сообщение «Ожидается выражение», строка 66, колонка 5;
- `.cf` — `diagnostics`, `exitCode 101`;
- `-AllExtensions` на существующей ИБ — 72 диагностики;
- `/CheckConfig` с `-Extension` — `ok`;
- async-запуск (`waitSec: 1` → `get_run`) и `cancel_run` — работают.
## Установка
```powershell
npm install
npm run build
npm test
```
Интеграционный smoke-тест на реальной 1С (нужны платформа и расширение):
```powershell
$env:ONEC_PLATFORM_PATH = 'C:\Program Files\1cv8\8.3.27.1644\bin\1cv8.exe'
$env:ONEC_PLATFORM_VERSION = '8.3.27.1644'
node scripts/mcp-smoke.mjs
```
## Параметры запуска MCP
Путь и версия платформы **обязательны** и задаются только при запуске сервера —
автопоиска нет. Tool-аргументы их не переопределяют.
| Параметр | Env | Описание |
|---|---|---|
| `--platform-path` | `ONEC_PLATFORM_PATH` | **Обязателен.** Полный путь к `1cv8.exe`; по нему запускается Конфигуратор и читается `FileVersion` |
| `--platform-version` | `ONEC_PLATFORM_VERSION` | **Обязателен.** Версия вида `8.3.27.1644`; при несовпадении с `FileVersion` — ошибка `PLATFORM_VERSION_MISMATCH` |
| `--work-dir` | `ONEC_WORK_DIR` | Корень временных информационных баз и логов. Должен быть записываемым; по умолчанию `%LOCALAPPDATA%\1c-check` |
| `--allowed-roots` | `ONEC_ALLOWED_ROOTS` | Корни через `;`, внутри которых разрешены `source.path` и `baseCfPath`. Выход за пределы — `PATH_NOT_ALLOWED`; по умолчанию текущий каталог |
| `--user` | `ONEC_USER` | Пользователь ИБ, передаётся как `/N` |
| — | `ONEC_PASSWORD` | Пароль ИБ; только env, в логах и `commandRedacted` маскируется |
| `--timeout-sec` | `ONEC_TIMEOUT_SEC` | Таймаут шага проверки в секундах, по умолчанию 300; загрузка конфигурации — не менее 600 с |
| `--max-parallel` | `ONEC_MAX_PARALLEL` | Сколько проверок выполнять одновременно; по умолчанию 2, у каждой своя временная ИБ |
| `--keep-workspace` | `ONEC_KEEP_WORKSPACE` | Не удалять `runs/<runId>` после проверки — для отладки; логи в `logs/` сохраняются всегда |
| `--allow-version-mismatch` | `ONEC_PLATFORM_ALLOW_VERSION_MISMATCH` | Не сверять `FileVersion` с объявленной версией (например, для патченной сборки) |
Пример:
```powershell
node dist/src/index.js `
--platform-path 'C:\Program Files\1cv8\8.3.27.1644\bin\1cv8.exe' `
--platform-version 8.3.27.1644 `
--work-dir 'C:\1c-check' `
--allowed-roots 'C:\dev;C:\dist'
```
### `--work-dir`
Корень для временных данных проверки. Из него строятся:
- `<work-dir>\runs\<runId>\ib` — временная файловая ИБ, в которую загружается `.cf`, `.cfe` или XML;
- `<work-dir>\runs\<runId>\*.log` — логи шагов `create`, `load-*`, `check-*`;
- `<work-dir>\logs\<runId>.log` — постоянная копия лога, остаётся после удаления ИБ.
Что важно:
- каталог должен быть записываемым для MCP-сервера и `1cv8.exe`;
- временная ИБ может занимать сотни мегабайт — нужен запас места;
- `runs\<runId>` удаляется после проверки, если не указан `--keep-workspace`;
- на служебные файлы 1С в `%LOCALAPPDATA%\1C\1cv8` параметр не влияет;
- `--allowed-roots` на `--work-dir` не распространяется.
### `--allowed-roots`
Список разрешённых корней через `;`. Проверяются входные пути запросов:
`source.path` (`.cfe`, `.cf`, каталог XML, существующая ИБ) и `source.baseCfPath`.
Проверка идёт до создания временной ИБ; путь вне корней отклоняется с
`PATH_NOT_ALLOWED`.
- корень покрывает сам себя и все подкаталоги, граница проверяется по разделителю:
`C:\1C` не покрывает `C:\1C2`;
- регистр не важен, относительные пути разрешаются от каталога запуска сервера;
- это фильтр входных путей, а не песочница: `--work-dir`, `--platform-path`,
логи и служебные каталоги 1С им не ограничиваются;
- если не задан, используется текущий каталог сервера; `C:\` фактически отключает
ограничение, поэтому список лучше держать узким.
В текущем `dsh/cordis.patch.yml`: `--work-dir` — `%TEMP%\1c-check`,
`--allowed-roots` — `C:\dev;C:\Users\user\Desktop;C:\1C`.
## Подключение к DeepSeek Harness
В папке `dsh/` лежит config-only bundle:
- `dsh/package.json` — манифест с `dsh.bundle.patch`;
- `dsh/cordis.patch.yml` — запись `@deepseek-ai/dsh-mcp-client` с `serverName: onec`.
Порядок:
1. Соберите сервер (`npm run build`) и поправьте в `dsh/cordis.patch.yml` пути
к `dist/src/index.js`, `1cv8.exe` и разрешённые корни.
2. Установите bundle в профиль DSH: `plugin_manager`, действие `install_bundle`,
`target` — абсолютный путь к папке `dsh/` (например,
`C:\dev\mcp-syntax-checker\dsh`). У bundle есть локаль, описание и иконка
для карточки в **Plugins**.
3. Перезагрузите конфигурацию DSH и проверьте `mcp__onec__environment`.
Важно для DSH:
- `toolCallTimeoutMs` по умолчанию 60 с. Поэтому `waitSec` в tool ≤ 55 с:
если проверка не успела, tool вернёт `runId`, а результат забирается через
`mcp__onec__get_run`. Для синхронного ожидания поднимите `toolCallTimeoutMs`.
- DSH очищает унаследованное окружение от имён с `PASSWORD/SECRET/TOKEN`,
поэтому пароль задавайте явно в `env` bundle (через `!!js` или credentials).
- Сервер стартует без обращения к 1С; `failOnStartupError: true` безопасен,
ошибки платформы возвращаются в ответах tools.
## CLI
```powershell
# расширение
node dist/src/cli.js check-extension `
--cfe 'C:\dist\MyExt.cfe' --extension 'МоёРасширение' `
--platform-path 'C:\Program Files\1cv8\8.3.27.1644\bin\1cv8.exe' `
--platform-version 8.3.27.1644 `
--work-dir 'C:\1c-check' --allowed-roots 'C:\dist' `
--modes Server,ThinClient --json
# конфигурация
node dist/src/cli.js check-config --cf 'C:\dist\main.cf' --modes Server,ThinClient
# все расширения ИБ
node dist/src/cli.js check-all --ib 'C:\bases\MyBase'
# окружение
node dist/src/cli.js environment
```
Код возврата: `0` — ошибок нет, `1` — диагностики/сбой/таймаут, `2` — ошибка
конфигурации или аргументов.
## Статусы результата
| Статус | Значение |
|---|---|
| `ok` | Проверка прошла, ошибок нет |
| `diagnostics` | Найдены ошибки/предупреждения (код 101) |
| `failed` | Ошибка загрузки, запуска или конфигурации |
| `timeout` | Проверка не уложилась в таймаут |
| `cancelled` | Запуск отменён |
В `structuredContent` возвращается не более 500 диагностик; полное число —
в `diagnosticsTotal`, признак обрезки — `diagnosticsTruncated`.
## Ограничения
- Нельзя проверить отдельный `.bsl` или фрагмент кода: платформа проверяет
модули только в контексте конфигурации/расширения. Для сниппетов используйте
BSL Language Server.
- Расширение с заимствованными объектами надо проверять против подходящей
основной конфигурации (`baseCfPath`), иначе возможны ложные ошибки.
- Конфигуратор — GUI-процесс; в CI запускайте от залогиненного пользователя.
- Пароль 1С принимает только аргументом командной строки, он виден в списке
процессов. Используйте отдельного пользователя с минимальными правами.
## Разработка
```
src/
index.ts MCP entry (stdio)
cli.ts CLI
config.ts параметры запуска
platform.ts версия и короткий путь 1cv8.exe
core/check-service.ts
onec/args.ts сборка командной строки
onec/process.ts spawn, таймаут, taskkill
onec/log-parser.ts разбор /Out
onec/workspace.ts временная ИБ
mcp/server.ts tools
test/ unit-тесты и фикстуры логов
dsh/ config-only bundle для DSH
```