convez.ai
MCP Server
gsbelarus

1c-mcp-server

gsbelarus/1c-mcp-server

Ver no GitHub
InicialPluginScore · de 0 a 100

Instalação

$npx convez-ai gsbelarus/1c-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 3 meses
Versão
—
Issues abertas
1
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Universal 1C MCP Server (Read-Only)

Универсальный MCP-сервер для безопасного read-only доступа к данным и метаданным 1С:Предприятия 8. Постоянные данные не изменяются; временные таблицы языка запросов 1С разрешены как рабочая область выполнения аналитического запроса.

Сервер реализует протокол Model Context Protocol (MCP) 2025-11-25 поверх HTTP-сервиса 1С и предоставляет LLM-агентам 30 read-only инструментов согласно спецификации mcp_1c_tools_spec.md.

Возможности

  • Полностью read-only: создание/изменение/удаление объектов невозможно.
  • 30 tools: discovery → inspect → search → retrieve → explain → navigate → report → query guidance → data passport.
  • Allowlist/denylist типов метаданных и полей.
  • Маскирование заданных полей перед передачей ответа в LLM.
  • Лимиты строк, времени и размера результата.
  • Аудит всех вызовов с correlation_id.
  • Универсальный — не зависит от конкретной конфигурации (УТ, ERP, БП и т.п.).
  • LLM не должна выдумывать методы, сущности, таблицы и поля: все имена берутся из discovery/metadata tools, карты счетов или результата предыдущего вызова.
  • Поддержка MCP Streamable HTTP: один endpoint /rpc, JSON-RPC 2.0, 202 Accepted для notifications, 405 для GET/SSE при stateless-режиме.

См. вебинар AI in 1C: How to Automate Routine Tasks and Speed Up Business Processes.

Реализованные tools

№ToolНазначение
1list_metadata_objectsСписок объектов метаданных
2get_metadata_structureСтруктура объекта метаданных
3search_metadata_fieldsКомпактный поиск полей метаданных
4count_event_subscriptions_by_eventСтатистика подписок на события
5list_event_subscriptionsСписок подписок на события
6run_1c_queryБезопасный read-only запрос 1С
7validate_1c_queryПроверка запроса до выполнения
8get_1c_query_guidanceУниверсальные подсказки по языку запросов 1С
9list_registersКомпактный список регистров
10get_accounting_accounts_mapКарта счетов и субконто плана счетов
11get_accounting_balancesБухгалтерские остатки и обороты
12get_accounting_balances_by_subconto_ageAging бухгалтерских остатков по выбранному субконто
13compare_accounting_balances_by_subcontoСравнение двух наборов остатков по одной аналитике
14get_accounting_entriesБухгалтерские проводки с универсальным join к субконто
15get_inventory_balances_by_itemБыстрые остатки товара по складам и организациям
16get_calculation_types_mapКарта видов расчёта
17get_database_passportПаспорт фактических данных базы
18get_object_by_refПолучение объекта по типу и UUID
19find_object_by_idПоиск объекта по UUID без знания типа
20search_objectsПоиск по строке/коду/ИНН/артикулу
21get_link_of_objectНавигационная ссылка на объект
22find_references_to_objectПоиск ссылок на объект
23get_enum_valuesЗначения перечисления
24get_register_recordsЗаписи / срезы / остатки / обороты
25get_document_movementsДвижения документа по регистрам
26list_reportsСписок отчётов
27get_report_infoПараметры и структура отчёта
28run_1c_reportВыполнение отчёта
29get_object_historyИстория объекта / журнал регистрации
30get_current_user_contextКонтекст пользователя и базы

Подробное описание tools

Все инструменты вызываются через MCP tools/call. В arguments передаются только параметры конкретного tool; additionalProperties=false, поэтому лишние поля лучше не отправлять. Формат результата задаёт response.tool_result_mode: text_only возвращает полный JSON только в content[].text и не объявляет outputSchema; structured_only возвращает structuredContent и объявляет outputSchema; both возвращает оба канала и дублирует JSON в тексте. По умолчанию используется text_only, чтобы Claude Desktop/Windows точно видел значения без двойного расхода токенов. Для контрактных проверок tools/list и tools/call принимают JSON-RPC param _response_mode=text_only|structured_only|both, который временно переопределяет режим без изменения arguments конкретного tool. Каждый ответ содержит минимальный auth_context.user_name, auth_context.identity_key и cache_policy.cacheable=false; полный контекст доступен через get_current_user_context или include_auth_context=true. Если включён privacy-режим, в ответ добавляется privacy, совпадающие поля заменяются маской, а организации могут отображаться псевдонимами.

Общие ограничения для всех tools: учитываются права текущего пользователя 1С, allowlist/denylist метаданных, field-level ограничения, лимиты строк/таймаутов/размера JSON из MCP_ServerConfig. Имена объектов и полей нельзя угадывать: сначала используйте list_metadata_objects, get_metadata_structure, карту счетов или результат предыдущего вызова. Если вернулся error.code=access_denied, LLM должна объяснить пользователю нехватку прав и не повторять тот же запрос без перелогина или изменения прав.

Пример отказа доступа в режимах structured_only и both:

