---
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`

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

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

```bash
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`

**Параметры:**

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

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

**Поддерживаемые metaType:**
- `Catalogs` — справочники
- `Documents` — документы
- `InformationRegisters` — регистры сведений
- `AccumulationRegisters` — регистры накопления
- `AccountingRegisters` — регистры бухгалтерии
- `Enums` — перечисления
- И другие...

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

---

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

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

**Метод:** `tools/call`

**Параметры:**

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

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

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

---

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

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

**Метод:** `tools/call`

**Параметры:**

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

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

---

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

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

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

**Метод:** `tools/call`

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

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

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

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

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

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

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

✅ **ПРАВИЛЬНО** — значения явно:
```sql
ГДЕ Контрагент.Наименование = "ООО Ромашка"
ГДЕ Товар.Код = "000001"
```

✅ **ПРАВИЛЬНО** — использование описаний объекта:
```json
"parameters": {
  "Контрагент": {
    "_objectRef": true,
    "УникальныйИдентификатор": "...",
    "ТипОбъекта": "СправочникСсылка.Контрагенты"
  }
}
```

**Ответ:**

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

---

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

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

**Метод:** `tools/call`

**Параметры:**

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

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

---

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

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

**Метод:** `tools/call`

**Параметры:**

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

---

## Ресурсы (Resources)

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

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

Для чтения ресурса используй:
```bash
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С

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

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

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

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

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

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

---

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

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

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

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

**Функции дат:**

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

---

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

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

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

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

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

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

Строковые значения в кавычках:
```sql
ГДЕ Наименование = "iPhone 17 Pro Max"
ГДЕ Контрагент.ИНН = "7707083893"
```

---

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

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

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

---

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

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

---

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

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

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

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

---

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

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

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

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

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

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

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

---

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

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