MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

B
Bsl MCP Bridge
by @svhov
GitHub Repo(1 stars)

powerful instrument for AI-dev in 1C sphere

Created 3/29/2026
Updated about 19 hours ago
README
View Source
Repository documentation and setup instructions

🚀 bsl-mcp-bridge v2.0

👨‍💻 Реализовал: Сухов Андрей Евгеньевич совместно с Claude Opus 4.6 (Anthropic)

🎬 YouTube: @svhovbase — обзоры, демо и разбор решений по автоматизации 1С с ИИ

Подключите ИИ-агента к вашему проекту 1С — и он начнёт понимать код, а не просто читать текст. Этот MCP-сервер поднимает BSL Language Server на актуальной Java 21 (Temurin) внутри Docker-контейнера и открывает все его возможности для Cursor, Claude Code и любых других MCP-клиентов: поиск символов, навигация по определениям, диагностика ошибок, граф вызовов, рефакторинг. ИИ-агент получает точные, детерминированные ответы от языкового сервера вместо того, чтобы угадывать структуру кода по grep-ам — это экономит тысячи токенов на каждом запросе и радикально повышает качество работы с кодовой базой 1С.

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

  • 🔥 BSL LS поднимается заранее и сразу начинает подготовку кеша
  • 📊 Добавлена надстройка call_graph для формирования полного графа вызовов силами BSL LS
  • 🔄 Автоматическая нормализация URI — агент может передавать пути в любом формате
  • 📂 Умное разрешение путей — автоматический маппинг хостовых, контейнерных и относительных путей
  • 🧠 Автоматическое открытие документов (didOpen) перед операциями — не нужно вручную

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

┌─────────────────────────────────────────────────────────────────┐
│  HOST (Windows/Linux/macOS)                                     │
│                                                                 │
│  ┌──────────────┐      ┌──────────────────────────────────────┐ │
│  │   Cursor     │      │         Кодовая база 1С              │ │
│  │   (IDE)      │      │   D:/Projects/MyConfig               │ │
│  └──────┬───────┘      └──────────────┬───────────────────────┘ │
│         │ HTTP / 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

Через HTTP (рекомендуется 🌟)

Установи MCP_TRANSPORT=http и MCP_HTTP_PORT=8010 в .env, затем в конфиге MCP-клиента:

{
  "mcpServers": {
    "lsp-bsl-bridge": {
      "type": "streamable-http",
      "url": "http://<server-ip>:8010/mcp"
    }
  }
}

Через stdio (docker exec)

{
  "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

🛤️ Форматы URI для инструментов

Все инструменты, принимающие uri, поддерживают любой из следующих форматов:

| Формат | Пример | |--------|--------| | 📌 Относительный путь (рекомендуется) | do-extension/CommonModules/МойМодуль/Ext/Module.bsl | | 📌 Контейнерный абсолютный | /projects/do-extension/CommonModules/МойМодуль/Ext/Module.bsl | | 📌 File URI | file:///projects/do-extension/CommonModules/МойМодуль/Ext/Module.bsl | | 📌 Хостовый Windows путь | F:\path\to\file.bsl (автоматически маппится в контейнерный) | | 📌 Произвольный путь | file:///workspace/project/do-extension/... (умное разрешение) |

🧠 Bridge автоматически нормализует любой путь в формат, понятный LSP серверу. Если путь не распознан, выполняется поиск по суффиксу в контейнерном workspace.

🆕 Последние изменения

🔄 Умная нормализация URI (resolveUnknownPath)

Агенты на удалённых машинах могут передавать пути в произвольном формате (например /workspace/do-project/...). Bridge теперь автоматически находит файл в контейнере, отбрасывая неизвестные префиксы и проверяя суффиксы пути.

📂 Автоматическое открытие документов (ensureDocumentOpen)

LSP протокол требует textDocument/didOpen перед операциями с документом. Bridge теперь:

  • ✅ Автоматически открывает документ перед hover, diagnostics и другими операциями
  • ✅ Отслеживает уже открытые документы и не дублирует didOpen (что ломало некоторые LSP серверы)

🔍 Улучшенный symbol_explore

  • ✅ Использует уже подключённые языковые клиенты (быстрый путь) вместо сканирования файловой системы
  • ✅ Fallback на SearchTextInAllLanguages если определение языков не сработало
  • ✅ Исправлен маппинг серверных имён → ID языков в GetConnectedLanguages

🩺 Улучшенная обработка ошибок в document_diagnostics

  • ✅ LSP ошибка -32603 (Internal error) теперь возвращает понятное сообщение: "Файл не найден в проекте LSP сервера"
  • ✅ Подсказки о возможных причинах и решениях

🔄 Принудительная переиндексация в did_change_watched_files

Раньше did_change_watched_files только отправлял LSP-уведомление, но LSP сервер не перечитывал уже загруженные документы — диагностики и символы оставались от старой версии файла. Теперь bridge:

  • ✅ Автоматически закрывает документ (didClose) при получении события Changed/Created
  • ✅ Переоткрывает с актуальным содержимым (didOpen) — LSP перечитывает файл с диска
  • ✅ Удаляет из трекинга при событии Deleted
  • 💡 После вызова did_change_watched_files все инструменты (diagnostics, hover, symbol_explore) сразу видят новую версию файла

🐛 Исправление хранения клиентов в session mode

  • ✅ Исправлен баг: клиенты в session mode сохранялись с ключом language вместо server, что приводило к созданию дублирующих подключений

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

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

  • [ ] 🧪 Инкрементальная диагностика — запускать document_diagnostics автоматически после каждого did_change_watched_files и кешировать результат, чтобы агент мог получить диагностики мгновенно без ожидания LSP
  • [ ] 📊 Дашборд здоровья проекта — новый tool project_health, агрегирующий количество ошибок/предупреждений по всем файлам, топ-10 проблемных модулей и тренд (стало лучше/хуже с прошлого запуска)
  • [ ] 🔗 Мультипроектный режим — поддержка нескольких BSL LS инстансов в одном контейнере для одновременной работы с конфигурацией, расширениями и внешними обработками с независимой индексацией
  • [ ] ⚡ Warm cache при старте — предварительный didOpen для наиболее часто используемых модулей (определяется по git log) сразу после завершения индексации, чтобы первый hover/diagnostics не ждал загрузки
  • [ ] 🔍 Семантический поиск по коду — tool code_search с поддержкой нечёткого поиска по телам процедур (не только по именам символов), включая поиск паттернов вида "все места где вызывается СообщитьПользователю внутри Попытка-Исключение"
  • [ ] 📝 Автогенерация описаний процедур — tool generate_doc, который на основе анализа тела процедуры (параметры, типы, вызовы) формирует заготовку комментария в формате стандарта 1С
  • [ ] 🔄 WebSocket File Watcher — замена polling на push-уведомления через WebSocket канал между хостом и контейнером для мгновенной реакции на изменения файлов без 30-секундной задержки
  • [ ] 🛡️ Профили диагностик — предустановленные конфигурации BSL LS (strict, moderate, relaxed) с возможностью переключения через MCP tool без перезапуска контейнера

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

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

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

Quick Setup
Installation guide for this server

Installation Command (package not published)

git clone https://github.com/svhov/bsl-mcp-bridge
Manual Installation: Please check the README for detailed setup instructions and any additional dependencies required.

Cursor configuration (mcp.json)

{ "mcpServers": { "svhov-bsl-mcp-bridge": { "command": "git", "args": [ "clone", "https://github.com/svhov/bsl-mcp-bridge" ] } } }