SkillAgentSearch skills...

MCP Bsl Platform Help Context

MCP-сервер: документация API платформы 1С, строгая типизация BSL, стандарты кода. Keyword, semantic и hybrid поиск для AI-ассистентов.

GenerateConvertImprove

Install / Use

/learn @Desko77/MCP Bsl Platform Help Context
About this skill

Quality Score

0/100

Supported Platforms

Claude Code
Cursor

README

MCP BSL Platform Help Context

MCP-сервер для доступа к документации API платформы 1С:Предприятие

Python License MCP

Python-порт mcp-bsl-platform-context (Kotlin/Spring Boot).

Возможности

  • Три режима поиска: keyword (нечёткий), semantic (embeddings + Qdrant), hybrid (оба + RRF-слияние + reranker)
  • Детальная информация о типах, методах, свойствах, конструкторах платформы 1С
  • Навигация по объектной модели платформы
  • Документация по строгой типизации BSL и рекомендации по стилю кода
  • Два источника данных: прямое чтение HBK файлов или pre-exported JSON
  • Три транспорта: STDIO (для Claude Desktop, Cursor), SSE и Streamable HTTP
  • Мультиверсионность: автоматическое обнаружение версий платформы с выбором ближайшей
  • YAML-конфигурация с поддержкой переменных окружения и CLI-аргументов
  • Двуязычность: русские и английские имена API, поиск регистронезависимый

MCP-инструменты

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

| Инструмент | Описание | Параметры | |------------|----------|-----------| | search | Поиск по API платформы 1С. Поддерживает keyword, semantic и hybrid режимы. Используйте термины 1С (русские или английские) для лучших результатов | query (строка поиска), mode? (keyword/semantic/hybrid), type? (method/property/type), limit? (1–50, по умолчанию 10) | | info | Детальная информация о конкретном элементе API по точному имени | name (точное имя, например НайтиПоСсылке), type (method/property/type) | | get_member | Получить информацию о методе или свойстве конкретного типа | type_name (имя типа), member_name (имя метода/свойства) | | get_members | Полный список методов и свойств типа | type_name (имя типа, например ТаблицаЗначений) | | get_constructors | Сигнатуры конструкторов для создания экземпляров типа | type_name (имя типа) | | get_platform_info | Информация о текущей версии платформы и список доступных версий | — |

Документация и стандарты кода

| Инструмент | Описание | Параметры | |------------|----------|-----------| | get_coding_guideline | Рекомендации по стилю кода BSL (1С:Предприятие) | — | | get_strict_typing_info | Документация по строгой типизации BSL. Используйте topic='topics' для списка тем | topic (название темы или topics) | | search_strict_typing | Текстовый поиск по документации строгой типизации с контекстом | query (поисковый запрос) |

Режимы поиска

Инструмент search поддерживает три режима (параметр mode, по умолчанию из конфигурации):

| Режим | Движок | Описание | |-------|--------|----------| | keyword | SimpleSearchEngine | 4-стратегийный поиск: точное совпадение, префикс, составные имена, порядок слов | | semantic | SemanticSearchEngine | Векторный поиск: embedding запроса → ANN в Qdrant → опциональный cross-encoder rerank | | hybrid | HybridSearchEngine | Keyword + semantic параллельно → RRF-слияние (k=60) → rerank |

RAG-пайплайн: DocumentBuilder → EmbeddingProvider → Qdrant embedded → Reranker

Модели по умолчанию:

  • Embedder: ai-forever/ru-en-RoSBERTa
  • Reranker: DiTy/cross-encoder-russian-msmarco

Провайдеры: local (sentence-transformers) или openai-compatible (любой API в формате OpenAI)

Установка

pip install -e .                # Базовая установка (keyword search)
pip install -e ".[dev]"         # + pytest для разработки
pip install -e ".[local]"       # + sentence-transformers, torch (semantic/hybrid search)

Зависимости

  • Python 3.10+
  • fastmcp >= 2.0
  • beautifulsoup4 >= 4.12
  • lxml >= 5.0
  • click >= 8.1
  • PyYAML >= 6.0

Конфигурация

YAML-файл (рекомендуется)

Скопируйте config.example.yml в config.yml и настройте под своё окружение:

cp config.example.yml config.yml
mcp-bsl-context -c config.yml

Приоритет конфигурации: YAML < переменные окружения (MCP_BSL_*) < CLI-аргументы.

Основные секции: server, platform, search, embeddings, reranker, storage, index, docs.

Параметры CLI

--config, -c               Путь к YAML-файлу конфигурации
--platform-path, -p        Путь к каталогу установки 1С
--platform-version         Предпочтительная версия платформы (e.g., 8.3.20)
--mode, -m                 Транспорт: stdio (по умолчанию), sse или streamable-http
--port                     Порт для HTTP-сервера (по умолчанию: 8080)
--data-source              Источник данных: hbk или json
--json-path                Путь к каталогу с JSON-файлами
--verbose, -v              Включить отладочное логирование

Переменные окружения

