1c-mcp

name	1c-mcp
description	MCP сервер для работы с базой данных 1С:Предприятие. Используй этот навык когда нужно получить данные из 1С, выполнить анализ данных в базе 1С, изучить структуру метаданных или написать запрос на языке 1С. Всегда начинай с list_metadata_objects если не знаешь точное имя объекта.

MCP сервер 1С:Предприятие

Обзор

MCP сервер (Model Context Protocol) для работы с базой данных 1С:Предприятие через HTTP-сервис. Позволяет выполнять запросы к базе данных, исследовать структуру метаданных, получать описания объектов и работать с навигационными ссылками.

Параметры подключения

• URL: http://localhost/unf/hs/mcp/
• Протокол: HTTP SSE (Server-Sent Events)
• Протокол MCP: версия 2025-03-26
• Авторизация: Basic (login: test, password: test)
• Content-Type: application/json

Инициализация соединения

Перед использованием инструментов необходимо инициализировать соединение:

curl -X POST "http://localhost/unf/hs/mcp/" \
  -H "Authorization: Basic dGVzdDp0ZXN0 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "agent", "version": "1.0"}
    }
  }'

Примечание: Base64 для test:test = dGVzdDp0ZXN0

---

Инструменты (Tools)

1. list_metadata_objects — Разведка конфигурации

Назначение: Поиск объектов метаданных по типу и имени. Используй ПЕРЕД любыми запросами когда не знаешь точное имя объекта.

Метод: tools/call

Параметры:

{
  "name": "list_metadata_objects",
  "arguments": {
    "metaType": "Documents",
    "nameMask": "реализ",
    "maxItems": 100
  }
}

Параметр	Тип	Обязательный	Описание
metaType	string	✅	Тип объекта метаданных
nameMask	string	❌	Фильтр по имени/синониму (регистронезависимый)
maxItems	number	❌	Макс. результатов (по умолчанию 100)

Поддерживаемые metaType:

• Catalogs — справочники
• Documents — документы
• InformationRegisters — регистры сведений
• AccumulationRegisters — регистры накопления
• AccountingRegisters — регистры бухгалтерии
• Enums — перечисления
• И другие...

Ответ:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "toolOutputs": [{
      "output": [
        {"name": "РеализацияТоваровУслуг", "synonym": "Реализация товаров и услуг"},
        {"name": "РеализацияОтгруженныхТоваров", "synonym": "Реализация отгруженных товаров"}
      ]
    }]
  }
}

---

2. get_metadata_structure — Изучение структуры объекта

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

Метод: tools/call

Параметры:

{
  "name": "get_metadata_structure",
  "arguments": {
    "metaType": "Documents",
    "name": "РеализацияТоваровУслуг"
  }
}

Параметр	Тип	Обязательный	Описание
metaType	string	✅	Тип объекта (Documents, Catalogs и др.)
name	string	✅	Имя объекта БЕЗ префикса типа

Ответ:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "toolOutputs": [{
      "output": {
        "attributes": [
          {"name": "Контрагент", "type": "СправочникСсылка.Контрагенты"},
          {"name": "СуммаДокумента", "type": "Число"}
        ],
        "tabularSections": [
          {"name": "Товары", "fields": [...]}
        ]
      }
    }]
  }
}

---

3. validate_query — Проверка синтаксиса запроса

Назначение: Проверка синтаксиса запроса 1С БЕЗ выполнения и БЕЗ обращения к базе данных. Быстрая операция — только парсинг текста.

Метод: tools/call

Параметры:

{
  "name": "validate_query",
  "arguments": {
    "queryText": "ВЫБРАТЬ Ссылка ИЗ Справочник.Контрагенты"
  }
}

Параметр	Тип	Обязательный	Описание
queryText	string	✅	Текст запроса 1С для проверки

---

4. execute_query — Основной инструмент

Назначение: ОСНОВНОЙ ИНСТРУМЕНТ для получения данных из 1С. Выполняет запрос и возвращает данные с автоматической обработкой ссылочных типов.

Особенности:

• Ссылочные поля автоматически конвертируются в объекты с _objectRef: true
• Результаты можно использовать как параметры для следующих запросов
• Можно организовывать цепочки запросов для углубления по связям

Метод: tools/call

Базовый запрос:

{
  "name": "execute_query",
  "arguments": {
    "queryText": "ВЫБРАТЬ ПЕРВЫЕ 10 Ссылка, Наименование ИЗ Справочник.Контрагенты",
    "limit": 10
  }
}

Запрос с параметрами (объектные ссылки):

{
  "name": "execute_query",
  "arguments": {
    "queryText": "ВЫБРАТЬ ПЕРВЫЕ 10 * ИЗ Документ.РеализацияТоваровУслуг ГДЕ Контрагент = &Контрагент",
    "parameters": {
      "Контрагент": {
        "_objectRef": true,
        "УникальныйИдентификатор": "9e6f1a6b-...",
        "ТипОбъекта": "СправочникСсылка.Контрагенты",
        "Представление": "ООО Ромашка"
      }
    },
    "limit": 10
  }
}

