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

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

pip install -r requirements.txt

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

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)
• количеством обработанных файлов
• подсчетом диагностик по уровням важности
• топ-проблемами с указанием местоположения в файлах

1. Структурированный 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

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

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

1. "Source path does not exist"

• Всегда используйте абсолютные пути (например, C:\dev\project\src\Module.bsl)
• Относительные пути могут работать некорректно с MCP-сервером
• См. PATH_USAGE_GUIDE.md для подробностей
• Проверьте, что параметр srcDir указывает на существующий файл или каталог
• Проверьте права доступа к файлам

1. "Directory contains no BSL/OS files"

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

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

• Проверьте, что Java установлена и доступна в PATH
• Убедитесь, что лимиты памяти JVM заданы разумно
• Проверьте совместимость версии JAR BSL Language Server с вашей версией Java

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

• Проблема исправлена — вывод прогресс-бара теперь фильтруется
• Отображаются только реальные ошибки
• Обновитесь до последней версии, если видите эту проблему

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

• Проблема исправлена — устранено накопление обработчиков
• Каждое сообщение лога теперь выводится ровно один раз
• См. 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