BSL MCP Server

MCP-сервер bsl-mcp анализирует каталог через BSL Language Server и отдает ошибки/предупреждения в JSON. Платформенную проверку синтаксиса 1С и функций не выполняет.

Возможности

• BSL-анализ: запуск комплексного анализа файлов BSL/OS с подробной диагностикой

• Форматирование кода: приведение BSL-файлов к правилам BSL Language Server

Related MCP server: LSP MCP

Установка

Предварительные требования

• Python 3.10 или новее

• Java Runtime Environment (JRE) 8 или новее

• JAR-файл BSL Language Server

Установка из исходников

1. Клонируйте репозиторий:

git clone <repository-url>
cd mcp-bsl-python

2. Установите зависимости:

pip install -r requirements.txt

3. Установите пакет:

pip install -e .

Настройка

Конфигурация MCP

Добавьте в ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bsl-mcp": {
      "command": "python",
      "args": ["-m", "mcp_bsl.server"],
      "env": {
        "BSL_JAR": "C:\\1C\\AI\\bsl\\bsl-language-server-0.24.2-exec.jar",
        "BSL_MEMORY_MB": "4096",
        "BSL_CONFIG": "C:\\1C\\AI\\bsl\\.bsl-language-server.json",
        "BSL_LOG_LEVEL": "ERROR"
      },
      "debug": false
    }
  }
}

Примечание: значение BSL_LOG_LEVEL установлено в ERROR, чтобы минимизировать вывод логов в Cursor IDE. Для поиска проблем используйте DEBUG.

Использование

В Cursor IDE

# Анализ директории (используйте АБСОЛЮТНЫЙ путь!)
mcp bsl-mcp C:\1C\lk\src\CommonModules\

# Если нужны DEBUG логи для отладки:
# В mcp.json измените: "BSL_LOG_LEVEL": "DEBUG"

Доступные инструменты

bsl_analyze

Запуск анализа BSL по каталогу исходников или файлу.

Параметры:

• srcDir (обязательно): путь к каталогу или файлу с .bsl/.os

Пример:

{
  "name": "bsl_analyze",
  "arguments": {
    "srcDir": "C:\\1C\\MyProject\\src"
  }
}

bsl_format

Форматирование BSL-файлов в каталоге исходников.

Параметры:

• srcDir (обязательно): путь к каталогу или файлу с .bsl/.os

Пример:

{
  "name": "bsl_format",
  "arguments": {
    "srcDir": "C:\\1C\\MyProject\\src"
  }
}

Форматы вывода

Результаты анализа

Инструмент bsl_analyze выдает:

1. Человекочитаемую сводку с:

   • статусом (success/error)

   • количеством обработанных файлов

   • подсчетом диагностик по уровням важности

   • топ-проблемами с указанием местоположения в файлах

2. Структурированный JSON-вывод с:

   • полной диагностической информацией

   • путями к файлам, номерами строк/столбцов

   • уровнями важности и сообщениями

   • сводной статистикой

Результаты форматирования

Инструмент bsl_format выдает:

• статус успех/ошибка

• количество обработанных файлов

• сырой вывод BSL Language Server

Конфигурация BSL Language Server

Создайте файл .bsl-language-server.json в корне проекта:

{
  "language": "bsl",
  "diagnostics": {
    "computeTrigger": "onSave",
    "skipSupport": "never"
  },
  "codeLens": {
    "showCognitiveComplexity": true,
    "showCyclomaticComplexity": true
  },
  "traceLog": {
    "enabled": false
  }
}

Обработка ошибок

Сервер обрабатывает различные нештатные ситуации:

• Файл не найден: проверяет корректность путей до запуска

• Неверный JAR: проверяет наличие JAR-файла BSL Language Server

• Таймаут: 5 минут для анализа, 2 минуты для форматирования

• Лимиты памяти: настраиваемое выделение памяти JVM

• Ошибки разбора: корректная обработка некорректного вывода BSL

Разработка

Структура проекта

mcp-bsl-python/
├── pyproject.toml          # Метаданные проекта и зависимости
├── requirements.txt        # Зависимости
├── README.md               # Этот файл
├── src/
│   └── mcp_bsl/
│       ├── __init__.py
│       ├── server.py       # Основная реализация MCP-сервера
│       ├── bsl_runner.py   # Обертка запуска JAR BSL
│       └── config.py       # Управление конфигурацией
└── .bsl-language-server.json  # Пример конфигурации BSL

Запуск тестов

python -m pytest tests/

Сборка

python -m build

Устранение неполадок

Типичные проблемы

2. "Source path does not exist"

   • Всегда используйте абсолютные пути (например, C:\dev\project\src\Module.bsl)

   • Относительные пути могут работать некорректно с MCP-сервером

   • См. PATH_USAGE_GUIDE.md для подробностей

   • Проверьте, что параметр srcDir указывает на существующий файл или каталог

   • Проверьте права доступа к файлам

3. "Directory contains no BSL/OS files"

   • Убедитесь, что каталог содержит файлы .bsl или .os

   • Проверьте корректность расширений файлов

4. Ошибки выполнения Java

   • Проверьте, что Java установлена и доступна в PATH

   • Убедитесь, что лимиты памяти JVM заданы разумно

   • Проверьте совместимость версии JAR BSL Language Server с вашей версией Java

5. Сообщение "ERROR: BSL analysis stderr detected"

   • Проблема исправлена — вывод прогресс-бара теперь фильтруется

   • Отображаются только реальные ошибки

   • Обновитесь до последней версии, если видите эту проблему

6. Дублирование сообщений логов

   • Проблема исправлена — устранено накопление обработчиков

   • Каждое сообщение лога теперь выводится ровно один раз

   • См. FIX_DUPLICATE_LOGS.md для деталей

Режим отладки и логирование

Сервер поддерживает уровни логирования, управляемые переменной окружения BSL_LOG_LEVEL:

• ERROR (рекомендуется для продакшена) — только критические ошибки

• WARNING (по умолчанию) — предупреждения и ошибки

• INFO — информационные сообщения

• DEBUG — подробная отладочная информация

Чтобы включить отладочное логирование в конфигурации MCP:

{
  "mcpServers": {
    "bsl-mcp": {
      "env": {
        "BSL_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Подробности см. в LOGGING_CONFIGURATION.md.

Лицензия

Проект распространяется по лицензии MIT.

Вклад в проект

1. Сделайте форк репозитория

2. Создайте feature-ветку

3. Внесите изменения

4. Отправьте pull request

Поддержка

Если у вас есть вопросы или вы столкнулись с проблемами:

• Создайте issue в репозитории

• Изучите существующую документацию

• Ознакомьтесь с документацией BSL Language Server