Mcp 1c

---
name: mcp-1c
description: "Используй, когда задача требует обратиться к базе 1С через MCP-сервер: исследовать метаданные, проверить или выполнить запрос, запустить код на сервере, прочитать или изменить конкретную настройку в стандартном хранилище платформы либо исследовать журнал регистрации. Здесь же порядок работы с инструментами сервера 1c_mcp, его проверенные ловушки и подключение новой базы к проекту."
---

# Работа с базой через MCP-сервер

Полная схема параметров и допустимых значений каждого инструмента приходит вместе с самим
инструментом — не копируй её отсюда. Нормы (что обязательно до кода, что нельзя без разрешения
пользователя) — в `.claude/rules/mcp.md`. Здесь — порядок работы, смысл параметров и поведение,
которых недостаточно видно из схемы.

## Порядок работы с данными базы

1. `list_metadata_objects` — найти объект, если точное имя неизвестно (маска ищет и в синониме).
2. `get_metadata_structure` — взять реальные имена и типы реквизитов, ТЧ, значения перечислений.
3. Написать запрос по полученным именам.
4. `validate_query` — проверить синтаксис и существование таблиц.
5. `execute_query` — выполнить (значения подставляй в текст: параметры запроса не поддерживаются).

Для журнала: сначала `eventlog_filter_values` (точные внутренние имена событий и пользователей),
потом `eventlog_query` — угаданное имя даёт пустую выборку, а не ошибку.

## Порядок работы с хранилищами настроек платформы

Этот раздел применяй только если задача прямо требует прочитать или изменить конкретную настройку.
Например, «покажи значение настройки X» или «измени настройку X для пользователя Y». Для обычной
разработки, а также из-за упоминания пароля, токена или учётных данных эти инструменты не вызывай.

`storage_reader` и `set_storage_value` работают со стандартными хранилищами платформы:

- `CommonSettings` — хранилище общих настроек;
- `SystemSettings` — хранилище системных настроек;
- `FormDataSettings` — хранилище настроек данных форм.

Они не читают и не изменяют БСП «Безопасное хранилище паролей».

Это не объекты метаданных типа `ХранилищеНастроек`: найденное через `list_metadata_objects`
прикладное хранилище нельзя передать как `storageType`.

Платформа не позволяет перечислить разделы хранилища. `objectName` (ключ объекта, то есть раздел)
нужно знать из задачи или найти в коде. Если раздел известен, а ключ настройки нет — сначала вызови
`storage_reader` с действием `get_list`, затем читай описание или значение нужного ключа. Вложенное
свойство и страницу табличного значения выбирай параметрами из схемы инструмента.

Если настройка зависит от пользователя, укажи `userName` осознанно: без него сервер работает от
имени текущего пользователя своего сеанса.

Отсутствие даты изменения и признака сжатия в результате `get_description` не является ошибкой:
стандартные хранилища платформы эти сведения не предоставляют. Правила подтверждения записи через
`set_storage_value` — в `.claude/rules/mcp.md`.

## Поведение сервера (проверено на демо-базе БСП)

- `metaType` — по-английски (`Catalogs`), `name` — как в конфигурации, обычно по-русски
  (`_ДемоКонтрагенты`). `Catalogs` + `Users` даёт «объект метаданных не найден».
- Метаданные отдаются **с учётом применённых расширений**: объекты и реквизиты из расширений видны
  наравне с основной конфигурацией. Чего MCP не даёт — тексты модулей, формы, внешние обработки:
  за ними иди по приоритету источников из `.claude/rules/mcp.md` (индекс исходников, затем исходники проекта).
- Ссылочные поля в результате запроса приходят представлением (`"Контрагент": "ООО \"Альфа\""`),
  а не GUID — для идентификации объекта запрашивай код, номер или используй `ЗНАЧЕНИЕ()`.
- Изредка (порядка одного вызова из полутора десятков) сервер отвечает ошибкой
  `Тип не определен '<guid>'` на запросе, который до и после этого отрабатывает штатно. Причина не
  установлена. Получив её — просто повтори вызов, не переписывай запрос.
- `execute_code` возвращает результат через предопределённую переменную `__Возврат`; если её не
  заполнить, результата не будет.
- Для отсутствующего ключа `storage_reader` не обязательно возвращает ошибку инструмента:
  `get_description` сообщает `exists: false`, а `get_value` — тип `Undefined`. Проверяй содержимое
  ответа, а не только признак успешного вызова MCP.

## Ресурс сервера

`file://resource/syntax_1c.txt` — краткая шпаргалка по синтаксису встроенного языка. Полезна для
базового синтаксиса; методы платформы и БСП по ней не проверить.

## Подключение

Сервер даёт расширение [1c_mcp](https://github.com/vladimir-kharin/1c_mcp): оно устанавливается
в базу и реализует протокол MCP как HTTP-сервис, база публикуется на веб-сервере — локальном
(`localhost`) или общем. Адрес сервиса: `http://<адрес сервера>/<имя публикации>/hs/mcp/`.

Сервера прописываются в `.mcp.json` в корне проекта (образец — `.mcp.json.example`). Одна папка проекта — не обязательно одна база: рядом с основной подключают тестовую копию, базу клиента, базу смежной системы для интеграционной задачи.

**Имя сервера выбирает пользователь, и по нему должно читаться, что за база.** Оно попадает в имя каждого инструмента (`mcp__<имя сервера>__<инструмент>`), и при нескольких базах это единственное, чем они различаются в списке. Хорошее имя называет конфигурацию и контур:

```json
{
  "mcpServers": {
    "ut-test": {
      "type": "http",
      "url": "http://localhost/ut_test/hs/mcp/"
    },
    "ut-prod": {
      "type": "http",
      "url": "http://server/ut/hs/mcp/"
    }
  }
}
```

Каждую добавленную базу занеси строкой в секцию «Подключённые базы (MCP)» файла `CLAUDE.md` — правила выбирают базу по ней. Не занесённая база для агента рабочая: писать в неё он не станет. Со второй базы пометь одну строку как базу по умолчанию, иначе агент будет переспрашивать при каждой задаче, где база не названа.

Если публикация закрыта Basic-авторизацией — заголовок с учётными данными из переменной окружения
(Claude Code разворачивает `${VAR}` в `.mcp.json`), а не в открытом виде в файле:

```json
"headers": { "Authorization": "Basic ${ONEC_MCP_BASIC}" }
```

Сервер из `.mcp.json` требует подтверждения при первом запуске; статус — командой `/mcp`.
Инструменты становятся доступны только при старте сессии: если сервер добавлен во время работы,
подключится он лишь после перезапуска Claude Code.