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 — имя проекта (будет частью имени контейнера)
• WORKSPACE_ROOT — путь внутри контейнера к каталогу с кодом (пример ниже)

Выбор режима монтирования кода (host vs sandbox)

Этот проект поддерживает 2 способа подключить код 1С. Выбираешь один.

1) Host filesystem (bind mount) — код 1С лежит на хосте Docker (Windows/Linux/macOS).

• В .env укажи HOST_PROJECTS_ROOT (путь на хосте Docker) и при необходимости PROJECTS_ROOT (как каталог будет виден внутри контейнера).
• Запуск: docker-compose.yml

2) Sandbox workspace volume (named volume) — код 1С живёт в external named volume песочницы (Dev Containers / отдельный sandbox-контейнер).

• В .env укажи PROJECTS_VOLUME_NAME (например agent-work-sandbox-1c) и выставь PROJECTS_ROOT так, как тебе удобно видеть workspace внутри контейнера (обычно /workspaces/work, чтобы совпадало с путями в IDE).
• Запуск: docker-compose.sandbox-volume.yml

Настройка WORKSPACE_ROOT

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

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

WORKSPACE_ROOT=/projects/main-config

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

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

WORKSPACE_ROOT=/projects

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

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

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

Host filesystem (bind mount)

docker compose -f docker-compose.yml build
docker compose -f docker-compose.yml up -d

Sandbox workspace volume (named volume)

docker compose -f docker-compose.sandbox-volume.yml build
docker compose -f docker-compose.sandbox-volume.yml 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)

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

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

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

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

Рефакторинг

Служебные

Подробнее: 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