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

MCP Servers