Skip to main content
Glama
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
```