{
  "isError": true,
  "structuredContent": {
    "ok": false,
    "auth_context": {
      "user_name": "ivanov",
      "identity_key": "ivanov@ERP#2.5.19.123",
      "cache_policy": { "cacheable": false, "revalidate_each_call": true }
    },
    "authorization": {
      "reason_code": "1c_access_denied",
      "denied_operation": "query_execute",
      "retry_policy": "do_not_retry_same_request_without_reauth_or_permission_change"
    },
    "error": { "code": "access_denied", "message": "Недостаточно прав текущей учетной записи 1С." }
  }
}

list_metadata_objects

Назначение: discovery доступных объектов метаданных: справочников, документов, регистров, перечислений, отчётов и т.п.

Параметры: kinds: string[] фильтрует виды метаданных; query: string ищет по имени, синониму и комментарию; include_not_allowed: boolean доступен только MCP-admin; include_details: boolean добавляет комментарий; limit: integer 1..1000 = 200; cursor: string для следующей страницы.

Пример:

{
  "kinds": ["Справочник", "Документ"],
  "query": "клиент",
  "include_details": true,
  "limit": 20
}

Выходящая схема: objects[] { kind, name, full_name, synonym, comment?, allowed, readable, searchable, supports_ref, supports_query, resource_uri }, next_cursor, truncated, total_estimated, опционально domain_guidance.

Ограничения: на больших конфигурациях полный обход метаданных может быть заметным; сужайте kinds и query. Запрещённые объекты не возвращаются, если нет прав администратора MCP.

get_metadata_structure

Назначение: получить структуру конкретного объекта метаданных перед запросами, поиском, чтением регистров или объектов.

Параметры: обязательный type: string в формате Справочник.Номенклатура; флаги include_standard_attributes, include_tabular_sections, include_forms, include_commands, include_query_names, include_sensitive_flags, include_virtual_tables.

Пример:

{
  "type": "РегистрНакопления.ТоварыНаСкладах",
  "include_virtual_tables": true,
  "include_tabular_sections": false
}

Выходящая схема: metadata { kind, name, full_name, synonym, attributes[], standard_attributes[], tabular_sections[], register_schema?, query_table?, virtual_tables?, supports_ref?, supports_query? }.

Ограничения: возвращаются только разрешённые поля и объекты. Формы и команды обычно не нужны LLM и могут увеличить ответ.

count_event_subscriptions_by_event

Назначение: компактно посчитать подписки на события по имени события, чтобы перед аудитом не выгружать полный список подписок.

Параметры: include_top_handlers: boolean = false добавляет топ модулей-обработчиков по каждому событию; top_handlers_limit: integer 1..20 = 5.

Пример:

{
  "include_top_handlers": true,
  "top_handlers_limit": 5
}

Выходящая схема: events[] { event, count, top_handlers?[] { module, count } }, event_count, subscription_count, include_top_handlers, top_handlers_limit?, guidance.

Ограничения: это metadata discovery, а не чтение BSL-кода обработчика. Подписки с источниками, запрещенными allowlist/правами MCP, не возвращаются.

list_event_subscriptions

Назначение: получить список подписок на события с точечными фильтрами по событию и обработчику.

Параметры: event: string exact match по имени события; handler_contains: string поиск подстроки в имени обработчика без учета регистра; limit: integer 1..1000 = 50; cursor.

Пример:

{
  "event": "ПередЗаписью",
  "handler_contains": "ДатыЗапретаИзменения",
  "limit": 20
}

Выходящая схема: subscriptions[] { name, synonym, comment, event, handler, handler_module, handler_routine, source, source_name, source_full_name }, subscription_count, total_estimated, truncated, next_cursor, filters, guidance.

Ограничения: на больших конфигурациях сначала вызывайте count_event_subscriptions_by_event, затем сужайте список через event и handler_contains.

run_1c_query

Назначение: выполнить безопасный read-only запрос на языке запросов 1С. Временные таблицы в пакетах разрешены как рабочая область, изменение постоянных данных запрещено.

Параметры: обязательный query: string; parameters: object с типизированными значениями kind=string|number|boolean|date|datetime|uuid|ref|enum|array|null; limit: integer 1..1000 = 100; cursor; timeout_seconds: integer 1..60 = 15; validate_before_run (legacy-флаг, серверная проверка всё равно выполняется); return_format: rows|table; include_column_types.

Пример:

{
  "query": "ВЫБРАТЬ ПЕРВЫЕ 10 Н.Ссылка, Н.Наименование ИЗ Справочник.Номенклатура КАК Н ГДЕ Н.Наименование ПОДОБНО &Шаблон",
  "parameters": { "Шаблон": { "kind": "string", "value": "%кабель%" } },
  "limit": 10
}

Выходящая схема: validation { ok, valid, errors[], warnings[] }, columns[] { name, type_description }, rows[], row_count, truncated, next_cursor, duration_ms, warnings[], опционально query_guidance при include_guidance=true или диагностическом событии. При ошибках запроса дополнительно возвращаются error_code, hint, field, field_path, object, available_fields, suggestions и диагностический guidance.

Если бухгалтерский запрос к виртуальным таблицам Остатки/Обороты использует позиционные поля Субконто1/2/3 и возвращает 0 строк, warnings[] дополнительно подскажет проверить позицию аналитики через get_accounting_accounts_map с узким account_code_prefix.

Ограничения: может выполняться долго на больших БД, особенно при широких JOIN, виртуальных таблицах без параметров и отсутствии индексов. Не используйте ВЫБРАТЬ *; сначала получите структуру метаданных и ограничивайте поля, период и limit.

validate_1c_query

