Mcp Bsl Lsp Bridge

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/     20 / cognitive > 15) |
| `module_health` | Комбо: complexity + quality_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`

---

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

- [Конфигурация](docs/configuration.md) — параметры `.env` и `lsp_config.json`
- [Архитектура кода](docs/codebase-guide.md) — структура проекта для контрибьюторов
- [Справочник tools](docs/tools/tools-reference.md) — полное описание инструментов
- [Tool → LSP mapping](docs/tools/lsp-methods-map.md) — какие 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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SteelMorgan](https://github.com/SteelMorgan)
- **Source:** [SteelMorgan/mcp-bsl-lsp-bridge](https://github.com/SteelMorgan/mcp-bsl-lsp-bridge)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.