# BSL MCP Server 

MCP-сервер bsl-mcp анализирует каталог через [BSL Language Server](https://github.com/1c-syntax/bsl-language-server) и отдает ошибки/предупреждения в JSON. Платформенную проверку синтаксиса 1С и функций не выполняет.

## Возможности

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

## Установка

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

* Python 3.10 или новее
* Java Runtime Environment (JRE) 8 или новее
* [JAR-файл BSL Language Server](https://github.com/1c-syntax/bsl-language-server/releases)

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

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

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

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

```bash
pip install -r requirements.txt
```

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

```bash
pip install -e .
```

## Настройка

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

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

```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

**Пример:**

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

#### `bsl_format`

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

**Параметры:**

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

**Пример:**

```json
{
  "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` в корне проекта:

```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
```

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

```bash
python -m pytest tests/
```

### Сборка

```bash
python -m build
```

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

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

2. **"Source path does not exist"**

   * **Всегда используйте абсолютные пути** (например, `C:\dev\project\src\Module.bsl`)
   * Относительные пути могут работать некорректно с MCP-сервером
   * См. [PATH_USAGE_GUIDE.md](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](FIX_DUPLICATE_LOGS.md) для деталей

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

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

* **ERROR** (рекомендуется для продакшена) — только критические ошибки
* **WARNING** (по умолчанию) — предупреждения и ошибки
* **INFO** — информационные сообщения
* **DEBUG** — подробная отладочная информация

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

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

Подробности см. в [LOGGING_CONFIGURATION.md](LOGGING_CONFIGURATION.md).

## Лицензия

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

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

1. Сделайте форк репозитория
2. Создайте feature-ветку
3. Внесите изменения
4. Отправьте pull request

## Поддержка

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

* Создайте issue в репозитории
* Изучите существующую документацию
* Ознакомьтесь с документацией BSL Language Server