Назначение: проверить запрос до выполнения: read-only синтаксис, известные таблицы, параметры, доступ к объектам, рискованные конструкции.

Параметры: обязательный query: string; parameters: object; strict: boolean; explain: boolean; include_guidance: boolean = false.

Пример:

{
  "query": "ВЫБРАТЬ Н.Ссылка ИЗ Справочник.Номенклатура КАК Н",
  "strict": true,
  "include_guidance": true
}

Выходящая схема: valid: boolean, errors[] { code, message, location?, hint?, see_also? }, warnings[], detected_objects[], detected_parameters[], estimated_risk, опционально query_guidance/domain_guidance при include_guidance=true или legacy explain=true.

Ограничения: валидация не заменяет фактическое выполнение: часть ошибок платформы 1С обнаружится только при run_1c_query.

get_1c_query_guidance

Назначение: вернуть встроенные правила и подсказки по языку запросов 1С: временные таблицы, виртуальные таблицы, ИМЕЮЩИЕ, составные типы, субконто, параметры и производительность.

Параметры: topic: string или auto; query: string для контекстных подсказок; intent: string; include_examples: boolean; max_sections: integer 1..12 = 6.

Пример:

{
  "topic": "virtual-tables",
  "intent": "получить остатки товаров на дату",
  "include_examples": true
}

Выходящая схема: configuration_agnostic, source, topics[], guidance[] { topic, title, text, examples? }.

Ограничения: это справка, а не метаданные конкретной базы; прикладные имена всё равно нужно брать через discovery tools.

get_accounting_accounts_map

Назначение: прочитать ПланСчетов.<Имя>.ВидыСубконто и вернуть соответствие счетов позициям Субконто1/2/3.

Параметры: chart: string полное имя плана счетов или краткое имя; account_code_prefix: string; include_empty_subconto: boolean; limit: integer 1..1000 = 500; cursor; include_query: boolean; include_guidance: boolean = false.

Пример:

{
  "chart": "ПланСчетов.Хозрасчетный",
  "account_code_prefix": "41",
  "include_empty_subconto": true,
  "limit": 100
}

Выходящая схема: chart, filter, tabular_section, source_of_truth, accounts[] { code, name, ref?, subconto[] }, total_accounts, next_cursor, truncated, warnings[], опционально guidance, domain_guidance, query_used.

Ограничения: если доступно несколько планов счетов и chart не указан, tool вернёт needs_chart=true. На больших планах используйте account_code_prefix и пагинацию.

get_accounting_balances_by_subconto_age

Назначение: универсальный быстрый путь для aging бухгалтерских остатков на дату по выбранному субконто. Вызывающая сторона задаёт регистр, префиксы счетов, сторону остатка и порядок видов субконто; сервер не интерпретирует счета как дебиторку, кредиторку или авансы.

Параметры: обязательные account_code_prefixes: string[], balance_side: debit|credit, subconto_kinds: string[]|QueryParameterValue[]; опциональные accounting_register, as_of, group_subconto_index: 1..3 = 1, age_subconto_index: 1..3 = 3, extra_subconto_indexes: integer[], age_buckets: number[] = [90,180,365], min_age_days, min_amount, order_by: amount_desc|age_desc|account, include_query, include_guidance, limit, cursor.

Пример:

{
  "accounting_register": "РегистрБухгалтерии.Хозрасчетный",
  "as_of": "2026-06-29T23:59:59",
  "account_code_prefixes": ["62.01", "62.21", "62.31"],
  "balance_side": "debit",
  "subconto_kinds": [
    "Контрагенты",
    "Договоры",
    "Документы расчетов с контрагентом"
  ],
  "group_subconto_index": 1,
  "age_subconto_index": 3,
  "age_buckets": [90, 180, 365],
  "min_amount": 10000,
  "limit": 50
}

Выходящая схема: accounting_register, as_of, balance_side, account_code_prefixes, group_subconto_index, age_subconto_index, bucket_rows[], rows[], row_count, truncated, next_cursor, duration_ms, warnings[], configuration_agnostic, опционально guidance, query_used { detail, buckets }.

Ограничения: перед вызовом получите реальные виды субконто через get_accounting_accounts_map; порядок subconto_kinds задаёт порядок Субконто1/2/3 в виртуальной таблице Остатки. Строковые значения резолвятся по Наименование в ПланВидовХарактеристик.ВидыСубконтоХозрасчетные; UUID можно передать явно через kind=ref. Возраст считается по дате выбранного субконто, поэтому age_subconto_index должен указывать на аналитику, у значения которой есть реквизит Дата.

compare_accounting_balances_by_subconto

Назначение: универсально сравнить два набора бухгалтерских остатков на дату и найти пересечения по UUID выбранного субконто. Подходит для сценариев вида "по одному контрагенту есть остатки в двух разных наборах счетов", но бизнес-смысл наборов задаёт вызывающая сторона.

Параметры: обязательные subconto_kinds: string[]|QueryParameterValue[], left_account_code_prefixes: string[], left_balance_side: debit|credit, right_account_code_prefixes: string[], right_balance_side: debit|credit; опциональные accounting_register, as_of, match_subconto_index: 1..3 = 1, min_amount, include_query, include_guidance, limit, cursor.

Пример:

