Запуск в режиме MCP¶

BSL Language Server умеет работать как сервер Model Context Protocol (MCP) — открывать возможности анализа кода 1С (BSL) и OneScript AI-агентам и инструментам, которые поддерживают MCP.

Инструменты MCP работают поверх того же движка, что и LSP-режим: тот же разбор, те же провайдеры. Рабочие папки регистрируются инструментами register_workspace_folder/list_workspace_folders — см. раздел «Рабочие папки» ниже.

Экспериментальная возможность

Режим MCP основан на Spring AI 2.0 (на момент написания — milestone-версия). API и поведение могут меняться.

Режимы запуска¶

MCP можно поднять несколькими способами.

Отдельный MCP-сервер (команда `mcp`)¶

Транспорт выбирается параметром --protocol: stdio (по умолчанию), sse или streamable. LSP при этом не запускается.

stdio — стандартный способ подключения локальных инструментов:

java -jar bsl-language-server.jar mcp
# эквивалентно: java -jar bsl-language-server.jar mcp --protocol stdio

sse — Server-Sent Events по HTTP на встроенном веб-сервере (эндпоинт /sse, сообщения на /mcp/message):

java -jar bsl-language-server.jar mcp --protocol sse --server.port=8080

streamable — Streamable HTTP по HTTP на встроенном веб-сервере (эндпоинт /mcp):

java -jar bsl-language-server.jar mcp --protocol streamable --server.port=8080

Рядом с LSP по stdio¶

LSP остаётся на stdio, а MCP дополнительно поднимается по Streamable HTTP на встроенном веб-сервере. Включается флагом --mcp. Команда lsp — режим по умолчанию, поэтому её можно не указывать:

java -jar bsl-language-server.jar --mcp --server.port=8080
# эквивалентно: java -jar bsl-language-server.jar lsp --mcp --server.port=8080

Рядом с LSP по websocket¶

LSP по websocket и MCP по Streamable HTTP на одном веб-сервере:

java -jar bsl-language-server.jar websocket --mcp --server.port=8080

Рабочие папки¶

Терминология — из LSP: рабочая папка (workspace folder) — это один корневой каталог проекта, а множество зарегистрированных папок и составляет рабочую область (workspace), которую обслуживает сервер. Регистрируется и передаётся в инструменты именно папка.

Все инструменты анализа работают только внутри зарегистрированной рабочей папки — 1С-конфигурации или OneScript-проекта, исходники которого проиндексированы. Файл вне всех зарегистрированных папок не анализируется, а инструменты без привязки к файлу (type_info, global_member_info, global_member_search) требуют явного параметра workspaceFolder.

Порядок работы клиента:

list_workspace_folders — узнать, что уже зарегистрировано, и получить значения uri.
register_workspace_folder с каталогом проекта — если нужного проекта в списке нет. Передавать нужно корень рабочей папки: тот каталог, который открывают в IDE и который LSP-клиент присылает как workspace folder, а не подкаталог с исходниками. Внутри него лежат исходники (src/cf конфигурации, исходники OneScript) и, если он есть, конфигурационный файл .bsl-language-server.json — он читается только из корня папки. Инструмент индексирует исходники и возвращает uri папки; повторная регистрация того же каталога переиндексацию не запускает.
unregister_workspace_folder — освободить индекс, когда проект больше не нужен. Инструмент удаляет только те папки, которые были зарегистрированы через MCP: папку, пришедшую от LSP-клиента, он не забирает — это рабочая папка редактора, и вернуть её клиент не сможет. Папку, которую сверх регистрации объявил корнем сам клиент (см. MCP roots ниже), сервер оставит проиндексированной и сообщит об этом признаком stillDeclaredByRoots: папка уходит, когда её отпустит последний источник.

Сообщения об ошибках самодостаточны: при неизвестном или отсутствующем workspaceFolder сервер перечисляет зарегистрированные папки и указывает, каким инструментом зарегистрировать недостающую, — агент может исправиться без участия человека.

Дополнительные источники рабочих папок:

LSP. В комбинированных режимах (lsp --mcp, websocket --mcp) рабочие папки приходят от LSP-клиента (workspace folders) в тот же общий контекст — регистрировать их через MCP не нужно, они сразу видны в list_workspace_folders.
MCP roots. Корни, объявленные клиентом через MCP roots, по-прежнему индексируются автоматически, включая пересинхронизацию по notifications/roots/list_changed. Это работает, пока сервер говорит по ревизии протокола 2025-11-25 — той, что реализует используемый MCP SDK, — где roots ещё активны.