Параметр	Тип	Обязательный	Описание
queryText	string	✅	Текст запроса на языке 1С
parameters	object	❌	Параметры запроса (объектные описания)
limit	number	❌	Ограничение строк (по умолчанию 100, максимум 1000)

Важные ограничения:

❌ НЕПРАВИЛЬНО — использование параметров через &:

ГДЕ Товар = &Товар

✅ ПРАВИЛЬНО — значения явно:

ГДЕ Контрагент.Наименование = "ООО Ромашка"
ГДЕ Товар.Код = "000001"

✅ ПРАВИЛЬНО — использование описаний объекта:

"parameters": {
  "Контрагент": {
    "_objectRef": true,
    "УникальныйИдентификатор": "...",
    "ТипОбъекта": "СправочникСсылка.Контрагенты"
  }
}

Ответ:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "truncated": false,
    "columns": ["Ссылка", "Наименование"],
    "rows": [
      [
        {
          "_objectRef": true,
          "УникальныйИдентификатор": "9e6f1a6b...",
          "ТипОбъекта": "СправочникСсылка.Контрагенты",
          "Представление": "ООО Ромашка"
        },
        "ООО Ромашка"
      ]
    ]
  }
}

---

5. parse_nav_link — Парсинг навигационной ссылки

Назначение: Преобразует навигационную ссылку 1С (e1cib/data/...) в описание объекта. Используй когда пользователь присылает ссылку из 1С.

Метод: tools/call

Параметры:

{
  "name": "parse_nav_link",
  "arguments": {
    "navLink": "e1cib/data/Документ.РеализацияТоваровУслуг?ref=9e6f1a6b-..."
  }
}

Параметр	Тип	Обязательный	Описание
navLink	string	✅	Навигационная ссылка формата e1cib/data/...

---

6. get_nav_link — Получение навигационной ссылки

Назначение: Получает навигационную ссылку по описанию объекта. Используй чтобы дать пользователю кликабельную ссылку для открытия в 1С.

Метод: tools/call

Параметры:

{
  "name": "get_nav_link",
  "arguments": {
    "objectDescription": {
      "_objectRef": true,
      "УникальныйИдентификатор": "9e6f1a6b...",
      "ТипОбъекта": "ДокументСсылка.РеализацияТоваровУслуг"
    }
  }
}

---

Ресурсы (Resources)

1csyntax — Справочник синтаксиса 1С

• URI: file://resource/syntax_1c.txt
• Описание: Описание синтаксиса встроенного языка 1С:Предприятие в формате Markdown

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

curl -X POST "http://localhost/unf/hs/mcp/" \
  -H "Authorization: Basic dGVzdDp0ZXN0" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "resources/read",
    "params": {"uri": "file://resource/syntax_1c.txt"}
  }'

---

Рекомендуемый порядок работы

1. list_metadata_objects    → найти нужные объекты по имени
2. get_metadata_structure   → изучить структуру объекта
3. validate_query           → проверить синтаксис (опционально)
4. execute_query            → получить данные
5. get_nav_link             → создать ссылку для открытия в 1С

---

Синтаксис запросов 1С

Базовая структура

ВЫБРАТЬ [РАЗЛИЧНЫЕ] [ПЕРВЫЕ N]
    <Поля выборки>
ИЗ
    <Источники данных>
[ГДЕ
    <Условия отбора>]
[СГРУППИРОВАТЬ ПО
    <Поля группировки>]
[УПОРЯДОЧИТЬ ПО
    <Поля сортировки>]

Основные источники данных

Тип объекта	Синтаксис
Справочник	Справочник.ИмяСправочника
Документ	Документ.ИмяДокумента
Табличная часть	Документ.ИмяДокумента.ИмяТабличнойЧасти
Регистр накопления (остатки)	РегистрНакопления.ИмяРегистра.Остатки()
Регистр накопления (обороты)	РегистрНакопления.ИмяРегистра.Обороты()
Регистр сведений	РегистрСведений.ИмяРегистра
Регистр сведений (срез последних)	РегистрСведений.ИмяРегистра.СрезПоследних()

Суффиксы ресурсов регистра накопления

Таблица	Суффикс	Пример
Остатки()	Остаток	КоличествоОстаток
ОстаткиИОбороты()	НачальныйОстаток, Приход, Расход, КонечныйОстаток	КоличествоКонечныйОстаток
Обороты()	Приход, Расход, Оборот	КоличествоПриход

---

Работа с датами

Функция ДАТАВРЕМЯ:

ДАТАВРЕМЯ(Год, Месяц, День[, Час, Минута, Секунда])

ГДЕ Документы.Дата >= ДАТАВРЕМЯ(2026, 1, 1)
ДАТАВРЕМЯ(2026, 1, 1, 12, 30, 0)  -- с точностью до секунд

Функции дат:

Функция	Описание	Пример
ГОД()	Год из даты	ГОД(Дата)
КВАРТАЛ()	Квартал	КВАРТАЛ(Дата)
МЕСЯЦ()	Месяц	МЕСЯЦ(Дата)
ДЕНЬ()	День месяца	ДЕНЬ(Дата)
НАЧАЛОПЕРИОДА()	Начало периода	НАЧАЛОПЕРИОДА(Дата, МЕСЯЦ)
КОНЕЦПЕРИОДА()	Конец периода	КОНЕЦПЕРИОДА(Дата, МЕСЯЦ)

---

Работа со строками

Оператор ПОДОБНО:

ГДЕ Наименование ПОДОБНО "%телефон%"     -- содержит
ГДЕ Код ПОДОБНО "001___"                  -- ровно 3 символа после 001

• % — любое количество символов
• _ — один символ

Функции строк:

Функция	Описание
ПОДСТРОКА(Строка, Начало, Длина)	Часть строки
ДЛИНА(Строка)	Длина строки

Строковые значения в кавычках:

ГДЕ Наименование = "iPhone 17 Pro Max"
ГДЕ Контрагент.ИНН = "7707083893"

---

Агрегатные функции

Функция	Описание
СУММА()	Сумма значений
КОЛИЧЕСТВО()	Количество записей
МАКСИМУМ()	Максимальное значение
МИНИМУМ()	Минимальное значение
СРЕДНЕЕ()	Среднее значение

ВЫБРАТЬ ПЕРВЫЕ 20
    Продажи.Номенклатура.Наименование КАК Товар,
    СУММА(Продажи.Количество) КАК ВсегоПродано,
    СУММА(Продажи.Сумма) КАК СуммаПродаж
ИЗ
    РегистрНакопления.Продажи.Обороты(
        ДАТАВРЕМЯ(2026, 1, 1),
        ДАТАВРЕМЯ(2026, 1, 31)
    ) КАК Продажи
СГРУППИРОВАТЬ ПО
    Продажи.Номенклатура

---

Условный оператор ВЫБОР

ВЫБРАТЬ ПЕРВЫЕ 50
    Товары.Наименование,
    ВЫБОР
        КОГДА Товары.ЭтоГруппа = ИСТИНА ТОГДА "Группа"
        ИНАЧЕ "Элемент"
    КОНЕЦ КАК ТипЗаписи
ИЗ
    Справочник.Номенклатура КАК Товары

---

Связывание результатов запросов (ИТЕРАТИВНЫЙ ПОДХОД)

Пример цепочки запросов:

1. Получаем договор:

ВЫБРАТЬ ПЕРВЫЕ 1
    Ссылка,
    Контрагент
ИЗ
    Документ.ДоговорыКонтрагентов
ГДЕ
    Номер = "001"

2. Используем Контрагент для поиска других договоров:

{
  "name": "execute_query",
  "arguments": {
    "queryText": "ВЫБРАТЬ Ссылка, Номер ИЗ Документ.ДоговорыКонтрагентов ГДЕ Контрагент = &Контрагент",
    "parameters": {
      "Контрагент": <результат_запроса_1.Контрагент>
    }
  }
}

---

Примеры запросов

Остатки товаров на складах

ВЫБРАТЬ ПЕРВЫЕ 100
    Остатки.Номенклатура.Наименование КАК Товар,
    Остатки.Склад.Наименование КАК Склад,
    Остатки.КоличествоОстаток КАК Количество
ИЗ
    РегистрНакопления.ТоварыНаСкладах.Остатки() КАК Остатки
ГДЕ
    Остатки.КоличествоОстаток > 0
УПОРЯДОЧИТЬ ПО
    Товар

Документы за период

ВЫБРАТЬ ПЕРВЫЕ 50
    Док.Номер,
    Док.Дата,
    Док.Контрагент.Наименование КАК Контрагент,
    Док.СуммаДокумента
ИЗ
    Документ.РеализацияТоваровУслуг КАК Док
ГДЕ
    Док.Дата >= ДАТАВРЕМЯ(2026, 1, 1)
    И Док.Дата < ДАТАВРЕМЯ(2026, 2, 1)
    И Док.Проведен = ИСТИНА
УПОРЯДОЧИТЬ ПО
    Док.Дата УБЫВ

Актуальные цены

ВЫБРАТЬ ПЕРВЫЕ 100
    Цены.Номенклатура.Наименование КАК Товар,
    Цены.ТипЦен.Наименование КАК ТипЦены,
    Цены.Цена
ИЗ
    РегистрСведений.ЦеныНоменклатуры.СрезПоследних() КАК Цены
УПОРЯДОЧИТЬ ПО
    Товар

---

Типичные ошибки и решения

Ошибка	Причина	Решение
"Параметр не найден"	Использование &ИмяПараметра	Указывать значения явно
Ошибка при сравнении ссылок	Прямое сравнение ссылочных полей	Сравнивать через .Код, .Наименование
Слишком много данных / таймаут	Нет ограничения ПЕРВЫЕ N	Всегда использовать ПЕРВЫЕ N
NULL в вычислениях	Левое соединение без обработки NULL	Использовать ЕСТЬNULL(Поле, 0)