{
  "accounting_register": "РегистрБухгалтерии.Хозрасчетный",
  "as_of": "2026-06-29T23:59:59",
  "subconto_kinds": [
    "Контрагенты"
  ],
  "match_subconto_index": 1,
  "left_account_code_prefixes": ["62"],
  "left_balance_side": "debit",
  "right_account_code_prefixes": ["60"],
  "right_balance_side": "credit",
  "min_amount": 10000,
  "limit": 100
}

Выходящая схема: accounting_register, as_of, match_subconto_index, left_balance_side, right_balance_side, left_account_code_prefixes, right_account_code_prefixes, rows[], row_count, truncated, next_cursor, duration_ms, warnings[], configuration_agnostic, опционально guidance, query_used.

Ограничения: tool соединяет наборы по УникальныйИдентификатор(СубконтоN) и не содержит предметных правил конкретной конфигурации. Если нужная аналитика не первая, задайте match_subconto_index и передайте subconto_kinds в соответствующем порядке. Строковые значения резолвятся по Наименование; UUID можно передать явно через kind=ref.

get_accounting_entries

Назначение: быстрый универсальный путь для чтения проводок из основной таблицы РегистрБухгалтерии.* и, при необходимости, join к РегистрБухгалтерии.*.Субконто.

Параметры: accounting_register; period_from; period_to; debit_account_code_prefixes; credit_account_code_prefixes; subconto_side: debit|credit; subconto_kind { kind:"ref", type, uuid }; subconto_value { kind:"ref", type, uuid }; group_by: string[]; include_zero; include_query; include_guidance: boolean = false; limit; cursor.

Пример:

{
  "accounting_register": "Хозрасчетный",
  "credit_account_code_prefixes": ["02"],
  "subconto_side": "credit",
  "group_by": ["period_month", "credit_subconto"],
  "include_query": true,
  "limit": 100
}

Выходящая схема: стандартная табличная схема columns[], rows[], row_count, плюс accounting_register, mode, group_by, subconto_side, configuration_agnostic, опционально guidance, query_used.

Ограничения: tool не содержит бизнес-логики ОС/ТМЦ/НДС. Для фильтра или группировки по виду субконто сначала получите реальный subconto_kind из get_accounting_accounts_map или metadata/query результата. Группировка по debit_subconto/credit_subconto без subconto_kind или group_by=subconto_kind отклоняется как неоднозначная: в одном поле могут смешаться контрагенты, договоры и документы расчетов. Для долга, задолженности и сальдо на дату используйте Остатки/ОстаткиИОбороты, а не проводки.

get_inventory_balances_by_item

Назначение: быстрый путь для вопроса об остатках товара: найти номенклатуру, определить виды субконто и выполнить агрегированный запрос к бухгалтерскому регистру.

Параметры: item_query: string или item_ref { type, uuid }; item_type; as_of: string ISO-дата; accounting_register; chart; account_code_prefixes: string[]; item_subconto_name; warehouse_subconto_name; include_zero; include_query; include_guidance: boolean = false; limit: integer 1..1000 = 100.

Пример:

{
  "item_query": "Кабель ВВГ",
  "as_of": "2026-05-23T00:00:00",
  "account_code_prefixes": ["41", "43"],
  "limit": 50
}

Выходящая схема: стандартная табличная схема columns[], rows[], row_count, плюс item, item_search, as_of, accounting_register, chart, account_code_prefixes, subconto, totals, warnings[], опционально query_used.

Ограничения: ориентирован на бухгалтерские регистры и типовые субконто номенклатуры/складов. account_code_prefixes применяются для поиска видов субконто и как фильтр остатков по коду счёта. Если в базе другой план счетов или названия видов субконто, передайте их явно.

get_calculation_types_map

Назначение: получить реальные виды расчёта из ПланВидовРасчета.<Имя> для ЗУП-подобных конфигураций.

Параметры: plan: string; code_prefix: string; limit: integer 1..1000 = 500; cursor; include_query: boolean.

Пример:

{
  "plan": "ПланВидовРасчета.Начисления",
  "code_prefix": "ОКЛ",
  "limit": 50
}

Выходящая схема: plan, filter, calculation_types[] { code, name, ref?, ... }, total_calculation_types, next_cursor, truncated, warnings[], guidance, опционально query_used.

Ограничения: если доступно несколько планов и plan не указан, вернётся needs_plan=true. На больших планах используйте code_prefix.

get_database_passport

Назначение: диагностический паспорт фактических данных: активные организации, период данных, закрытые периоды, заполненность регистров.

Параметры: accounting_register; флаги include_organizations, include_period, include_closed_periods, include_accumulation_registers, include_information_registers, include_calculation_registers, include_empty_registers, force_refresh; лимиты organization_limit, accounting_register_limit, accumulation_register_limit, information_register_limit, calculation_register_limit.

Пример:

{
  "include_organizations": true,
  "include_period": true,
  "include_accumulation_registers": false,
  "include_information_registers": false,
  "force_refresh": false
}

Выходящая схема: generated_at, configuration_agnostic, read_only, cache_hit, cache_age_seconds, warnings[], опционально organizations[], data_period, accounting_registers[], closed_periods[], accumulation_registers, information_registers, calculation_registers и detail-разделы.

Ограничения: потенциально самый тяжёлый discovery tool на больших БД, потому что проверяет множество регистров. Выключайте лишние include_* и не используйте force_refresh без необходимости. В универсальной поставке кэш явно помечается через cache_hit/cache_age_seconds.

get_object_by_ref

Назначение: получить объект по точному типу и UUID ссылки.

