MCP сервер для AI-ассистентов (справка по синтаксису и объектной модели 1С:Предприятие)

MCP (Model Context Protocol) сервер — это инструмент для интеграции с AI-ассистентами (например, Claude Desktop, Cursor IDE), предоставляющий быстрый и стандартизированный доступ к справочной информации по встроенным функциям, типам данных, методам и свойствам платформы 1С:Предприятие. MCP сервер позволяет AI-ассистентам работать с "Синтаксис-помощником" 1С в интерактивном режиме.

Обзор

Приложение mcp-bsl-context предназначено исключительно для интеграции с AI-ассистентами, чтобы они могли выполнять поиск по справке платформы 1С:Предприятие и получать детальную информацию о встроенных функциях, типах, методах и свойствах (аналогично работе с "Синтаксис-помощником" или официальной документацией 1С).

🤖 Возможности MCP сервера

• Поиск по справке платформы 1С — нечеткий поиск по встроенным функциям, методам, свойствам и типам данных
• Детальная справка — получение подробной информации о функциях, методах, свойствах и типах, включая сигнатуры и описания
• Навигация по объектной модели — просмотр методов и свойств конкретных типов данных
• Информация о конструкторах — способы создания объектов платформы 1С
• Интеграция с AI — стандартизированный протокол MCP для взаимодействия с AI-ассистентами
• Два режима работы — STDIO для локальной разработки и SSE для сетевого доступа

Проект использует Spring Boot и Spring AI для создания MCP сервера на базе Kotlin.

Режимы работы

STDIO режим (по умолчанию)

• Назначение — локальная интеграция с MCP клиентами
• Транспорт — стандартный ввод/вывод (stdin/stdout)
• Применение — Claude Desktop, Cursor IDE, VS Code
• Преимущества — простота настройки, низкие накладные расходы

SSE режим (Server-Sent Events)

• Назначение — сетевая интеграция и веб-интерфейс
• Транспорт — HTTP с Server-Sent Events
• Применение — веб-клиенты, удаленные подключения, REST API
• Преимущества — сетевой доступ, встроенный веб-интерфейс, real-time коммуникация

Требования

Системные требования

• Java: версия 17 или выше
• Операционная система: Linux, macOS, Windows
• Память: минимум 512 МБ RAM для работы приложения
• Место на диске: 100 МБ для установки приложения

Для MCP сервера

• Платформа 1С Предприятие: версия 8.3.20 или выше (рекомендуется)
• MCP клиент: Claude Desktop, Cursor IDE или другой совместимый MCP клиент
• Сетевое подключение: для загрузки зависимостей при первом запуске

Зависимости времени выполнения

Все необходимые зависимости включены в исполняемый JAR-файл:

• Spring Boot 3.5.0
• Spring AI 1.0.0
• Jackson 2.15.2
• Kotlin Coroutines

Сборка

Проект собирается с помощью Gradle. Для сборки выполните следующую команду в корневой директории проекта:

./gradlew build

После успешной сборки исполняемый JAR-файл будет находиться в директории build/libs/.

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

Запуск MCP сервера

Linux

java -jar mcp-bsl-context-<версия>.jar [опции]

Windows

java -Dfile.encoding=UTF-8 -jar mcp-bsl-context-<версия>.jar [опции]

Опции:

• --platform-path, -p - путь к каталогу установки 1С Предприятия
• --help, -h - показать справку по использованию
• --verbose - включить отладочное логирование
• --mode, -m - режим работы: sse (HTTP Server-Sent Events) или stdio (стандартный ввод/вывод) (по умолчанию stdio)
• --port - порт для SSE сервера (по умолчанию 8080)

Примеры:

# STDIO режим (по умолчанию)
java -jar mcp-bsl-context-0.3.0.jar --platform-path "/opt/1cv8/x86_64/8.3.25.1257"

# SSE режим (HTTP Server-Sent Events)
java -jar mcp-bsl-context-0.3.0.jar --mode sse --platform-path "/opt/1cv8/x86_64/8.3.25.1257"

# SSE режим с кастомным портом
java -jar mcp-bsl-context-0.3.0.jar --mode sse --port 9000 --platform-path "/opt/1cv8/x86_64/8.3.25.1257"

# Сокращенная форма
java -jar mcp-bsl-context-0.3.0.jar -m stdio -p "/opt/1cv8/x86_64/8.3.25.1257"

# Показать справку
java -jar mcp-bsl-context-0.3.0.jar --help

Примеры запуска в Windows:

# STDIO режим (по умолчанию)
java -Dfile.encoding=UTF-8 -jar mcp-bsl-context-0.3.0.jar --platform-path "C:\Program Files\1cv8\8.3.27.1606"

Возможности MCP сервера

Инструменты (Tools) доступные через MCP:

• search - поиск по API платформы 1С Предприятие
• info - получение детальной информации об элементе API
• getMember - получение информации о методе или свойстве конкретного типа
• getMembers - получение полного списка всех методов и свойств для указанного типа
• getConstructors - получение списка конструкторов для указанного типа

Подробная документация по использованию MCP сервера доступна в MCP_SERVER_USAGE.md.

Интеграция с AI клиентами

STDIO режим (по умолчанию)

Для локального использования с AI клиентами через stdin/stdout.

Claude Desktop - добавьте конфигурацию в claude_desktop_config.json:

{
  "mcpServers": {
    "1c-platform": {
      "command": "java",
      "args": [
        "-jar", 
        "/path/to/mcp-bsl-context.jar", 
        "--platform-path", 
        "/opt/1cv8/x86_64/8.3.25.1257"
      ]
    }
  }
}

Пример настройки для работы в Windows

  "mcpServers": {
    "1c-platform": {
      "type": "stdio",
      "command": "java",
      "args": [
        "-Dfile.encoding=UTF-8",
        "-jar",
        "C:\\your_path\\mcp-bsl-context-0.3.0.jar",
        "--platform-path",
        "C:\\Program Files\\1cv8\\8.3.27.1606"
      ],
      "env": {
        "LOG_FILE": "C:\\cmd\\mcp-server.log"
      }
    }
}

Cursor IDE - создайте файл .cursor/mcp.json в корне проекта:

{
  "mcpServers": {
    "1c-platform": {
      "command": "java",
      "args": [
        "-jar", 
        "/path/to/mcp-bsl-context.jar", 
        "--platform-path", 
        "/opt/1cv8/x86_64/8.3.25.1257"
      ]
    }
  }
}

Пример настройки для работы в Windows

  "mcpServers": {
    "1c-platform": {
      "type": "stdio",
      "command": "java",
      "args": [
        "-Dfile.encoding=UTF-8",
        "-jar",
        "C:\\your_path\\mcp-bsl-context-0.3.0.jar",
        "--platform-path",
        "C:\\Program Files\\1cv8\\8.3.27.1606"
      ],
      "env": {
        "LOG_FILE": "C:\\cmd\\mcp-server.log"
      }
    }
}

SSE режим (HTTP Server-Sent Events)

Для сетевого доступа и веб-интерфейса.

Запуск сервера:

java -jar mcp-bsl-context.jar --mode sse --platform-path "/opt/1cv8/x86_64/8.3.25.1257"

Доступные эндпоинты:

• http://localhost:8080/sse - SSE соединение

Подключение через URL:

{
  "mcpServers": {
    "1c-platform-sse": {
      "url": "http://localhost:8080/mcp/sse"
    }
  }
}

Пример HTTP запроса:

curl -X POST http://localhost:8080/mcp/request \
  -H "Content-Type: application/json" \
  -d '{
    "id": "req-1",
    "method": "search",
    "params": {
      "query": "СтрНайти",
      "type": "method",
      "limit": 5
    }
  }'

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

• Обзор - общий обзор и быстрый старт
• Возможности - описание доступных инструментов и функций
• Установка и запуск - инструкции по установке и настройке
• Docker - работа с Docker контейнерами
• Техническая документация - архитектура и технические детали
• Интеграция - интеграция с IDE и AI клиентами
• SSE режим - подробная документация по SSE режиму
• Использование MCP сервера - базовое использование

Алгоритм поиска

Поиск выполняется по принципу нечеткого соответствия с ранжированием:

1. Точное совпадение (100 баллов) - имя полностью совпадает с запросом
2. Префиксное совпадение (80 баллов) - имя начинается с запроса
3. Частичное совпадение (60 баллов) - имя содержит запрос
4. Совпадение в сигнатуре (40 баллов) - запрос найден в сигнатуре
5. Совпадение в описании (20 баллов) - запрос найден в описании
6. Fuzzy matching (0-50 баллов) - на основе расстояния Левенштейна

Зависимости

Основные зависимости проекта:

• Spring Boot 3.5.0
• Spring AI MCP Server
• Kotlin с Coroutines
• Jackson (для работы с JSON)
• Logback для логирования

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

Алгоритм чтения справки базируется на идеях bsl-context (от 1c-syntax).

Лицензия

Этот проект распространяется под лицензией MIT. Подробную информацию смотрите в файле LICENSE.