MCP roots объявлены устаревшими

В ревизии спецификации 2026-07-28 механизм roots (вместе с sampling и logging) помечен как deprecated, а уведомление notifications/roots/list_changed из протокола удалено. В качестве замены спецификация предлагает передавать каталоги через параметры инструментов и конфигурацию сервера — это и делают register_workspace_folder/list_workspace_folders. Поддержка roots сохраняется как совместимость со старыми клиентами; по политике жизненного цикла возможностей MCP удалить их могут не раньше чем через 12 месяцев после этой ревизии, а в сервере они уйдут вместе с переходом на неё.

Доступные инструменты¶

Инструмент	Назначение
`list_workspace_folders`	Зарегистрированные рабочие папки: `uri` для остальных инструментов и имя
`register_workspace_folder`	Регистрация каталога проекта как рабочей папки с индексацией исходников; имя можно задать явно, иначе берётся имя каталога
`unregister_workspace_folder`	Удаление рабочей папки и освобождение её индекса
`analyze_file`	Диагностики по файлу
`document_symbols`	Дерево символов файла (методы, области, переменные)
`find_references`	Все ссылки на символ в позиции
`call_hierarchy`	Входящие и исходящие вызовы метода/процедуры в позиции
`hover`	Подсказка по символу (сигнатура, тип, документация)
`definition`	Переход к объявлению символа
`type_info`	По имени типа (например, `Массив`) — его свойства, методы, события и конструкторы с сигнатурами, а также метаинформация самого типа и его членов (версии появления/устаревания, контексты исполнения, замечания, примеры, «См. также»)
`global_member_info`	По имени глобального члена (например, `Сообщить`/`Message`) — функция, свойство или системное перечисление с сигнатурами и метаинформацией
`global_member_search`	Поиск членов глобального контекста — функции (`СтартовыйСценарий`/`StartupScript`), свойства (`Метаданные`/`Metadata`) и системные перечисления; нечёткое совпадение и ранжирование, как в автодополнении, с группировкой по категориям; можно сузить выборку категориями
`type_at_position`	Выведенный тип выражения под курсором и доступные на нём методы и свойства

Позиции (line, character) нумеруются с нуля, как в LSP.

Ни один инструмент не меняет файлы на диске. Инструменты анализа помечены как read-only (readOnlyHint) — клиент не должен спрашивать подтверждение на каждый вызов. Инструменты управления рабочими папками меняют состояние сервера, поэтому read-only не помечены; unregister_workspace_folder дополнительно помечен разрушающим (destructiveHint), так как выбрасывает собранный индекс, — на него клиент вправе запросить подтверждение.

Параметры запуска¶

Параметр	Режим	Назначение
`-c`, `--configuration` `<path>`	все	Путь к глобальному конфигурационному файлу (см. Конфигурационный файл)
`--protocol` `<stdio\\|sse\\|streamable>`	`mcp`	Транспорт отдельного MCP-сервера: `stdio` (по умолчанию), `sse` или `streamable`
`--mcp`	`lsp` (по умолчанию), `websocket`	Дополнительно поднять MCP по Streamable HTTP
`--mcp-path` `<path>`	`lsp --mcp`, `websocket --mcp`	Адрес MCP-эндпоинта (по умолчанию `/mcp`)
`--server.port=<port>`	`mcp --protocol sse\\|streamable`, `lsp --mcp`, `websocket --mcp`	Порт встроенного веб-сервера

Примеры конфигурации клиента¶

stdio¶

Клиент сам запускает сервер и общается с ним по stdio (формат mcpServers):

{
  "mcpServers": {
    "bsl-language-server": {
      "command": "java",
      "args": ["-jar", "/path/to/bsl-language-server.jar", "mcp"]
    }
  }
}

Streamable HTTP¶

Сервер запущен отдельно (--mcp или websocket --mcp), клиент подключается к эндпоинту по URL:

{
  "mcpServers": {
    "bsl-language-server": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Адрес по умолчанию — http://<host>:<port>/mcp; путь меняется параметром --mcp-path, порт — --server.port.