MCP BSL LS Bridge

MCP-сервер, который даёт ИИ-агентам (Cursor, Claude Code и др.) доступ к возможностям BSL Language Server для работы с кодом 1С и OneScript: навигация, поиск, диагностика, рефакторинг. Цель - обеспечить детерминированные операции над кодом и экономия токенов (конечно модель всё может сделать грепами, но сколько токенов сожжет?)

Особенности проекта

• BSL LS поднимается заранее и сразу начинает подготовку кеша.
• добавлена надстройка call_graph для формирования полного графа вызовов силами BSL LS

Как это работает

┌─────────────────────────────────────────────────────────────────┐
│  HOST (Windows/Linux/macOS)                                     │
│                                                                 │
│  ┌──────────────┐      ┌──────────────────────────────────────┐ │
│  │   Cursor     │      │         Кодовая база 1С              │ │
│  │   (IDE)      │      │   D:/Projects/MyConfig               │ │
│  └──────┬───────┘      └──────────────┬───────────────────────┘ │
│         │ docker exec -i              │ volume mount            │
└─────────┼─────────────────────────────┼─────────────────────────┘
          │                             │
          ▼                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  DOCKER CONTAINER                                               │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  mcp-lsp-bridge (MCP Server)                             │   │
│  │  Принимает запросы от IDE, транслирует в LSP             │   │
│  └──────────────────────┬───────────────────────────────────┘   │
│                         │ TCP :9999                             │
│  ┌──────────────────────▼───────────────────────────────────┐   │
│  │  lsp-session-manager                                     │   │
│  │  Держит BSL LS запущенным, следит за индексацией         │   │
│  │  ┌────────────────────────────────────────────────────┐  │   │
│  │  │  File Watcher (polling)                            │  │   │
│  │  │  Отслеживает изменения файлов, уведомляет BSL LS   │  │   │
│  │  └────────────────────────────────────────────────────┘  │   │
│  └──────────────────────┬───────────────────────────────────┘   │
│                         │ stdio                                 │
│  ┌──────────────────────▼───────────────────────────────────┐   │
│  │  BSL Language Server (Java)                              │   │
│  │  Индексация, диагностика, навигация, рефакторинг         │   │
│  └──────────────────────────────────────────────────────────┘   │
│                         ▲                                       │
│  ┌──────────────────────┴───────────────────────────────────┐   │
│  │  /projects (смонтированная кодовая база)                 │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Требования

• Docker + Docker Compose
• IDE с поддержкой MCP (Cursor, Claude Code)
• 8+ ГБ RAM (BSL LS требователен к памяти на больших проектах)

Быстрый старт

Принцип: один проект = один контейнер (каталог проекта задаётся в .env)

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

git clone https://github.com/SteelMorgan/mcp-bsl-lsp-bridge.git
cd mcp-bsl-lsp-bridge

2. Настрой окружение

cp env.example .env

Отредактируй .env — минимум нужно указать:

• MCP_PROJECT_NAME — имя проекта (будет частью имени контейнера)
• HOST_PROJECTS_ROOT — путь к коду 1С на хосте
• WORKSPACE_ROOT — путь внутри контейнера к каталогу с кодом

Настройка WORKSPACE_ROOT

WORKSPACE_ROOT определяет корневой каталог для BSL LS внутри контейнера.

Один каталог с кодом:

WORKSPACE_ROOT=/projects/main-config

Основная конфигурация + расширения: Если нужно работать с несколькими каталогами кода (конфигурация + расширения), укажите их общий родительский каталог:

# Структура:
# /projects/
#   ├── main-config/    <- основная конфигурация
#   └── extension1/     <- расширение

WORKSPACE_ROOT=/projects

BSL LS проиндексирует все подкаталоги и будет видеть связи между конфигурацией и расширениями.

Все параметры описаны в env.example.

3. Собери и запусти контейнер

docker compose build
docker compose up -d

Имя контейнера: ${MCP_CONTAINER_PREFIX}-${MCP_PROJECT_NAME} (например mcp-lsp-demo)

4. Подключи MCP в IDE

Создай .cursor/mcp.json (или аналог для твоего MCP-клиента):

{
  "mcpServers": {
    "lsp-bsl-bridge": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp-lsp-demo",
        "mcp-lsp-bridge"
      ],
      "env": {}
    }
  }
}

Замени mcp-lsp-demo на реальное имя контейнера.

5. Проверь подключение

В IDE вызови tool lsp_status — должен показать статус подключения и прогресс индексации.

---

Возможности (Tools)

Поиск и навигация

Tool	Что делает	Когда использовать
project_analysis	Универсальный поиск: символы, файлы, текст	Найти процедуру по имени, обзор проекта
symbol_explore	Детальный поиск с кодом и документацией	Нужна полная информация о символе
definition	Перейти к определению	"Где объявлена эта процедура?"
hover	Документация и сигнатура	"Какие параметры у функции?"
get_range_content	Получить фрагмент кода	Извлечь код по координатам

Анализ зависимостей

Tool	Что делает	Когда использовать
call_hierarchy	Кто вызывает / что вызывает (1 уровень)	Быстро понять связи
call_graph	Полный граф вызовов	Глубокий анализ перед рефакторингом

Диагностика и проверка кода

Tool	Что делает	Когда использовать
document_diagnostics	Синтаксические ошибки, предупреждения, стилистика	Проверка кода перед коммитом, поиск ошибок
code_actions	Автоматические исправления	Quick-fix для найденных ошибок

document_diagnostics — основной инструмент для синтаксического контроля. Возвращает все диагностики BSL LS: синтаксические ошибки, неиспользуемые переменные, deprecated методы, нарушения стиля и т.д.

Рефакторинг

Tool	Что делает	Когда использовать
prepare_rename	Проверить возможность переименования	Перед переименованием
rename	Переименовать символ везде	apply=false для preview

Служебные

Tool	Что делает	Когда использовать
lsp_status	Статус LSP и прогресс индексации	Проверить готовность
did_change_watched_files	Уведомить об изменении файлов	После git pull

Подробнее: docs/tools/tools-reference.md

---

Документация

• Конфигурация — параметры .env и lsp_config.json
• Архитектура кода — структура проекта для контрибьюторов
• Справочник tools — полное описание инструментов
• Tool → LSP mapping — какие LSP методы вызывает каждый tool

---

Дорожная карта

• Улучшить File Watcher для Win + Docker (пока polling, ищем решения)
• Автообновление BSL LS при запуске контейнера
• Сократить количество tools, упаковать логику в навыки
• Сделать решение под Windows. Если использовать докер в Windows (WSL 2), то скорость чтения примаунченных каталогов ограничена. 40к файлов у меня читает около 12 минут. 9к файлов - в районе 3-5 минут. (упирается в общую "пропускную способность докера).

---

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

См. CONTRIBUTING.md. Баги и идеи — через Issues.

Благодарности

https://github.com/rockerBOO/mcp-lsp-bridge - взято за основу https://github.com/nixel2007 - за консультации по BSL LS