Параметры: обязательные type, uuid; fields: string[]; include_standard_fields; include_tabular_sections; tabular_sections: string[]; tabular_section_row_limit: integer 1..1000 = 100; tabular_section_cursor; include_navigation_url.

Пример:

{
  "type": "Справочник.Номенклатура",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "fields": ["Код", "Наименование", "Артикул"],
  "include_tabular_sections": false
}

Выходящая схема: found, object { ref, standard_fields, fields, tabular_sections, tabular_sections_paging }; если объект не найден, object=null.

Ограничения: работает только для ссылочных объектов с разрешённым типом. Табличные части могут быть большими; включайте их выборочно и используйте курсор.

find_object_by_id

Назначение: найти объект по UUID, когда тип неизвестен.

Параметры: обязательный uuid; types: string[]; kinds: string[]; limit: integer 1..100 = 10; cursor; include_deleted.

Пример:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "kinds": ["Справочник", "Документ"],
  "limit": 5
}

Выходящая схема: found, matches[] { ref, standard_fields }, searched_types_count, types_truncated, truncated, next_cursor, warnings[].

Ограничения: может быть долгим, если не задать types/kinds, потому что перебирает разрешённые ссылочные типы. Перебор ограничен max_searched_types_per_call.

search_objects

Назначение: человеко-ориентированный поиск объектов по строке, коду, номеру, ИНН, артикулу и разрешённым поисковым полям.

Параметры: обязательный query; types; kinds; search_fields; filters; date_from; date_to; limit: integer 1..100 = 20; cursor; include_deleted; include_fields; match_mode: auto|exact|prefix|contains.

Пример:

{
  "query": "7701234567",
  "types": ["Справочник.Контрагенты"],
  "include_fields": ["ИНН", "КПП", "Наименование"],
  "match_mode": "exact"
}

Выходящая схема: matches[] { ref, score, matched_fields[], fields }, truncated, next_cursor.

Ограничения: поиск по многим типам может быть дорогим. filters объявлен в схеме, но универсальная реализация сейчас в основном использует строковый поиск и период для документов; для сложных фильтров лучше run_1c_query после проверки метаданных.

get_link_of_object

Назначение: получить навигационные ссылки на объект 1С: e1cib и, при разрешённом base_url, ссылку web-клиента.

Параметры: обязательные type, uuid; link_type: auto|e1cib|web_client|thin_client; base_url; include_presentation. Если base_url не передан, используется web_client.base_url из MCP_ServerConfig.

Пример:

{
  "type": "Документ.ЗаказКлиента",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "link_type": "auto",
  "base_url": "https://1c.example.com/base"
}

Выходящая схема: found, ref, presentation?, links[] { type, url, description }, warnings[].

Ограничения: base_url должен быть HTTP(S) и разрешён в allowlist. thin_client в универсальной реализации может вернуть предупреждение о неподдержанном формате.

find_references_to_object

Назначение: найти объекты, которые ссылаются на заданную ссылку.

Параметры: обязательный target { type, uuid }; search_in_types; search_in_kinds; period_from; period_to; limit_per_type: integer 1..100 = 20; max_types: integer 1..200 = 50; cursor; include_counts; include_samples.

Пример:

{
  "target": {
    "type": "Справочник.Номенклатура",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  },
  "search_in_kinds": ["Документ"],
  "include_samples": true
}

Выходящая схема: target, references[] { source_type, field_path, count, samples[], truncated }, searched_types_count, truncated, next_cursor, warnings[].

Ограничения: зависит от доступности штатного НайтиПоСсылкам и прав пользователя. Fallback может быть неполным; при недоступности сервер явно добавляет предупреждение.

get_enum_values

Назначение: получить значения перечисления.

Параметры: обязательный type в формате Перечисление.<Имя>; include_order; include_empty; limit: integer 1..1000 = 1000; cursor.

Пример:

{
  "type": "Перечисление.ВидыЦен",
  "include_order": true,
  "include_empty": true
}

Выходящая схема: type, values[] { name, presentation, order? }, next_cursor, truncated, total_estimated.

Ограничения: работает только с разрешёнными Перечисление.*; UUID-поиск к значениям перечислений не применяется.

get_register_records

Назначение: универсальное чтение регистров: записи, срезы первых/последних, остатки, обороты, остатки и обороты.

Параметры: обязательные register_type: РегистрСведений|РегистрНакопления|РегистрБухгалтерии|РегистрРасчета, register, mode: records|slice_first|slice_last|balance|turnovers|balance_and_turnovers|turnovers_debit_credit; period; period_from; period_to; filters; dimensions; resources; attributes; order_by; limit: integer 1..1000 = 100; cursor.

Пример:

{
  "register_type": "РегистрНакопления",
  "register": "ТоварыНаСкладах",
  "mode": "balance",
  "period": "2026-05-23T00:00:00",
  "dimensions": ["Номенклатура", "Склад"],
  "resources": ["Количество"],
  "limit": 100
}

Выходящая схема: register, mode, columns[] { name, type_description }, rows[], row_count, truncated, next_cursor, query_used, duration_ms.

Ограничения: режимы зависят от вида регистра. Для slice_* и balance нужен period; для оборотов нужны period_from и period_to. Для долга, задолженности, сальдо или остатка на дату используйте balance/Остатки, а не turnovers/Обороты: обороты показывают только движение за период и не включают входящее сальдо. Для "на конец 2024" дата остатка обычно 2025-01-01T00:00:00. Для зарплаты за период сначала предпочитайте зарплатные отчёты/расчётные регистры; бухгалтерский fallback по счёту 70 для начислений строится по кредитовому обороту 70, а не по дебету 70. Виртуальные таблицы на больших регистрах могут выполняться долго, особенно без фильтров по измерениям.

