BSL MCP Server

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

Возможности

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

Установка

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

• 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