| CLI-аргумент | Переменная окружения | По умолчанию | |---|---|---| | --platform-path | MCP_BSL_PLATFORM_PATH | (обязателен для hbk) | | --platform-version | MCP_BSL_PLATFORM_VERSION | null (авто — последняя) | | --mode | MCP_BSL_MODE | stdio | | --port | MCP_BSL_PORT | 8080 | | --data-source | MCP_BSL_DATA_SOURCE | hbk | | --json-path | MCP_BSL_JSON_PATH | — | | --verbose | MCP_BSL_VERBOSE | false | | --host | MCP_BSL_HOST | 127.0.0.1 | | — | MCP_BSL_DOCS_STRICT_TYPES_PATH | null (встроенный) | | — | MCP_BSL_DOCS_GUIDELINE_PATH | null (встроенный) |

Использование

YAML-конфигурация (рекомендуется)

mcp-bsl-context -c config.yml                                  # Полная конфигурация из YAML
mcp-bsl-context -c config.yml -p /opt/1cv8/x86_64              # YAML + CLI override

CLI-параметры

mcp-bsl-context -p /opt/1cv8/x86_64                            # Автоопределение последней версии
mcp-bsl-context -p /opt/1cv8/x86_64 --platform-version 8.3.20  # Ближайшая к 8.3.20
mcp-bsl-context -p /path -m streamable-http --port 8080         # Streamable HTTP транспорт
mcp-bsl-context -p /path --data-source json --json-path /path   # JSON источник

Интеграция

Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "bsl-context": {
      "command": "python",
      "args": ["-m", "mcp_bsl_context", "-p", "/opt/1cv8/x86_64/8.3.25.1257"]
    }
  }
}

Cursor IDE

Добавьте в .cursor/mcp.json:

{
  "mcpServers": {
    "bsl-context": {
      "command": "python",
      "args": ["-m", "mcp_bsl_context", "-p", "C:\\Program Files\\1cv8\\8.3.25.1257"]
    }
  }
}

Мультиверсионный режим

Укажите путь к родительскому каталогу, и сервер автоматически найдёт все установленные версии:

# Linux: /opt/1cv8/x86_64 содержит 8.3.22.2838/, 8.3.25.1257/, ...
mcp-bsl-context -p /opt/1cv8/x86_64

# Выбрать конкретную версию (будет найдена ближайшая доступная)
mcp-bsl-context -p /opt/1cv8/x86_64 --platform-version 8.3.20

Streamable HTTP (рекомендуется для сетевого доступа)

Streamable HTTP — актуальный HTTP-транспорт в спецификации MCP, заменяющий устаревший SSE. Основные отличия:

  • Единый эндпоинт /mcp вместо двух (/sse + /messages) — проще настройка и проксирование
  • Stateless-режим — каждый запрос самодостаточен, не требуется держать долгоживущее SSE-соединение
  • Лучше для production — корректно работает за reverse proxy, load balancer, в Kubernetes
mcp-bsl-context -p /opt/1cv8/x86_64/8.3.25.1257 -m streamable-http --port 8080

Подключение клиента:

{
  "mcpServers": {
    "bsl-context": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Примечание: SSE-режим (-m sse) по-прежнему поддерживается для обратной совместимости.

Docker

Docker Compose

В docker-compose.yml нужно указать путь к каталогу установки платформы 1С, в котором находится файл shcntx_ru.hbk.

volumes:
  # Linux:
  - /opt/1cv8/x86_64/8.3.25.1257:/data/platform:ro
  # Windows (Docker Desktop):
  # - "C:/Program Files/1cv8/8.3.25.1257:/data/platform:ro"

docker compose up -d                   # CPU + API providers
docker compose --profile gpu up -d     # GPU + локальные модели
docker compose --profile json up -d    # JSON data source

Ручная сборка

docker build -t mcp-bsl-context .

# HBK-данные
docker run -d \
  -v /opt/1cv8/x86_64/8.3.25.1257:/data/platform:ro \
  -p 8080:8080 \
  mcp-bsl-context

# JSON-данные
docker run -d \
  -e MCP_BSL_DATA_SOURCE=json \
  -v ./json-data:/data/json:ro \
  -p 8080:8080 \
  mcp-bsl-context

Проверка здоровья

docker inspect --format='{{.State.Health.Status}}' mcp-bsl-context

Архитектура

mcp_bsl_context/
├── config.py                  # AppConfig — YAML + env + CLI merge
├── domain/                    # Доменный слой (все dataclasses frozen)
│   ├── entities.py            # Definition, MethodDefinition, PropertyDefinition, PlatformTypeDefinition
│   ├── enums.py               # ApiType (METHOD, PROPERTY, TYPE, CONSTRUCTOR)
│   ├── exceptions.py          # Иерархия исключений
│   ├── value_objects.py       # SearchQuery, SearchOptions, PlatformVersion
│   ├── services.py            # ContextSearchService
│   └── docs_service.py        # DocsInfoService (строгая типизация, guideline)
│
├── infrastructure/
│   ├── hbk/                   # Парсер бинарного формата HBK
│   │   ├── container_reader.py     # Бинарный контейнер
│   │   ├── content_reader.py       # ZIP-распаковка, TOC + FileStorage
│   │   ├── context_reader.py       # Оркестратор чтения
│   │   ├── pages_visitor.py        # Visitor: обход дерева страниц
│   │   ├── toc/                    # TOC: токенизатор, парсер, дерево
│   │   └── pa

Desko77

View profile

View on GitHub
GitHub Stars9
CategoryDevelopment
Updated1d ago
Forks1
Desko77/mcp-bsl-platform-help-context

Languages

Python

Security Score

90/100

Audited on Mar 23, 2026

No findings