get_document_movements

Назначение: получить движения документа-регистратора по регистрам.

Параметры: обязательные document_type, uuid; registers: string[]; include_empty_registers; include_totals_effect; row_limit_per_register: integer 1..1000 = 200; cursor; row_cursor.

Пример:

{
  "document_type": "Документ.РеализацияТоваровУслуг",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "include_empty_registers": false,
  "row_limit_per_register": 100
}

Выходящая схема: found, document, movements[] { register, register_type, rows[], row_count, truncated, next_row_cursor }, truncated, next_cursor.

Ограничения: доступность зависит от прав на документ и регистры. Документы с большим количеством движений нужно читать постранично через cursor/row_cursor.

list_reports

Назначение: discovery доступных отчётов и вариантов.

Параметры: query; include_variants; include_not_allowed только MCP-admin; limit: integer 1..500 = 100; cursor.

Пример:

{
  "query": "продажи",
  "include_variants": true,
  "limit": 10
}

Выходящая схема: reports[] { type, name, synonym, description, allowed, execution_supported, execution_reason, has_custom_pre_compose, variants? }, next_cursor, truncated, total_estimated, опционально interaction_hint и domain_guidance.

Ограничения: возвращает только метаданные отчётов, не выполняет их. Для отчётной аналитики сначала выберите отчёт/вариант, затем вызывайте get_report_info.

get_report_info

Назначение: получить параметры, варианты и поддерживаемые форматы вывода отчёта.

Параметры: обязательный report; variant; include_schema; include_variants; include_default_settings.

Пример:

{
  "report": "Отчет.Продажи",
  "variant": "ПродажиПоКонтрагентам",
  "include_default_settings": true
}

Выходящая схема: report, synonym, variants[], has_custom_pre_compose, report_parameter_source, parameters[] { name, presentation, type_description, required, default_value }, output_formats[], warnings[], опционально domain_guidance.

Ограничения: подробная схема СКД в универсальном адаптере может не возвращаться даже при include_schema=true; тогда в warnings будет явное сообщение.

run_1c_report

Назначение: выполнить разрешённый отчёт 1С через СКД и вернуть табличный результат.

Параметры: обязательный report; variant; parameters: object; output_format: table|json|text; limit: integer 1..1000 = 200; cursor; timeout_seconds: integer 1..180 = 60; include_totals.

Пример:

{
  "report": "Отчет.Продажи",
  "variant": "Основной",
  "parameters": {
    "ДатаНачала": { "kind": "date", "value": "2026-01-01" },
    "ДатаОкончания": { "kind": "date", "value": "2026-05-23" }
  },
  "limit": 200
}

Выходящая схема: report, variant, execution_supported, columns[], rows[], totals, row_count, truncated, next_cursor, total_estimated, duration_ms, pre_compose_applied, warnings[], parameters_used.

Ограничения: отчёты СКД могут выполняться существенно дольше прямых узких запросов, особенно с широкими периодами и детализацией. Используйте параметры периода, небольшой limit и timeout_seconds.

get_object_history

Назначение: получить историю объекта из журнала регистрации и/или подсистемы версионирования, если они доступны.

Параметры: обязательный target { type, uuid }; mode: auto|versions|event_log|status_changes; period_from; period_to; include_diff; limit: integer 1..500 = 100; cursor.

Пример:

{
  "target": {
    "type": "Документ.ЗаказКлиента",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  },
  "mode": "event_log",
  "period_from": "2026-01-01T00:00:00",
  "limit": 50
}

Выходящая схема: supported, target, events[] { timestamp, user, event_type, description, diff }, truncated, next_cursor, capabilities { versions, event_log, diff }.

Ограничения: журнал регистрации требует соответствующих прав 1С. diff в универсальной реализации не поддержан (capabilities.diff=false); если источники истории недоступны, tool возвращает supported=false или пустой список без фатальной ошибки.

get_current_user_context

Назначение: получить текущий контекст пользователя, базы, версии сервера, лимитов и summary доступных метаданных.

Параметры: include_roles; include_limits; include_allowed_metadata_summary; include_server_info.

Пример:

{
  "include_roles": true,
  "include_limits": true,
  "include_allowed_metadata_summary": true,
  "include_server_info": true
}

Выходящая схема: user { name, full_name, roles? }, auth_context { user_name, infobase_name, configuration_version, identity_key, generated_at, cache_policy }, authorization_policy, infobase { name, synonym, configuration_name, configuration_version, platform_version, host }, mcp_server { name, version, read_only, tools[] }, limits, privacy, allowed_metadata_summary { objects_count, kinds }.

Ограничения: не заменяет list_metadata_objects, потому что возвращает только summary. Роли и сведения о пользователе могут быть ограничены правами и политикой безопасности.

Структура проекта

