# INFATON MCP Server для 1С:Предприятие

[![MCP35 MCP server](https://glama.ai/mcp/servers/infaton/MCP35/badges/card.svg)](https://glama.ai/mcp/servers/infaton/MCP35)

**Model Context Protocol (MCP)** — сервер на стороне 1С:Предприятие, предоставляющий **93 инструмента** для взаимодействия AI-ассистентов с базой данных 1С.

Протокол: **JSON-RPC 2.0** (спецификация [MCP](https://modelcontextprotocol.io/))

> Часть платформы **INFATON** — цифровые двойники и AI-агенты над 1С:ERP.
> Компания: **[infaton.ru](https://infaton.ru)** · Продукт: **[chatmcp.ru](https://chatmcp.ru)** (ChatMCP — чат-двойник над вашей 1С:ERP).

---

## 🏗 Кто использует

INFATON MCP Server — движок доступа AI к 1С в продуктах платформы INFATON:

- **[eventcode.ru](https://eventcode.ru)** — платформа заказной разработки: AI-агенты ведут проекты и работают с 1С:ERP заказчика через этот MCP-сервер.
- **[chatmcp.ru](https://chatmcp.ru)** — ChatMCP, цифровой двойник над 1С:ERP: чат-интерфейс и рабочие места (АРМ) поверх этого MCP-сервера.

Сервер открыт (MIT) — используйте в своём продукте, см. [Быстрый старт](#-быстрый-старт).

---

## 📋 Состав репозитория

| Файл | Описание |
|------|----------|
| `Module.bsl` | Модуль HTTP-сервиса MCP — основной код, 93 инструмента (7 350 строк) |
| `index.mjs` | Node.js stdio-обёртка для MCP-клиентов (Claude Desktop, Cursor и др.) |
| `package.json` | npm-манифест для публикации и запуска через `npx` |
| `glama.json` | Манифест для каталога [Glama.ai](https://glama.ai/) |
| **сборка .cfe** | Соберите расширение из `Module.bsl` (**v6.2.1**) — см. `HOW_TO_BUILD_CFE.md` |
| `HOW_TO_BUILD_CFE.md` | Инструкция по сборке и установке `.cfe` |
| `EXAMPLES.md` | Примеры агентских сценариев (7 кейсов) |
| `CHANGELOG.md` | История версий |

---

## 🆕 Что нового в v6.2.1

- **Безопасная запись составных ссылок по GUID** (6.2.1): объект проверяется в каждом разрешённом типе, несуществующий GUID отклоняется.
- **`fill_counterparty_by_inn`** (6.2.0): реквизиты контрагента по ИНН штатным 1С:Контрагент (чтение, без записи).
- **`get_config_fingerprint`** (6.1.0): дешёвый отпечаток состава конфигурации.

## 🆕 Что нового в v6.0.2

**59 → 91 инструмент** (+32): отчёты СКД под типовые конфигурации 1С:ERP (`run_report`, `get_report_options`…), аудит прав (`get_rights_for_user`, `export_role_matrix`), пользовательские настройки (`set_constant`, `set_functional_option`, `set_user_setting`…), снимки и сравнение (`snapshot_document_state`, `compare_snapshots`, `document_chain`), бизнес-данные ЕРП (`get_stock_by_warehouse`, `get_unfulfilled_order_lines`, `get_reservation_status`). Плюс **запись ссылочных полей и перечислений** (резолв `_guid` для шапки И строк табличных частей). Полный перечень — в [CHANGELOG.md](CHANGELOG.md).

---

## 🆕 Что нового в v2.1.0

### Исправления (9 патчей)

| # | Инструмент | Баг | Исправление |
|---|-----------|-----|-------------|
| P1 | `get_list` | Отсутствие `ПЕРВЫЕ N` — возвращал ВСЕ записи | Добавлен `ПЕРВЫЕ` с параметром `limit` (по умолчанию 100) |
| P2 | `get_document_list` | Фильтр по дате — `Дата >=` без параметра | Добавлен `Запрос.УстановитьПараметр` для дат |
| P3 | `get_object_by_ref` | Пустая ссылка → невнятная ошибка платформы | Добавлена проверка `Если НЕ ЗначениеЗаполнено(Ссылка)` |
| P4 | `get_active_users` / `get_locks` | Прямой обход коллекции сеансов → ошибка на сервере | Переход на `МассивСеансов = ПолучитьСеансыИнформационнойБазы()` |
| P5 | `get_event_log` | Дата передавалась строкой + поле «Метаданные» вместо представления | `ПреобразоватьДату()` + `.МетаданныеПредставление` |
| P6 | `ПреобразоватьДату` | Не обрабатывал `2026-05-14`, `14.05.2026`, `20260514` | Полная перезапись: ISO 8601 + 3 формата |
| P7 | `fill_on_basis` | `Объект.Заполнить()` → верный метод `ЗаполнитьНаОсновании()` | Исправлен вызов метода |
| P8 | `execute_batch` | Вложенный `execute_batch` → бесконечная рекурсия | Добавлен guard-флаг `_batch_depth` |
| P9 | — | Версия оставалась 2.0.0 | Обновлена до 2.1.0 |

### Новые инструменты (10 штук, группа З)

| # | Инструмент | Назначение |
|---|-----------|------------|
| 42 | `get_balance` | Остатки и обороты регистра бухгалтерии (любой план счетов) |
| 43 | `get_register_totals` | Итоги регистров накопления (остатки/обороты) |
| 44 | `get_accounting_entries` | Бухгалтерские проводки документа (Дт, Кт, сумма) |
| 45 | `get_related_documents` | Цепочка связанных документов (ввод на основании) |
| 46 | `validate_document` | Проверка заполнения документа без проведения |
| 47 | `get_form_structure` | Структура управляемой формы (реквизиты, команды) |
| 48 | `get_rights` | Права доступа текущего пользователя к объекту |
| 49 | `find_duplicates` | Поиск дублей в справочниках по реквизитам |
| 50 | `get_print_form` | Печатные формы через подсистему УправлениеПечатью |
| 51 | `get_configuration_extensions` | Список расширений конфигурации (CFE) |

---

## 🛠 Каталог инструментов

> Ниже — базовый каталог (51 инструмент, группы А–З). В **v6.0.2** добавлены ещё 32 (отчёты/СКД, права, пользовательские настройки, снимки, бизнес-данные 1С:ERP) — полный список из **93** в `Module.bsl` и [CHANGELOG.md](CHANGELOG.md).

### Группа А — Метаданные (8)

| # | Инструмент | Описание |
|---|-----------|----------|
| 1 | `get_metadata_tree` | Дерево объектов метаданных конфигурации |
| 2 | `get_object_metadata` | Полная структура объекта (реквизиты, ТЧ, модули) |
| 3 | `get_object_attributes` | Список реквизитов объекта |
| 4 | `get_object_tabular_sections` | Табличные части объекта |
| 5 | `get_enum_values` | Значения перечисления |
| 6 | `get_register_dimensions` | Измерения, ресурсы и реквизиты регистра |
| 7 | `get_document_movements` | Движения документа по регистрам |
| 8 | `search_metadata` | Поиск по метаданным (по имени/синониму) |

### Группа Б — Чтение данных (7)

| # | Инструмент | Описание |
|---|-----------|----------|
| 9 | `execute_query` | Выполнение произвольного запроса 1С |
| 10 | `get_object_by_ref` | Получение объекта по ссылке/GUID |
| 11 | `get_list` | Список элементов справочника/документа с фильтрами |
| 12 | `find_by_code` | Поиск элемента по коду |
| 13 | `find_by_name` | Поиск элемента по наименованию |
| 14 | `get_register_records` | Записи регистра с фильтрами |
| 15 | `get_document_list` | Список документов с фильтрами по дате/номеру |

### Группа В — CRUD (7)

| # | Инструмент | Описание |
|---|-----------|----------|
| 16 | `create_object` | Создание нового объекта (справочник/документ) |
| 17 | `update_object` | Изменение реквизитов объекта |
| 18 | `delete_object` | Пометка на удаление |
| 19 | `post_document` | Проведение документа |
| 20 | `unpost_document` | Отмена проведения |
| 21 | `copy_object` | Копирование объекта |
| 22 | `set_attribute` | Изменение отдельного реквизита |

### Группа Г — Код и отчёты (4)

| # | Инструмент | Описание |
|---|-----------|----------|
| 23 | `execute_code` | Выполнение произвольного кода на встроенном языке |
| 24 | `evaluate_expression` | Вычисление выражения и возврат результата |
| 25 | `get_module_text` | Получение текста модуля объекта |
| 26 | `generate_report` | Формирование отчёта (СКД) |

### Группа Д — Администрирование (6)

| # | Инструмент | Описание |
|---|-----------|----------|
| 27 | `get_active_users` | Список активных пользователей и сеансов |
| 28 | `get_event_log` | Журнал регистрации с фильтрами |
| 29 | `get_locks` | Текущие блокировки данных |
| 30 | `get_server_info` | Информация о платформе, конфигурации, сервере |
| 31 | `check_references` | Проверка ссылочной целостности |
| 32 | `run_scheduled_job` | Запуск регламентного задания |

### Группа Е — Интеграция (3)

| # | Инструмент | Описание |
|---|-----------|----------|
| 33 | `exchange_execute` | Выполнение обмена данными |
| 34 | `get_exchange_log` | Журнал обмена |
| 35 | `import_data` | Импорт данных из JSON |

### Группа Ж — Расширенные операции v2.0 (6)

| # | Инструмент | Описание |
|---|-----------|----------|
| 36 | `fill_on_basis` | Заполнение документа на основании другого |
| 37 | `write_register_records` | Запись набора записей регистра |
| 38 | `update_tabular_section` | Обновление табличной части объекта |
| 39 | `subscribe_events` | Подписка на события журнала |
| 40 | `execute_batch` | Пакетное выполнение инструментов |
| 41 | `get_changes_since` | Получение изменений с метки времени (CDC) |

### Группа З — Бухгалтерия, аудит, формы v2.1 (10) 🆕

| # | Инструмент | Описание |
|---|-----------|----------|
| 42 | `get_balance` | Остатки/обороты регистра бухгалтерии |
| 43 | `get_register_totals` | Итоги регистров накопления |
| 44 | `get_accounting_entries` | Проводки документа (Дт/Кт/Сумма) |
| 45 | `get_related_documents` | Связанные документы (цепочка оснований) |
| 46 | `validate_document` | Проверка заполнения без проведения |
| 47 | `get_form_structure` | Структура управляемой формы |
| 48 | `get_rights` | Права доступа текущего пользователя |
| 49 | `find_duplicates` | Поиск дублей по реквизитам |
| 50 | `get_print_form` | Печатные формы через УправлениеПечатью |
| 51 | `get_configuration_extensions` | Список расширений конфигурации (CFE) |

---

## 🚀 Быстрый старт

### Вариант 1: Через Claude Desktop / Cursor (stdio)

#### Способ А — через npx (без клонирования)

```json
{
  "mcpServers": {
    "1c-erp": {
      "command": "npx",
      "args": ["infaton-mcp"],
      "env": {
        "ONEC_URL": "https://your-server/base/hs/mcp/",
        "ONEC_USER": "Username",
        "ONEC_PASSWORD": "Password"
      }
    }
  }
}
```

#### Способ Б — из клонированного репозитория

```json
{
  "mcpServers": {
    "1c-erp": {
      "command": "node",
      "args": ["/path/to/MCP35/index.mjs"],
      "env": {
        "ONEC_URL": "https://your-server/base/hs/mcp/",
        "ONEC_USER": "Username",
        "ONEC_PASSWORD": "Password"
      }
    }
  }
}
```

### Вариант 2: Прямой HTTP-вызов

#### 1. Установите расширение

1. Откройте **Конфигуратор** базы 1С
2. **Конфигурация → Расширения конфигурации → Добавить**
3. Выберите файл `INFATON_MCP.cfe` (или соберите по [инструкции](HOW_TO_BUILD_CFE.md) из `Module.bsl`)
4. Обновите конфигурацию БД (**F7**)

#### 2. Проверьте подключение

```bash
curl -u 'Логин:Пароль' -X POST \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1}' \
  https://ваш-сервер/база/hs/mcp/
```

Ожидаемый ответ:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "infaton-1c-mcp", "version": "6.2.1" }
  }
}
```

#### 3. Вызовите инструмент

```bash
curl -u 'Логин:Пароль' -X POST \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"get_balance","arguments":{"account_code":"41.01","period_from":"2026-01-01T00:00:00","period_to":"2026-03-31T23:59:59"}}}' \
  https://ваш-сервер/база/hs/mcp/
```

---

## 📐 Архитектура

```
┌─────────────────────────┐
│   AI Assistant          │  Claude / GPT / Qwen / Gemini / ...
│   (MCP Client)          │
└────────┬────────────────┘
         │ stdio (JSON-RPC 2.0)
         ▼
┌─────────────────────────┐
│   index.mjs             │  Node.js stdio → HTTP proxy
│   (MCP Transport)       │
└────────┬────────────────┘
         │ HTTP POST (Basic Auth)
         ▼
┌─────────────────────────┐
│   HTTP-сервис /hs/mcp/  │  Расширение INFATON_MCP.cfe
│   Module.bsl            │  93 инструмента (7 350 строк)
│   (MCP Server)          │
└────────┬────────────────┘
         │ Встроенный язык 1С
         ▼
┌─────────────────────────┐
│   База 1С:Предприятие   │  ERP / УПП / Бухгалтерия / УТ / КА
│   Данные, метаданные    │
└─────────────────────────┘
```

---

## 📝 Совместимость

| Параметр | Значение |
|----------|----------|
| Платформа 1С | 8.3.20+ (тестировалось на 8.3.27.1989) |
| Конфигурации | ERP 2.5, УПП 1.3, Бухгалтерия 3.0, УТ 11, КА 2 |
| MCP Протокол | 2024-11-05 |
| Транспорт | HTTP (Basic Auth), stdio (через index.mjs) |
| Node.js | 18+ (для stdio-обёртки) |

---

## 📊 История версий

| Версия | Дата | Инструментов | Изменения |
|--------|------|:---:|-----------|
| **v2.1.0** | 2026-05-14 | **51** | +10 инструментов (бухгалтерия, аудит, формы), 9 багфиксов |
| v2.0.0 | 2026-05-08 | 41 | +6 инструментов (batch, CDC, fill_on_basis и др.) |
| v1.0.0 | 2026-04-28 | 35 | Первый публичный релиз |

---

## 🔒 Безопасность

### Обязательно для продакшена

| Требование | Почему важно |
|------------|-------------|
| **HTTPS** | Basic Auth передаёт логин/пароль в base64. По HTTP они видны любому в сети |
| **Отдельный пользователь 1С** | Создайте пользователя `mcp_agent` с минимальными правами — только нужные объекты |
| **`ONEC_ALLOWED_TOOLS`** | Ограничьте список инструментов для конкретного сценария |

### Опасные инструменты

Следующие инструменты требуют явного разрешения и должны использоваться осознанно:

| Инструмент | Риск | Рекомендация |
|-----------|------|-------------|
| `execute_code` | Выполняет произвольный BSL-код в привилегированном режиме | Запрещать через `ONEC_ALLOWED_TOOLS` если не нужен |
| `delete_object` | Помечает объекты на удаление | Запрещать в аналитических сценариях |
| `run_scheduled_job` | Запускает регламентные задания | Запрещать если не нужен |
| `import_data` | Массовое создание/изменение объектов | Запрещать в read-only сценариях |
| `post_document` / `unpost_document` | Изменяет проведение документов и движения по регистрам | Только для операционных сценариев |

### Конфигурация только для чтения

```bash
ONEC_ALLOWED_TOOLS="get_metadata_tree,execute_query,get_object_by_ref,get_list,find_by_code,find_by_name,get_register_records,get_document_list,get_server_info,get_event_log,get_balance,get_register_totals,get_accounting_entries,get_related_documents,get_form_structure,get_rights,find_duplicates"
```

Подробнее — см. [EXAMPLES.md](EXAMPLES.md#конфигурация-только-для-чтения-безопасная).

---

## 📄 Лицензия

MIT © 2024-2026 [INFATON](https://infaton.ru) — Привалов С.Ю.

Платформа: **[infaton.ru](https://infaton.ru)** · Продукт: **[chatmcp.ru](https://chatmcp.ru)** (ChatMCP).

---

*Подробная инструкция по сборке `.cfe` — см. [HOW_TO_BUILD_CFE.md](HOW_TO_BUILD_CFE.md)*

*Примеры агентских сценариев — см. [EXAMPLES.md](EXAMPLES.md)*

*История изменений — см. [CHANGELOG.md](CHANGELOG.md)*

---

## 📰 Публикация на Инфостарт

[![Infostart](https://infostart.ru/bitrix/templates/sandbox_empty/assets/tpl/abo/img/logo.svg)](https://infostart.ru/1c/articles/2712602/)

Статья на портале **Инфостарт**: [INFATON MCP Server v2.1 — 51 инструмент для AI-интеграции с 1С:Предприятие](https://infostart.ru/1c/articles/2712602/)