├── .env.example ├── docker-compose.example.yml ├── MCP_SERVER_CAPABILITIES.md └── README.md /.env.example: -------------------------------------------------------------------------------- 1 | # .env.example — пример файла окружения для настройки 2 | # Копируйте как .env и правьте значения под свою среду. 3 | # 4 | # Примечания по типам значений: 5 | # - Логические: true/false, 1/0, yes/no, on/off (регистр не важен) 6 | # - Списки/словари: указывать в формате JSON, например ["A","B"] или {"key":["v1","v2"]} 7 | # - Пути: для контейнера путь по умолчанию /app/data (смонтированный volume) 8 | 9 | ############################ 10 | # OpenAI / LLM настройки 11 | ############################ 12 | # Обязательно нужно указывать если TEMPLATE_MODE_ONLY=false 13 | 14 | # Ключ доступа (обязательно для LLM-режима) 15 | OPENAI_API_KEY= 16 | 17 | # Базовый URL API. По умолчанию используется OpenRouter (совместимый с OpenAI API) 18 | # Для использования локальный моделей на том же компьютере укажите http://host.docker.internal:1234/v1 19 | OPENAI_API_BASE=https://openrouter.ai/api/v1 20 | 21 | # Модель LLM 22 | # Пример: google/gemini-2.5-flash, gpt-4o-mini, или совместимая у кастом-провайдера 23 | OPENAI_MODEL=google/gemini-2.5-flash 24 | 25 | ############################ 26 | # Embedding API настройки (для векторного поиска) 27 | ############################ 28 | # Базовый URL API для эмбеддингов 29 | EMBEDDING_API_BASE=http://host.docker.internal:1234/v1 30 | 31 | # Ключ доступа к API эмбеддингов 32 | EMBEDDING_API_KEY=lm-api-key # Для LM Studio можно указать любое значение 33 | 34 | # Модель эмбеддингов (например, qwen3-embedding-4b, jina-embeddings-v3, user-bge-m3) 35 | EMBEDDING_MODEL=text-embedding-qwen3-embedding-0.6b 36 | 37 | # Включить векторную индексацию для описаний процедур/функций 38 | ENABLE_ROUTINE_DESCRIPTION_EMBEDDING=false 39 | 40 | # Включить векторную индексацию для описаний метаданных 41 | ENABLE_METADATA_DESCRIPTION_EMBEDDING=false 42 | 43 | ############################ 44 | # Настройки Neo4j 45 | ############################ 46 | 47 | # Пароль БД (обязательно) 48 | NEO4J_PASSWORD= 49 | 50 | ############################ 51 | # MCP сервер 52 | ############################ 53 | 54 | # Транспорт MCP: если true — SSE, иначе streamable-http 55 | MCP_USE_SSE=false 56 | 57 | ############################ 58 | # Загрузка данных 59 | ############################ 60 | # Управление загрузкой предопределенных значений (Predefined.xml): 61 | # - true — парсить и загружать предопределенные значения (по умолчанию) 62 | # - false — пропустить этап Predefined.xml 63 | LOAD_PREDEFINED_VALUES=true 64 | 65 | # Управление загрузкой форм из Ext/Form.xml: 66 | # - true — парсить и загружать определения форм (по умолчанию) 67 | # - false — пропустить этап Form.xml (ускоряет загрузку, уменьшает объем графа) 68 | LOAD_FORMS_FROM_XML=true 69 | 70 | # Управление загрузкой прав ролей из Roles/*/Ext/Rights.xml: 71 | # - true — загружать права ролей (по умолчанию) 72 | # - false — пропустить импорт прав 73 | LOAD_ROLE_RIGHTS=true 74 | 75 | # Сканирование и импорт сигнатур BSL из файлов .bsl (модули, процедуры/функции, вызовы) 76 | # - true — включить парсинг и загрузку BSL (по умолчанию) 77 | # - false — пропустить этап BSL 78 | LOAD_BSL_SIGNATURES=true 79 | 80 | # Загрузка подписок на события из каталога EventSubscriptions/*.xml 81 | # - true — включить парсинг и загрузку подписок (по умолчанию) 82 | # - false — пропустить этап подписок 83 | LOAD_EVENT_SUBSCRIPTIONS=true 84 | 85 | # Управление загрузкой справок Help/ru.html для объектов метаданных: 86 | # - true — парсить и загружать справку (по умолчанию) 87 | # - false — пропустить этап справки 88 | LOAD_HELP_FROM_HTML=true 89 | 90 | ############################ 91 | # Режим шаблонов (без LLM) 92 | ############################ 93 | # Включить поддержку Template JSON вместе с естественным языком 94 | TEMPLATE_MODE_ENABLED=true 95 | 96 | # Включить только Template JSON (полностью отключить использование LLM) 97 | TEMPLATE_MODE_ONLY=true 98 | 99 | -------------------------------------------------------------------------------- /docker-compose.example.yml: -------------------------------------------------------------------------------- 1 | 2 | name: ROCTUP-MCP 3 | services: 4 | ########################################### 5 | ## NEO4J Database 6 | ########################################### 7 | 1c-neo4j: 8 | image: neo4j:latest 9 | restart: unless-stopped 10 | ports: 11 | - "7474:7474" # Neo4j Browser (optional) 12 | - "7687:7687" # Bolt 13 | volumes: 14 | - 1c_neo4j_data:/data 15 | environment: 16 | - NEO4J_AUTH=neo4j/${NEO4J_PASSWORD} 17 | - NEO4J_client_allow__telemetry=false 18 | - NEO4J_dbms_memory_transaction_total_max=4096m 19 | - NEO4J_db_transaction_timeout=300s 20 | - NEO4J_server_memory_heap_max__size=4096m 21 | healthcheck: 22 | test: ["CMD-SHELL", "cypher-shell -a bolt://localhost:7687 -u neo4j -p \"${NEO4J_PASSWORD}\" 'RETURN 1' || exit 1"] 23 | interval: 10s 24 | timeout: 5s 25 | retries: 5 26 | 27 | ########################################### 28 | ## Project1 29 | ########################################### 30 | 1c-metacode-prj1: 31 | image: roctup/1c-mcp-metacode 32 | restart: unless-stopped 33 | ports: 34 | - "6001:6001" # MCP server (project 1) 35 | # Host directories are mounted into the container's /app/data directory. 36 | # The application expects to find 'metadata' and an optional 'code' subdirectory. 37 | # 38 | # Example 1: Single project directory from host 39 | # ./data/prj1/metadata -> /app/data/metadata 40 | # ./data/prj1/code -> /app/data/code 41 | # 42 | # volumes: 43 | # - ./data/prj1:/app/data 44 | # 45 | # Example 2: Separate host directories for metadata and code 46 | # D:\metadata\prj1 -> /app/data/metadata 47 | # E:\sources\prj1 -> /app/data/code 48 | # 49 | # volumes: 50 | # - D:\metadata\prj1:/app/data/metadata 51 | # - E:\sources\prj1:/app/data/code 52 | volumes: 53 | - ./data/prj1:/app/data # use relative path binding or full path binding - E:\1C\MCP\Accounting\data:/app/data 54 | environment: 55 | # Project identity (unique per app) 56 | - PROJECT_NAME=Accounting 57 | # Shared Neo4j DB 58 | - NEO4J_PASSWORD=${NEO4J_PASSWORD} 59 | - NEO4J_URI=bolt://1c-neo4j:7687 60 | # OpenAI / LLM 61 | - OPENAI_API_BASE=${OPENAI_API_BASE} 62 | - OPENAI_API_KEY=${OPENAI_API_KEY} 63 | - OPENAI_MODEL=${OPENAI_MODEL} 64 | # Embedding API 65 | - EMBEDDING_API_BASE=${EMBEDDING_API_BASE} 66 | - EMBEDDING_API_KEY=${EMBEDDING_API_KEY} 67 | - EMBEDDING_MODEL=${EMBEDDING_MODEL} 68 | - ENABLE_ROUTINE_DESCRIPTION_EMBEDDING=${ENABLE_ROUTINE_DESCRIPTION_EMBEDDING:-false} 69 | - ENABLE_METADATA_DESCRIPTION_EMBEDDING=${ENABLE_METADATA_DESCRIPTION_EMBEDDING:-false} 70 | # MCP server 71 | - MCP_USE_SSE=${MCP_USE_SSE} 72 | # Load toggles (per app). Note: FULL_METADATA_RELOAD=true clears ONLY the current PROJECT_NAME data (project-scoped), not the entire DB. 73 | - FULL_METADATA_RELOAD=false 74 | - LOAD_PREDEFINED_VALUES=${LOAD_PREDEFINED_VALUES:-true} 75 | - LOAD_FORMS_FROM_XML=${LOAD_FORMS_FROM_XML:-true} 76 | - LOAD_ROLE_RIGHTS=${LOAD_ROLE_RIGHTS:-true} 77 | - LOAD_BSL_SIGNATURES=${LOAD_BSL_SIGNATURES:-true} 78 | - LOAD_EVENT_SUBSCRIPTIONS=${LOAD_EVENT_SUBSCRIPTIONS:-true} 79 | - LOAD_HELP_FROM_HTML=${LOAD_HELP_FROM_HTML:-true} 80 | # Template/LLM mode 81 | - TEMPLATE_MODE_ENABLED=${TEMPLATE_MODE_ENABLED:-true} 82 | - TEMPLATE_MODE_ONLY=${TEMPLATE_MODE_ONLY:-true} 83 | depends_on: 84 | 1c-neo4j: 85 | condition: service_healthy 86 | 87 | ########################################### 88 | ## Project2 89 | ########################################### 90 | 1c-metacode-prj2: 91 | image: roctup/1c-mcp-metacode 92 | restart: unless-stopped 93 | ports: 94 | - "6011:6001" # MCP server (project 2) -> host:6011 95 | # Host directories are mounted into the container's /app/data directory. 96 | # The application expects to find 'metadata' and an optional 'code' subdirectory. 97 | # 98 | # Example 1: Single project directory from host 99 | # ./data/prj2/metadata -> /app/data/metadata 100 | # ./data/prj2/code -> /app/data/code 101 | # 102 | # volumes: 103 | # - ./data/prj2:/app/data 104 | # 105 | # Example 2: Separate host directories for metadata and code 106 | # D:\metadata\prj2 -> /app/data/metadata 107 | # E:\sources\prj2 -> /app/data/code 108 | # 109 | # volumes: 110 | # - D:\metadata\prj2:/app/data/metadata 111 | # - E:\sources\prj2:/app/data/code 112 | volumes: 113 | - ./data/prj2:/app/data # use relative path binding or full path binding full path binding - E:\1C\MCP\HRM\data:/app/data 114 | environment: 115 | # Project identity (unique per app) 116 | - PROJECT_NAME=HRM 117 | # Shared Neo4j DB 118 | - NEO4J_PASSWORD=${NEO4J_PASSWORD} 119 | - NEO4J_URI=bolt://1c-neo4j:7687 120 | # OpenAI / LLM 121 | - OPENAI_API_BASE=${OPENAI_API_BASE} 122 | - OPENAI_API_KEY=${OPENAI_API_KEY} 123 | - OPENAI_MODEL=${OPENAI_MODEL} 124 | # Embedding API 125 | - EMBEDDING_API_BASE=${EMBEDDING_API_BASE} 126 | - EMBEDDING_API_KEY=${EMBEDDING_API_KEY} 127 | - EMBEDDING_MODEL=${EMBEDDING_MODEL} 128 | - ENABLE_ROUTINE_DESCRIPTION_EMBEDDING=${ENABLE_ROUTINE_DESCRIPTION_EMBEDDING:-false} 129 | - ENABLE_METADATA_DESCRIPTION_EMBEDDING=${ENABLE_METADATA_DESCRIPTION_EMBEDDING:-false} 130 | # MCP server 131 | - MCP_USE_SSE=${MCP_USE_SSE} 132 | # Load toggles (per app). Note: FULL_METADATA_RELOAD=true clears ONLY the current PROJECT_NAME data (project-scoped), not the entire DB. 133 | - FULL_METADATA_RELOAD=false 134 | - LOAD_PREDEFINED_VALUES=${LOAD_PREDEFINED_VALUES:-true} 135 | - LOAD_FORMS_FROM_XML=${LOAD_FORMS_FROM_XML:-true} 136 | - LOAD_ROLE_RIGHTS=${LOAD_ROLE_RIGHTS:-true} 137 | - LOAD_BSL_SIGNATURES=${LOAD_BSL_SIGNATURES:-true} 138 | - LOAD_EVENT_SUBSCRIPTIONS=${LOAD_EVENT_SUBSCRIPTIONS:-true} 139 | - LOAD_HELP_FROM_HTML=${LOAD_HELP_FROM_HTML:-true} 140 | # Template/LLM mode 141 | - TEMPLATE_MODE_ENABLED=${TEMPLATE_MODE_ENABLED:-true} 142 | - TEMPLATE_MODE_ONLY=${TEMPLATE_MODE_ONLY:-true} 143 | depends_on: 144 | 1c-neo4j: 145 | condition: service_healthy 146 | 147 | volumes: 148 | 1c_neo4j_data: 149 | driver: local 150 | -------------------------------------------------------------------------------- /MCP_SERVER_CAPABILITIES.md: -------------------------------------------------------------------------------- 1 | # Возможности MCP сервера для работы с метаданными 1С 2 | 3 | ## Обзор 4 | 5 | MCP сервер предоставляет три специализированных инструмента для работы с метаданными и кодом конфигураций 1С:Предприятие. 6 | 7 | 8 | 9 | ## Режимы работы MCP-сервера 10 | 11 | MCP-сервер может работать в трех режимах, которые управляются через переменные окружения. Это позволяет гибко настраивать его поведение: использовать точные и быстрые шаблонные запросы, мощные возможности LLM для обработки запросов на естественном языке или комбинировать оба подхода. 12 | 13 | ### 1. Template Mode Only (Только шаблоны) 14 | 15 | Это режим **по умолчанию**, который **не требует LLM**. Он предназначен для выполнения точных, заранее определенных операций с графом метаданных через JSON-шаблоны. 16 | 17 | - **Необходимо указать переменные**: 18 | - `TEMPLATE_MODE_ENABLED=true` 19 | - `TEMPLATE_MODE_ONLY=true` 20 | 21 | ### 2. LLM Mode Only (Только LLM) 22 | 23 | В этом режиме сервер использует OpenAI-совместимую модель для преобразования запросов на естественном языке в точные Cypher-запросы. Шаблонные запросы в этом режиме **отключены**. 24 | 25 | - **Необходимо указать переменные**: 26 | - `TEMPLATE_MODE_ENABLED=false` 27 | - `TEMPLATE_MODE_ONLY=false` 28 | - `OPENAI_API_KEY`: API ключ 29 | - `OPENAI_API_BASE`: Адрес API 30 | - `OPENAI_MODEL`: Имя модели 31 | 32 | ### 3. Combined Mode (Комбинированный режим) 33 | 34 | Это гибридный режим, в котором **одновременно доступны и шаблонные запросы, и LLM-обработка**. Агент, который обращается к MCP серверу, сам выбирает какой запрос отправлять, шаблонный или на естественном языке. 35 | 36 | - **Необходимо указать переменные**: 37 | - `TEMPLATE_MODE_ENABLED=true` 38 | - `TEMPLATE_MODE_ONLY=false` 39 | - `OPENAI_API_KEY`: API ключ 40 | - `OPENAI_API_BASE`: Адрес API 41 | - `OPENAI_MODEL`: Имя модели 42 | 43 | 44 | ## MCP инструменты и их возможности 45 | 46 | ### 1. `search_metadata` - Структурный поиск метаданных 47 | 48 | **Основное назначение:** Поиск объектов метаданных по их структурным свойствам, связям, техническим характеристикам и отношениям. 49 | 50 | **Что можно искать:** 51 | - Объекты метаданных по названию и категории. 52 | - Реквизиты, табличные части, ресурсы, измерения регистров, а также их типы данных и использование в других объектах. 53 | - Формы объектов (основные, списки, выбора) и их роли. 54 | - Команды объектов и форм, их связь с элементами управления формы. 55 | - Макеты печатных форм и их использование. 56 | - Значения перечислений. 57 | - Предопределенные элементы. 58 | - HTTP-сервисы, Шаблоны URL и Методы HTTP-сервисов. 59 | - Журналы документов и их графы. 60 | - Связи между объектами: где конкретный объект используется как тип реквизита, ресурса, измерения, признака учета или признака учета субконто в других объектах метаданных. 61 | - Система прав доступа: какие роли имеют доступ к определенному объекту, к каким объектам имеет доступ конкретная роль, а также детальные права доступа роли с условиями. 62 | - Подписки на события конфигурации: список всех подписок, подписки для конкретного объекта метаданных (с указанием События и Обработчика), а также Источники подписки. 63 | - Обработчики событий форм и привязки элементов управления к командам: структурные связи (метаданные), указывающие, какие процедуры назначены обработчиками событий форм и элементов управления, а также к каким командам привязаны элементы управления формы. 64 | - Элементы управления форм (контролы) и их иерархия, а также привязки данных. 65 | - Поиск объектов метаданных по их уникальным идентификаторам (GUID/UUID/УИД) для таких элементов как основные объекты метаданных, их атрибуты, табличные части, ресурсы, измерения и формы. 66 | - Граф вызовов BSL кода: анализ вызовов процедур/функций в контексте объектов метаданных - "кто вызывает процедуру X модуля объекта Y" (callers) и "что вызывает процедура X" (callees) с поддержкой многоуровневой глубины анализа. Поиск неиспользуемых процедур, экспортируемых методов, вызовов между модулями разных объектов. 67 | 68 | **Особенности:** 69 | - Поддержка как естественного языка, так и шаблонных JSON-запросов. 70 | - Более 50 предопределенных операций для различных типов запросов в шаблонном режиме. 71 | - Детальный анализ системы прав доступа с учетом условий. 72 | 73 | **Шаблонные операции:** 74 | - Структура объектов: `list_attributes`, `list_tabular_parts`, `list_resources`, `list_dimensions`, `object_structure` 75 | - Связи и зависимости: `find_objects_using_object`, `find_usages_of_object`, `find_documents_making_movements_into_register` 76 | - Формы и интерфейс: `list_forms`, `get_default_forms`, `list_form_controls`, `list_form_events`, `list_form_commands`, `list_form_bindings`, `list_form_attributes`, `list_form_event_handlers` 77 | - Команды и макеты: `list_commands`, `list_layouts`, `find_objects_by_command`, `find_objects_by_layout` 78 | - Типы данных: `get_attribute_type`, `get_tabular_attribute_type`, `list_attributes_with_type`, `get_resource_type`, `get_dimension_type` 79 | - Перечисления и предопределенные: `list_enum_values`, `list_predefined_of_object`, `find_predefined_by_name_in_object`, `find_predefined_by_flag` 80 | - HTTP-сервисы: `list_http_services`, `list_url_templates_of_service`, `list_url_methods_of_template` 81 | - Права доступа: `list_roles_with_access_to_target`, `list_access_targets_of_role`, `get_access_of_role_to_target` 82 | - События: `list_event_subscriptions`, `list_event_subscriptions_of_object`, `get_event_subscription_sources` 83 | - Поиск и навигация: `list_objects_by_category`, `list_objects_by_name`, `resolve_qn`, `find_by_guid` 84 | - Граф вызовов BSL: `list_callees_of_routine`, `list_callers_of_routine`, `call_graph_subtree`, `find_calls_between_owners`, `find_unused_routines`, `list_exported_routines` 85 | - Модули и процедуры: `list_modules_of_owner`, `list_module_routines`, `list_common_module_routines`, `find_routines_by_name`, `find_routines_by_signature`, `list_routine_handled_events`, `list_event_subscription_handlers` 86 | 87 | **Примеры использования (естественный язык):** 88 | - "Какие реквизиты у документа Счёт?" 89 | - "Где используется справочник Контрагенты?" 90 | - "Формы справочника Организации" 91 | - "Обработчики событий формы документа Счёт" 92 | - "Какой доступ имеет роль Менеджер к справочнику Контрагенты (с текстом условия)?" 93 | - "Найди элемент по GUID '8f1c2d34-5678-4abc-9def-0123456789ab'" 94 | - "Кто вызывает процедуру ПередЗаписью модуля объекта документа Счёт?" 95 | - "Кого вызывает процедуру ПередЗаписью модуля справочника Контрагенты (глубина 2)?" 96 | - "Привязки команд в форме ФормаЭлемента справочника Контрагенты" 97 | - "Элементы управления формы документа ПриходныйКассовыйОрдер" 98 | - "Предопределенные элементы справочника ВидыДоходов, у которых ТипСчета = 'АктивноПассивный'" 99 | 100 | ### 2. `search_metadata_by_description` - Семантический поиск по описаниям 101 | 102 | **Основное назначение:** Поиск объектов метаданных по их семантическому содержанию, используя описания, комментарии, синонимы и внутренние имена. Инструмент использует полнотекстовый/векторный индекс для поиска по описательным полям. 103 | 104 | **Что можно искать:** 105 | - Объекты, соответствующие бизнес-логике или назначению. 106 | - Объекты, функциональные возможности которых включают определенные ключевые слова. 107 | - Объекты по их описаниям, комментариям или справке. 108 | - Объекты по семантически связанным терминам. 109 | 110 | **Особенности:** 111 | - Полнотекстовый поиск по полям: `Справка`, `Синоним`, `Комментарий`, `Описание`, `Наименование`. 112 | - Фильтрация по категориям объектов (например, только `Справочники` или `Документы`). 113 | - Специализирован для контентного и семантического поиска, отлично подходит для запросов типа "что хранит", "для чего используется", "про что". 114 | 115 | **Шаблонные операции:** 116 | - `search_metadata_by_description` - полнотекстовый поиск по описаниям объектов. 117 | 118 | **Примеры использования (естественный язык):** 119 | - "Найди справочники про банковские счета" 120 | - "Документы для поступления товаров" 121 | - "Объекты, где упоминается IBAN" 122 | - "Регистры сведений, содержащие информацию о контрагентах" 123 | - "Перечисления, связанные с видами доходов" 124 | 125 | ### 3. `search_code` - Поиск и получение BSL кода 126 | 127 | **Основное назначение:** Семантический поиск процедур и функций по их описаниям и получение исходного кода BSL. 128 | 129 | **Что можно искать:** 130 | - Процедуры и функции по их описаниям (комментарии, которые расположены перед процедурой/функцией). 131 | - Исходный код процедур и функций с полной документацией, директивами компиляции, путем к файлу и номером строки. 132 | - Методы из различных типов модулей (модули объектов, модули менеджеров, модули форм, общие модули, модули команд). 133 | - Процедуры и функции из БСП (Библиотека стандартных подсистем) с автоматическим определением по контексту. 134 | - Экспортные/неэкспортные методы, методы с определенными директивами (&НаСервере, &НаКлиенте и т.д.). 135 | 136 | **Особенности:** 137 | - Полнотекстовый/гибридный поиск по описанию из комментариев к процедуре/функции. 138 | - Получение исходного кода с контекстом: файл, строка, владелец (объект/форма/общий модуль). 139 | - Справка по БСП: упоминание "БСП", "SSL", "библиотека стандартных подсистем" автоматически фильтрует результаты только по процедурам и функциям из области ПрограммныйИнтерфейс БСП. 140 | - Фильтры: по типу процедуры/функции, по экспортности, по директиве, по владельцу (объект метаданных). 141 | 142 | **Шаблонные операции:** 143 | - `find_routines_by_description` - полнотекстовый/гибридный поиск процедур/функций по описанию 144 | - `get_routine_body` - получение исходного кода по ID, имени+владельцу или сигнатуре 145 | 146 | **Примеры использования (естественный язык):** 147 | - "Найди функции для работы с XML" 148 | - "Процедуры для печати счетов" 149 | - "Функции из БСП для работы с файлами" 150 | - "Покажи тело процедуры ПередЗаписью из документа Счёт" 151 | - "Исходный код функции ПолучитьЗначениеРеквизита из БСП" 152 | - "Процедуры на сервере для обработки email" 153 | - "Функции общего модуля СтроковыеФункцииКлиентСервер для работы с JSON" 154 | 155 | **Примечание:** Для анализа графа вызовов, поиска неиспользуемых процедур, анализа обработчиков событий используйте инструмент `search_metadata`, который предоставляет структурный анализ кода в контексте объектов метаданных. 156 | 157 | --- 158 | 159 | ## Разделение ответственности между инструментами 160 | 161 | ### Когда использовать `search_metadata`: 162 | - **Структурные запросы**: "Какие реквизиты у документа X?", "Где используется справочник Y?" 163 | - **Связи объектов**: "Какие документы делают движения в регистр Z?", "Что использует тип данных X?" 164 | - **Права доступа**: "Какие роли имеют доступ к объекту X?", "К чему имеет доступ роль Y?" 165 | - **Формы и интерфейс**: "Какие формы есть у объекта X?", "Элементы управления формы Y" 166 | - **Граф вызовов в контексте метаданных**: "Кто вызывает ПередЗаписью документа Счёт?", "Граф вызовов модуля справочника X" 167 | - **Обработчики событий**: "Обработчики формы X", "Процедуры-обработчики подписок на события" 168 | - **Поиск по GUID**: "Найди объект по GUID xyz" 169 | 170 | ### Когда использовать `search_metadata_by_description`: 171 | - **Семантический поиск объектов**: "Найди справочники про банковские счета" 172 | - **Поиск по назначению**: "Документы для учета зарплаты" 173 | - **Поиск по ключевым словам**: "Объекты, где упоминается IBAN" 174 | - **Общие концепции**: "Что хранит информацию о контрагентах?" 175 | 176 | ### Когда использовать `search_code`: 177 | - **Семантический поиск процедур/функций**: "Найди процедуры для работы с XML" 178 | - **Поиск кода по описанию**: "Функции для печати счетов" 179 | - **Получение исходного кода**: "Покажи тело процедуры ПередЗаписью из документа Счёт" 180 | - **Поиск в БСП**: "Функции из библиотеки стандартных подсистем для работы с файлами" 181 | - **Фильтрация по характеристикам**: "Экспортные функции на сервере для обработки email" 182 | 183 | ### Ключевые различия: 184 | 185 | | Аспект | search_metadata | search_code | 186 | |--------|----------------|-------------| 187 | | **Основной фокус** | Структура метаданных и связи | Содержание и исходный код BSL | 188 | | **Тип поиска** | Структурный + граф связей | Семантический (fulltext/hybrid по описаниям) | 189 | | **Возвращает** | Метаданные, связи, структуры | Описания процедур + исходный код | 190 | | **Граф вызовов** | ✅ Да (в контексте объектов) | ❌ Нет (используйте search_metadata) | 191 | | **Исходный код** | ❌ Нет (только ID процедур) | ✅ Да (полный код с контекстом) | 192 | | **Поиск по описанию процедур** | ❌ Нет | ✅ Да (fulltext/hybrid по doc_description) | 193 | | **Структура объектов** | ✅ Да (реквизиты, формы, команды) | ❌ Нет | 194 | 195 | ### Типичные сценарии комбинированного использования: 196 | 197 | 1. **Найти и просмотреть код процедуры:** 198 | - `search_metadata`: "Обработчики события ПередЗаписью документа Счёт" → получаем routine_id 199 | - `search_code`: "Покажи тело процедуры с ID xyz" → получаем исходный код 200 | 201 | 2. **Анализ использования объекта в коде:** 202 | - `search_metadata`: "Где используется справочник Контрагенты?" → структурные связи 203 | - `search_metadata`: "Граф вызовов процедур, работающих с Контрагентами" → анализ кода 204 | 205 | 3. **Поиск функциональности:** 206 | - `search_code`: "Функции для формирования XML" → список процедур с описаниями 207 | - `search_code`: "Покажи код функции X" → исходный код для анализа 208 | 209 | 210 | ## Режимы поиска по описаниям 211 | 212 | MCP-сервер поддерживает два основных режима поиска для описаний процедур/функций и метаданных: 213 | 214 | ### 1. Полнотекстовый поиск (Fulltext-only Search) 215 | 216 | Это режим **по умолчанию**, который используется, когда векторные представления (embeddings) для соответствующих сущностей отключены. В этом режиме поиск производится исключительно по текстовым данным с использованием полнотекстовых индексов. 217 | 218 | - **Когда активируется:** 219 | - Если `EMBEDDING_API_BASE` не настроен. 220 | - Если `ENABLE_ROUTINE_DESCRIPTION_EMBEDDING=false` для поиска по описаниям процедур/функций. 221 | - Если `ENABLE_METADATA_DESCRIPTION_EMBEDDING=false` для поиска по описаниям метаданных. 222 | 223 | ### 2. Гибридный поиск (Hybrid Search) 224 | 225 | Этот режим объединяет возможности полнотекстового и векторного поиска для достижения более релевантных результатов, учитывая как точные совпадения по ключевым словам, так и семантическую близость. Он активируется, когда включена генерация векторных представлений (embeddings) для соответствующих сущностей. 226 | 227 | - **Как работает:** 228 | - Производится два независимых поиска: один полнотекстовый (по ключевым словам) и один векторный (по смыслу). 229 | - Результаты из обоих поисков объединяются. При этом система временно запрашивает больше кандидатов, чем нужно, чтобы потом выбрать лучшие. 230 | - Оценки релевантности (scores) от полнотекстового и векторного поиска объединяются с помощью взвешенной суммы или специализированных алгоритмов, таких как Reciprocal Rank Fusion (RRF), чтобы сформировать единый "гибридный" рейтинг. Это позволяет учитывать вклад обеих компонент. 231 | - Лучшие результаты из объединенного и отсортированного списка возвращаются MCP сервером. 232 | 233 | - **Необходимо указать переменные:** 234 | - `EMBEDDING_API_BASE`: API адрес сервиса embeddings 235 | - `EMBEDDING_API_KEY`: API ключ сервиса embeddings 236 | - `EMBEDDING_MODEL`: Имя модели для embeddings 237 | - `ENABLE_ROUTINE_DESCRIPTION_EMBEDDING=true`: Включает векторную индексацию и гибридный поиск для описаний процедур/функций. 238 | - `ENABLE_METADATA_DESCRIPTION_EMBEDDING=true`: Включает векторную индексацию и гибридный поиск для описаний объектов метаданных. 239 | 240 | 241 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 1C Metacode MCP Server 2 | 3 | Загружает метаданные и код конфигураций 1С в графовую базу данных и предоставляет инструменты MCP для запросов по графу. 4 | 5 | #### Основные возможности 6 | 7 | - Загрузка всех метаданных конфигураций 1С в графовую базу Neo4j из отчета по конфигурации. 8 | - Загрузка данных управляемых форм - реквизиты, элементы формы, события, команды. Привязка событий форм и элементов, команд к обработчикам. 9 | - Загрузка предопределенных значений и прав ролей. 10 | - Загрузка подписок на события и привязка к обработчикам. 11 | - Загрузка сигнатур процедур/функций из всех модулей (включая модуль формы обычных форм), формирование графа вызовов. 12 | - Загрузка описания и тела всех процедур и функций (включая модуль формы обычных форм) с полнотекстовым или гибридным поиском по описанию. 13 | - Широкая связность объектов метаданных: в реквизитах, в элементах управлениях формы, в регистрах накопления/сведений, в правах доступа. 14 | - MCP инструменты: search_metadata, search_metadata_by_description, search_code 15 | - Поддержка загрузки и поиска информации по несколким конфигурациям (проектам). При поиске не нужно указывать в каком проекте искать. Система автоматически фильтрует. 16 | - Возможность осуществлять поиск как с помощью LLM (режим агента, который переводить запрос на естественом языке в cypher запрос), так и без LLM (поиск по шаблонам). Возможен так же гибридный режим. Большинство информации может быть найдено по шаблонам. 17 | 18 | 19 | #### Структура данных 20 | 21 | ```mermaid 22 | graph TB 23 | %% Компактная вертикальная структура 24 | Project(["Project
Проект"]) -->|"contains"| Configuration(["Configuration
Конфигурация"]) 25 | Configuration -->|"has"| MetadataCategory(["MetadataCategory
Категория метаданных"]) 26 | MetadataCategory -->|"contains"| MetadataObject(["MetadataObject
Объект метаданных"]) 27 | 28 | %% Формы и интерфейс (левая колонка) 29 | MetadataObject -->|"HAS_FORM"| Form(["Form
Форма"]) 30 | Form -->|"HAS_CONTROL"| FormControl(["FormControl
Элемент формы"]) 31 | Form -->|"HAS_EVENT"| FormEvent(["FormEvent
Событие формы"]) 32 | Form -->|"HAS_FORM_ATTRIBUTE"| FormAttribute(["FormAttribute
Атрибут формы"]) 33 | FormControl -->|"HAS_EVENT"| FormControlEvent(["FormEvent
Событие элемента"]) 34 | FormEvent -->|"HAS_HANDLER"| EventHandler(["Routine
Обработчик события"]) 35 | FormControlEvent -->|"HAS_HANDLER"| ControlEventHandler(["Routine
Обработчик события"]) 36 | 37 | %% Данные и атрибуты (правая колонка) 38 | MetadataObject -->|"HAS_ATTRIBUTE"| Attribute(["Attribute
Атрибут"]) 39 | MetadataObject -->|"HAS_TABULAR_PART"| TabularPart(["TabularPart
Табличная часть"]) 40 | MetadataObject -->|"HAS_RESOURCE"| Resource(["Resource
Ресурс"]) 41 | MetadataObject -->|"HAS_DIMENSION"| Dimension(["Dimension
Измерение"]) 42 | TabularPart -->|"HAS_ATTRIBUTE"| TabularAttribute(["Attribute
Атрибут табл. части"]) 43 | 44 | %% Связи и зависимости (нижняя секция) 45 | MetadataObject -->|"USED_IN"| UsedInTarget(["Target Object
Целевой объект"]) 46 | MetadataObject -->|"DO_MOVEMENTS_IN"| RegisterObject(["Register
Регистр"]) 47 | MetadataObject -->|"GRANTS_ACCESS_TO"| AccessTarget(["Access Target
Цель доступа"]) 48 | 49 | %% Модули и код (вертикальная цепочка) 50 | MetadataObject -->|"HAS_MODULE"| Module(["Module
Модуль"]) 51 | Module -->|"DECLARES"| Routine(["Routine
Процедура/Функция"]) 52 | Routine -->|"CALLS"| CalledRoutine(["Called Routine
Вызываемая процедура"]) 53 | 54 | %% Дополнительные компоненты (компактно) 55 | MetadataObject -->|"HAS_COMMAND"| Command(["Command
Команда"]) 56 | MetadataObject -->|"HAS_URL_TEMPLATE"| UrlTemplate(["UrlTemplate
Шаблон URL"]) 57 | MetadataObject -->|"HAS_EVENT_SUBSCRIPTION"| EventSubscription(["EventSubscription
Подписка на событие"]) 58 | MetadataObject -->|"HAS_PREDEFINED"| PredefinedItem(["PredefinedItem
Предопределенный элемент"]) 59 | 60 | %% Связи HTTP и форм (компактно) 61 | UrlTemplate -->|"HAS_URL_METHOD"| UrlMethod(["UrlMethod
Метод URL"]) 62 | UrlMethod -->|"HAS_HANDLER"| UrlHandler(["Routine
Обработчик HTTP"]) 63 | FormControl -->|"BINDS_TO"| BindTarget(["Bind Target
Цель связывания"]) 64 | FormControl -->|"LINKS_TO_COMMAND"| LinkedCommand(["Command
Команда"]) 65 | 66 | %% Новые добавления: дополнительные сущности и связи 67 | MetadataObject -->|"HAS_LAYOUT"| Layout(["Layout
Макет"]) 68 | MetadataObject -->|"HAS_CHARACTERISTIC"| Characteristic(["Characteristic
Характеристика"]) 69 | MetadataObject -->|"HAS_ENUM_VALUE"| EnumValue(["EnumValue
ЗначениеПеречисления"]) 70 | MetadataObject -->|"HAS_GRAPH"| JournalGraph(["JournalGraph
Граф журнала"]) 71 | MetadataObject -->|"HAS_ACCOUNTING_FLAG"| AccountingFlag(["AccountingFlag
ПризнакУчета"]) 72 | MetadataObject -->|"HAS_DIMENSION_ACCOUNTING_FLAG"| DimensionAccountingFlag(["DimensionAccountingFlag
ПризнакУчетаСубконто"]) 73 | MetadataObject -->|"CONTAINS_OBJECT"| SubsystemChild(["MetadataObject
Дочерний объект
(подсистемы)"]) 74 | PredefinedItem -->|"HAS_CHILD"| PredefinedChild(["PredefinedItem
Дочерний элемент"]) 75 | FormControl -->|"HAS_CHILD"| FormControlChild(["FormControl
Дочерний элемент"]) 76 | Form -->|"HAS_COMMAND"| FormCommand(["Command
Команда формы"]) 77 | EventSubscription -->|"HAS_HANDLER"| EventSubHandler(["Routine
Обработчик подписки"]) 78 | Command -->|"HAS_HANDLER"| CommandHandler(["Routine
Обработчик команды"]) 79 | FormCommand -->|"HAS_HANDLER"| FormCommandHandler(["Routine
Обработчик команды формы"]) 80 | 81 | %% Уникальные стили для каждого типа узла (упрощено, без лишних подтипов) 82 | classDef projectClass fill:#FF6B6B,stroke:#C92A2A,stroke-width:2px,color:#FFFFFF 83 | classDef configClass fill:#4ECDC4,stroke:#26A69A,stroke-width:2px,color:#FFFFFF 84 | classDef categoryClass fill:#45B7D1,stroke:#1976D2,stroke-width:2px,color:#FFFFFF 85 | classDef objectClass fill:#96CEB4,stroke:#388E3C,stroke-width:2px,color:#FFFFFF 86 | classDef formClass fill:#FFEAA7,stroke:#FD8D3C,stroke-width:2px,color:#000000 87 | classDef formControlClass fill:#AED6F1,stroke:#3498DB,stroke-width:2px,color:#FFFFFF 88 | classDef formEventClass fill:#FF69B4,stroke:#C2185B,stroke-width:2px,color:#FFFFFF 89 | classDef formAttrClass fill:#A3E4D7,stroke:#1ABC9C,stroke-width:2px,color:#000000 90 | classDef attributeClass fill:#85C1E9,stroke:#2980B9,stroke-width:2px,color:#FFFFFF 91 | classDef tabularClass fill:#F7DC6F,stroke:#F39C12,stroke-width:2px,color:#000000 92 | classDef resourceClass fill:#F8C471,stroke:#E67E22,stroke-width:2px,color:#000000 93 | classDef dimensionClass fill:#82E0AA,stroke:#27AE60,stroke-width:2px,color:#FFFFFF 94 | classDef targetClass fill:#CACFD2,stroke:#7F8C8D,stroke-width:2px,color:#000000 95 | classDef moduleClass fill:#98D8C8,stroke:#16A085,stroke-width:2px,color:#FFFFFF 96 | classDef routineClass fill:#F1948A,stroke:#E74C3C,stroke-width:2px,color:#FFFFFF 97 | classDef commandClass fill:#E1BEE7,stroke:#9C27B0,stroke-width:2px,color:#FFFFFF 98 | classDef urlTemplateClass fill:#F9E79F,stroke:#F1C40F,stroke-width:2px,color:#000000 99 | classDef urlMethodClass fill:#D98880,stroke:#CD6155,stroke-width:2px,color:#FFFFFF 100 | classDef eventSubClass fill:#AEB6BF,stroke:#5D6D7E,stroke-width:2px,color:#FFFFFF 101 | classDef predefinedClass fill:#BB8FCE,stroke:#8E44AD,stroke-width:2px,color:#FFFFFF 102 | classDef bindTargetClass fill:#D5DBDB,stroke:#BDC3C7,stroke-width:2px,color:#000000 103 | classDef layoutClass fill:#F0E68C,stroke:#DAA520,stroke-width:2px,color:#000000 104 | classDef characteristicClass fill:#DEB887,stroke:#CD853F,stroke-width:2px,color:#000000 105 | classDef enumValueClass fill:#FFA07A,stroke:#FF6347,stroke-width:2px,color:#FFFFFF 106 | classDef journalGraphClass fill:#20B2AA,stroke:#008B8B,stroke-width:2px,color:#FFFFFF 107 | classDef accountingFlagClass fill:#87CEEB,stroke:#4682B4,stroke-width:2px,color:#FFFFFF 108 | classDef dimensionAccountingFlagClass fill:#DDA0DD,stroke:#BA55D3,stroke-width:2px,color:#FFFFFF 109 | classDef subsystemChildClass fill:#A8E6CF,stroke:#3D9970,stroke-width:2px,color:#FFFFFF 110 | classDef formControlChildClass fill:#B3E5FC,stroke:#03A9F4,stroke-width:2px,color:#FFFFFF 111 | classDef tabularAttributeClass fill:#90CAF9,stroke:#2196F3,stroke-width:2px,color:#FFFFFF 112 | 113 | %% Применение цветов (упрощено) 114 | class Project projectClass 115 | class Configuration configClass 116 | class MetadataCategory categoryClass 117 | class MetadataObject,SubsystemChild subsystemChildClass 118 | class Form formClass 119 | class FormControl,FormControlChild formControlChildClass 120 | class FormEvent formEventClass 121 | class FormAttribute formAttrClass 122 | class Attribute,TabularAttribute tabularAttributeClass 123 | class TabularPart tabularClass 124 | class Resource resourceClass 125 | class Dimension dimensionClass 126 | class UsedInTarget,RegisterObject,AccessTarget targetClass 127 | class Module moduleClass 128 | class Routine,CalledRoutine,EventHandler,ControlEventHandler,UrlHandler,EventSubHandler,CommandHandler,FormCommandHandler routineClass 129 | class Command,FormCommand,LinkedCommand commandClass 130 | class UrlTemplate urlTemplateClass 131 | class UrlMethod urlMethodClass 132 | class EventSubscription eventSubClass 133 | class PredefinedItem,PredefinedChild predefinedClass 134 | class BindTarget bindTargetClass 135 | class Layout layoutClass 136 | class Characteristic characteristicClass 137 | class EnumValue enumValueClass 138 | class JournalGraph journalGraphClass 139 | class AccountingFlag accountingFlagClass 140 | class DimensionAccountingFlag dimensionAccountingFlagClass 141 | 142 | ``` 143 | 144 | 145 | #### Быстрый старт 146 | 147 | - Docker и Docker Compose 148 | - Свободные порты 7474/7687 (Neo4j) и 6001 (MCP) 149 | 150 | 1. Подготовьте .env 151 | 152 | Скопируйте пример и заполните значения (минимум пароль Neo4j): 153 | 154 | Обязательно задайте пароль Neo4j 155 | NEO4J_PASSWORD=... 156 | 157 | В файле .env указываются значение, которые общие для всех контейнеров. 158 | Значения, которые различаются для каждого контейнера лучше указывать непосредственно в docker-compose.yml 159 | 160 | 161 | 2. Подготовьте docker-compose.yml 162 | 163 | Скопируйте пример docker-compose.example.yml в туже папку где у вас файл .env и переименуйте в docker-compose.yml 164 | 165 | Задайте PROJECT_NAME в сервисе 1c-metacode-prj1 (можно переименовать название сервиса как нравится) 166 | Если у вас только один проект, то второй сервис 1c-metacode-prj2 можно удалить полностью 167 | Если нужно больше двух то продублируйте секцию сервиса и обязательно задайте другой порт на хосте ( меняем только первый порт в этой строке "6001:6001") и другой PROJECT_NAME 168 | 169 | 170 | 3. Разместите данные 171 | 172 | В корне папки где располагаются файлы .env и docker-compose.yml создайте структуру для монтирования в контейнер: 173 | 174 | - ./data/prj1/metadata — Выгрузка отчет по конфигурации в формате .txt (в папке должен быть только один txt файл). В конфигураторе Конфигурация -> Отчет по конфигурации (в текстовый файл, Вся конфигурация) 175 | - ./data/prj1/code — Выгрузка конфигурации в файлы. В конфигураторе Конфигурация -> Выгрузить конфигурацию в файлы (XML-файлы) 176 | 177 | Аналогично по другим проектам: 178 | 179 | - ./data/prj2/metadata 180 | - ./data/prj2/code 181 | 182 | 4. Запуск 183 | 184 | ``` 185 | docker compose up -d 186 | ``` 187 | 188 | #### Сервисы 189 | 190 | - Neo4j: http://localhost:7474 (логин neo4j / пароль из NEO4J_PASSWORD) 191 | - Bolt: bolt://localhost:7687 192 | - MCP сервер: http://localhost:6001/mcp (и другие порты, указанные в docker-compose.yml) 193 | 194 | #### Логи приложения 195 | 196 | ``` 197 | docker compose logs -f 1c-metacode-prj1 198 | ``` 199 | 200 | #### Первичный запуск 201 | 202 | - Приложение создаст индексы в Neo4j 203 | - Проведёт загрузку метаданных из ./data/metadata/*.txt 204 | - При включённых флагах — просканирует ./data/code и догрузит формы, предопределённые значения, права, подписки на события, модули с процедурами и функциями 205 | - Загрузка всех данных (без векторной индексации) занимает около 30 минут для типовой конфигурации Бухгалтерия (может увеличиться если слабый компьютер) 206 | - При включенной векторной индексации она запускается в фоне, после загрузки всех данных. MCP сервер во время векторной индексации доступен для запросов. 207 | - Векторная индексация описаний метадананных и процедур/функций занимает около 30 минут для типовой конфигурации Бухгалтерия с использованием модели Qwen3-Embedding-4B_Q8 на 5070Ti 208 | - Для загрузки требуется оперативной памяти из расчета 4 ГБ для Neo4j и по 6 ГБ на каждую одновременно загружаемую базу. После загрузки потребление памяти значительно снижается. 209 | 210 | #### Обновление/перезагрузка данных 211 | 212 | - Для полной перезагрузки данных проекта установите в docker-compose.yml переменную для соответсвующего проекта и перезапустите контейнер: 213 | 214 | ``` 215 | FULL_METADATA_RELOAD=true 216 | docker compose restart 1c-metacode-prj1 217 | ``` 218 | 219 | #### Инструменты MCP 220 | 221 | Сервер публикует 3 инструмента: 222 | - `search_metadata` — Поиск объектов метаданных по их структурным свойствам, связям, техническим характеристикам и отношениям. 223 | - `search_metadata_by_description` — Поиск объектов метаданных по их семантическому содержанию, используя описания, комментарии, синонимы и внутренние имена. 224 | - `search_code` — Семантический поиск процедур и функций по их описаниям и получение исходного кода BSL. 225 | 226 | Более подробно в **[Описание возможностей MCP сервера](./MCP_SERVER_CAPABILITIES.md)** 227 | 228 | Транспорт: 229 | - По умолчанию streamable-http (HTTP путь /mcp) 230 | - При MCP_USE_SSE=true — SSE-режим 231 | 232 | Подключение клиентов 233 | Используйте любой MCP-совместимый клиент (например, IDE/агенты с поддержкой OpenAI MCP). Укажите: 234 | - transport: streamable-http или sse 235 | - endpoint: http://localhost:6001/mcp 236 | 237 | Пример mcp.json для Cline 238 | 239 | ``` 240 | { 241 | "mcpServers": { 242 | "1c-metacode": { 243 | "url": "http://localhost:6001/mcp", 244 | "connection_id": "1c_metacode_service_001", 245 | "alwaysAllow": [], 246 | "type": "streamable-http", 247 | "timeout": 300 248 | 249 | } 250 | } 251 | } 252 | ``` 253 | 254 | #### Обновление 255 | 256 | Для обновления на новую версию приложения 257 | 258 | ``` 259 | docker compose pull 260 | docker compose down --volumes 261 | docker compose up -d --force-recreate 262 | ``` 263 | 264 | Если нужно начать всё с нуля и удалить полностью базу то выполните 265 | 266 | ``` 267 | docker compose down --volumes 268 | docker compose up -d --force-recreate 269 | ``` 270 | 271 | #### Changelog 272 | 273 | ##### v1.3.0 - 2025-10-29 274 | - Добавлена поддержка загрузки процедур/функций из модуля формы обычных форм (файлы Form.bin). 275 | - Улучшена скорость загрузки (примерно в 2 раза) путем распараллеливания процесса загрузки на несколько ядер. 276 | - Добавлена векторная индексация описаний процедур/функций, описаний метаданных, а так же гибридный поиск по этим описаниям. 277 | 278 | ##### v1.2.0 - 2025-10-20 279 | - Добавлена загрузка тела процедур и функций, а также их описаний (комментарии над сигнатурой). 280 | - Возможность полнотекстового поиска процедур и функций по описанию. 281 | - Возможность получения тела процедуры/функции прямо из графовой базы. 282 | - Добавлена поддержка загрузки справки по объектам метаданным с возможностью полнотекстового поиска объектов метаданных по этой справке, а так же по другим описательным полям. 283 | 284 | ##### v1.1.0 - 2025-10-07 285 | - Добавлена поддержка загрузки подписок на события 286 | - Добавлена поддержка загрузки модулей с процедурами/функциями и формирования графа вызовов 287 | 288 | ##### v1.0.0 - 2025-09-30 289 | - Первоначальный релиз с загрузкой метаданных 1С в Neo4j 290 | - Поддержка MCP инструментов для поиска метаданных 291 | 292 | 293 | --------------------------------------------------------------------------------