1c MCP/
├── README.md                  -- этот файл
├── INSTALL.md                 -- инструкция по установке в 1С
├── ARCHITECTURE.md            -- описание архитектуры
├── config/
│   ├── allowlist.json         -- пример allowlist метаданных
│   └── server_config.json     -- пример лимитов и настроек
└── src/
    ├── HTTPServices/
    │   └── MCP_HTTPService.bsl              -- HTTP-сервис, точка входа
    └── CommonModules/
        ├── MCP_Config.bsl                   -- конфигурация и лимиты
        ├── MCP_JSONRPC.bsl                  -- JSON-RPC 2.0 + MCP dispatcher
        ├── MCP_Errors.bsl                   -- единая модель ошибок
        ├── MCP_Security.bsl                 -- allowlist, права, ограничения
        ├── MCP_Audit.bsl                    -- аудит вызовов
        ├── MCP_Values.bsl                   -- кодирование значений 1С в JSON
        ├── MCP_Metadata.bsl                 -- обход метаданных
        ├── MCP_Query.bsl                    -- безопасные запросы 1С
        ├── MCP_Knowledge.bsl                -- встроенные правила языка запросов 1С для LLM
        ├── MCP_Registers.bsl                -- работа с регистрами
        ├── MCP_Reports.bsl                  -- работа с отчётами (СКД)
        ├── MCP_History.bsl                  -- история объектов
        ├── MCP_Tools.bsl                    -- описания и dispatcher tools
        └── MCP_Tools_Impl.bsl               -- реализация tools

Транспорт

HTTP-сервис MCP реализует Streamable HTTP endpoint:

http(s)://<сервер>/<база>/hs/mcp/rpc

Поддерживаемые HTTP-методы:

POST     -- JSON-RPC request / notification / response
GET      -- 405 Method Not Allowed, если не нужен server-to-client SSE
DELETE   -- 405 Method Not Allowed, сессии транспорта не создаются
OPTIONS  -- CORS preflight

Поддерживаемые JSON-RPC методы:

initialize           -- инициализация сессии
notifications/initialized -- lifecycle notification после initialize
tools/list           -- список инструментов
tools/call           -- вызов инструмента
resources/list       -- список ресурсов (необязательно)
resources/read       -- чтение ресурса
ping                 -- ping

Встроенная база знаний для LLM

Сервер отдаёт знания из doc/skills через MCP, чтобы агент мог составлять запросы 1С без привязки к конкретной конфигурации:

  • tool get_1c_query_guidance возвращает короткие контекстные подсказки по теме или черновику запроса;
  • tool get_accounting_accounts_map читает live-таблицу ПланСчетов.<Имя>.ВидыСубконто и возвращает accounts[].subconto[], чтобы агент не угадывал позиции Субконто1/2/3;
  • tool get_calculation_types_map читает ПланВидовРасчета.<Имя> и возвращает реальные виды расчёта для ЗУП-подобных конфигураций;
  • для зарплатных запросов база знаний закрепляет порядок выбора источника: готовый зарплатный отчёт или расчётные регистры, затем бухгалтерский fallback по кредитовому обороту 70 через Обороты;
  • tool get_database_passport возвращает фактический срез данных: активные организации, горизонт записей, закрытые периоды при наличии регистра дат запрета и заполненность регистров накопления/сведений/расчёта; параметр force_refresh принудительно пересчитывает паспорт, а поля cache_hit/cache_age_seconds показывают состояние кэша или его отсутствие в универсальной read-only поставке;
  • validate_1c_query и run_1c_query возвращают query_guidance opt-in через include_guidance=true; при ошибках выполнения диагностический guidance возвращается принудительно;
  • run_1c_query без дополнительного discovery добавляет компактный warning, если нулевой результат похож на неверно угаданную позицию бухгалтерского Субконто1/2/3;
  • resources 1c://knowledge/query/* дают полную встроенную справку: syntax, functions, optimization, temporary-tables, compound-types, subconto, parameters, reports-vs-query, report-fast-path, payroll.

Главное правило этой базы знаний: сначала получить метаданные через list_metadata_objects / get_metadata_structure, затем писать запрос по фактическим именам объектов и полей текущей базы.

Быстрый старт

  1. Установите расширение конфигурации (см. INSTALL.md).
  2. Опубликуйте HTTP-сервис на веб-сервере (IIS/Apache).
  3. Настройте config/allowlist.json под свою конфигурацию.
  4. Создайте сервисного пользователя 1С с минимальными правами.
  5. Подключите MCP-клиента к http(s)://.../hs/mcp/rpc.

См. подробности в INSTALL.md.

Полный доступ для тестирования

Для локального стенда или демо-базы удобно открыть чтение всех стандартных объектов метаданных. Постоянные данные при этом всё равно остаются read-only: сервер не выполняет запись, проведение, удаление или изменение прикладных объектов; временные таблицы разрешены только как рабочая область запроса.

Важно: config/server_config.json настраивает CORS/HTTP и лимиты выполнения. Доступ к объектам метаданных задаётся allowlist-конфигом, который сервер читает из константы 1С MCP_Allowlist или из примера config/allowlist.json.

Защита персональных данных

В MCP_ServerConfig можно указать поля, значения которых нельзя передавать в LLM:

{
  "web_client": {
    "base_url": "https://laba-1c.astondevs.ru/BUH_KORP"
  },

  "privacy": {
    "masked_fields": ["ФИО", "ДатаРождения", "НомерПаспорта", "ПерсональныйНомер"],
    "organization_aliases": {
      "enabled": true,
      "prefix": "Орг-",
      "include_navigation_url": true
    },
    "person_aliases": {
      "enabled": true,
      "physical_person_prefix": "ФЛ-",
      "employee_prefix": "Сотр-",
      "user_prefix": "Польз-",
      "include_navigation_url": true
    }
  }
}

web_client.base_url задаёт корневой URL web-клиента 1С. Если он заполнен, ObjectRef.navigation_url возвращается как кликабельная HTTP(S)-ссылка вида https://.../e1cib/data/<Тип>?ref=<uuid>, а исходная ссылка платформы сохраняется в e1cib_navigation_url. Для стендов с включённым restrict_data_access: true этот URL также нужно добавить в allowed_base_urls allowlist.

Если masked_fields отсутствует или пустой, сервер отдаёт данные как раньше. Если список заполнен, совпадающие поля маскируются во всех tool-ответах: обычные значения заменяются на XXXXXXX, даты — на 1900-01-01T00:00:00 (01.01.1900). Сравнение имён регистронезависимое и не учитывает пробелы, дефисы и подчёркивания, поэтому правило остаётся общим и не привязано к конкретной конфигурации 1С.

organization_aliases по умолчанию выключен. Если включить enabled: true, сервер заменяет полные названия Справочник.Организации на стабильные коды вида Орг-453276 во всех tool-ответах, ресурсах и диагностических JSON-данных. Ссылки сохраняют type, uuid, ref и доступный navigation_url; при настроенном web_client.base_url это конечная ссылка web-клиента, пригодная для открытия из чата. Если в произвольном результате есть только строковое поле, явно похожее на организацию, но нет UUID/ссылки, сервер возвращает Орг-скрыто.

person_aliases по умолчанию выключен. Если включить enabled: true, сервер заменяет presentation и поля ФИО у Справочник.ФизическиеЛица, Справочник.Сотрудники* и Справочник.Пользователи стабильными кодами вида ФЛ-453276, Сотр-453276 или Польз-453276. При настроенном web_client.base_url navigation_url у таких ссылок тоже становится кликабельной web-ссылкой. Паспортные данные, индивидуальный номер, страховой номер и дата рождения маскируются как чувствительные поля. Если в произвольном результате есть только строковое поле, явно похожее на физлицо/сотрудника, но нет UUID/ссылки, сервер возвращает ФЛ-скрыто.

Технические имена метаданных не маскируются: type, full_name, kind, register, chart, plan, resource_uri и похожие поля остаются валидными идентификаторами 1С. Privacy применяется к данным и представлениям ссылок, а не к схеме.

Когда privacy-режим включен, сервер явно сообщает об этом LLM: добавляет privacy в каждый tool-result, возвращает privacy в get_current_user_context, а также добавляет короткую подсказку в tools/list/описания tools. Агент должен считать перечисленные поля, названия организаций и ФИО/персональные реквизиты намеренно недоступными и не пытаться обходить политику альтернативными запросами.

Форма служебного блока: { "enabled": true, "masked_fields": [...], "string_mask": "XXXXXXX", "date_mask": "1900-01-01T00:00:00", "organization_aliases": {"enabled": true, "prefix": "Орг-", "resolution": "open_navigation_url_in_1c"}, "person_aliases": {"enabled": true, "physical_person_prefix": "ФЛ-", "employee_prefix": "Сотр-", "user_prefix": "Польз-", "resolution": "open_navigation_url_in_1c"}, "guidance": "..." }.

Per-user права и кэширование

При работе через промежуточный Python-сервер с per-session учетными данными каждый HTTP-запрос к 1С выполняется в контексте текущего пользователя 1С. Поэтому права проверяются на каждом вызове tool и в каждом ответе возвращается auth_context.cache_policy.cacheable=false. Если клиент перелогинился, прежние сведения о доступных объектах, отчетах и полях надо считать устаревшими.

Ошибки прав возвращаются как обычный MCP tool result с isError=true, error.code=access_denied и блоком authorization. В режиме text_only диагностика находится в JSON внутри content[]; в режиме both критичная диагностика дополнительно дублируется в content[] строкой Диагностика JSON: ..., потому что некоторые proxy-реализации MCP передают LLM только текстовый content и теряют structuredContent.

Минимальный allowlist для полного тестового доступа:

{
  "restrict_data_access": false,
  "default_policy": "allow",
  "allowed_kinds": [
    "Справочник",
    "Документ",
    "Перечисление",
    "РегистрСведений",
    "РегистрНакопления",
    "РегистрБухгалтерии",
    "РегистрРасчета",
    "ПланСчетов",
    "ПланВидовХарактеристик",
    "ПланВидовРасчета",
    "ПланОбмена",
    "БизнесПроцесс",
    "Задача",
    "Отчет"
  ],
  "denied_objects": [],
  "allowed_metadata": {},
  "allowed_base_urls": []
}

Быстрый порядок настройки:

  1. Скопируйте JSON выше в константу 1С MCP_Allowlist или замените им содержимое config/allowlist.json перед переносом настроек в базу.
  2. В config/server_config.json для тестов задайте разумные лимиты строк, размера ответа и таймаутов. Read-only политика и правила временных таблиц задаются в коде сервера, а не в JSON-конфиге.
  3. Используйте отдельного сервисного пользователя и тестовую базу. Для продуктивной базы верните явные denied_objects, hidden_fields и точечный allowed_metadata.

Версия

  • MCP-протокол: 2025-11-25
  • Сервер: 0.1.0
  • Платформа 1С: 8.3.18+ (используется ЗаписьJSON, HTTP-сервисы, ОписаниеТипов).
Ver o original no GitHub

Relacionados