MCP данных: подключение, наборы, методы и выгрузки

Зачем это нужно

MCP предоставляет совместимому агенту именованные инструменты и схемы запросов. Вы задаёте вопрос, агент выбирает метод и параметры. Разработчик использует тот же контракт без прямого доступа к базе или ключу Wildberries.

Пример из работы магазина

Как начать

1. Подключите магазин и WB-ключ чтения нужных категорий в кабинете.
2. Выполните инструкцию подключения агента в папке проекта магазина.
3. Передайте X-MP-ключ через защищённый файл или скрытый ввод установщика.
4. В новой сессии проверьте agent.me, capabilities.list, readiness.get и datasets.list.

Что вы получите

Ограниченные ответы по выбранным данным, происхождение и проверенные приватные файлы для больших объёмов.

Что важно учитывать

Методы зависят от клиента и прав. Справочник сверён с клиентом 0.32.0 на 08.09.2026; tools/list вашей сессии определяет доступный контракт. Сохранённый источник может содержать неполный или ошибочный ответ.

Устройство подключения

WB-ключ разрешает серверу читать категории маркетплейса. X-MP-ключ разрешает агенту пользоваться конкретным магазином. Шлюз не выдаёт агенту WB-ключ, доступ к базе или объектному хранилищу.

Подключение по шагам

1. Выберите магазин в кабинете. В защищённых подключениях сохраните WB-ключ чтения категорий, нужных для задачи.
2. Откройте подключение агента и выдайте нужные права: analytics.read для аналитики; operations.read/operations.plan отдельно для рабочих блоков.
3. Поддержанный установщик Codex требует curl, python3 и codex в PATH. Запустите команду кабинета в папке, из которой будете работать.
4. Установщик скачивает пакет, проверяет совместимость и хеши, создаёт .xmp и привязку MCP. ID магазина в команде проверяет ожидаемое подключение, не даёт права выбирать чужой scope.
5. Ключ вводится скрыто или через --credential-file. Файл должен принадлежать текущему пользователю, быть обычным приватным файлом с правами 0600.
6. Начните новую сессию в подключённой папке; проверьте магазин, права и наборы.

В проекте: .xmp/current/bin/xmp_agent_mcp.py — клиент; .xmp/secrets/agent.key — секрет; .codex/config.toml — настройки MCP. Не копируйте ключи между магазинами. Для другого клиента требуется совместимый способ подключения из инструкции, а не произвольное использование настроек Codex.

xmp.update.check проверяет выпуск; xmp.update.apply с confirm=true применяет проверенное обновление. Автообновление зависит от настроенной политики устройства. Обновление не добавляет прав. Если метода нет в tools/list, проверьте версию, совместимость и доступ.

Команда установки и локальная структура

Предпочтительно копировать индивидуальную команду из своего кабинета. Ниже — техническая форма того же установщика для подготовленного окружения. UUID и путь учебные: замените их на ID вашего кабинета и существующий приватный файл ключа. Значение ключа в командной строке отсутствует.

curl --fail --silent --show-error https://x-mp.ru/cabinet/static/install-xmp-codex.sh --output ./install-xmp-codex.sh
bash ./install-xmp-codex.sh "00000000-0000-0000-0000-000000000001" --credential-file "/private/xmp-agent.key" --no-launch

Если работа ведётся через другого совместимого клиента, используйте его проверенную инструкцию подключения. Этот shell-установщик предназначен для Codex и не является универсальным установщиком всех MCP-клиентов.

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

{}

{}

{}

{}

Сверьте магазин, эффективные права, свежесть и доступные dataset_key. degraded по свежести не всегда запрещает чтение: разрешённые старые данные можно использовать с явной датой. Для нового плана изменения действуют более строгие требования.

Для исходных сохранённых данных нужен analytics.read на шлюзе и серверный grant stored_data. Недостающие права не исправляются передачей account_id, SQL или пути хранилища.

Агрегат, строки или файл

dataset.export — нормализованный набор; collection.artifact.download — один сохранённый артефакт. Это разные продукты, а не два названия произвольного доступа к базе.

Наборы и разрешённые поля dataset.query

Доступные dataset_key сначала читаются через datasets.list. Страничная проекция реализована для products, orders, sales. Другие источники ищите через collection.sources, не подставляйте произвольную entity как dataset_key.

fields — до 16 уникальных разрешённых полей, nm_ids — до 20 строковых артикулов, limit — до 50 строк, offset — до 10000. Для периода нужны обе границы, максимум 90 дней. У products даты относятся к observed_at, у orders/sales — к event_at.

{
  "dataset_key": "orders",
  "fields": [
    "nm_id",
    "vendor_code",
    "discounted_price",
    "is_cancel",
    "event_at",
    "raw_run_id"
  ],
  "date_from": "2026-09-01",
  "date_to": "2026-09-07",
  "limit": 10,
  "offset": 0
}

raw_run_id показывает происхождение, а не включает весь payload в строку. Не складывайте разные ценовые поля как независимые доходы. Идентификаторы источника не доказывают уникального покупателя.

Источники и сохранённые версии

{
  "limit": 20,
  "offset": 0
}

1. Пройдите next_offset каталога. В нём бывают пустые и ошибочные источники.
2. Из record_sets возьмите entity и kind: entity, fact либо product. Не угадывайте значения.
3. Вызовите collection.records с полями и лимитом. Для истории задайте current_only=false.
4. Продолжайте next_after. Даты фильтруют observed_at, не дату продажи.
5. Если payload_omitted сообщает о большом содержимом, переходите к raw_run_id и артефакту.

До 50 записей и 20 полей за страницу. Фильтр записей/файлов — до 366 дней за запрос; без дат доступны сохранённые даты с пагинацией. Сортировка UUID стабильна для неизменного набора, но не создаёт транзакционный снимок при параллельном сборе.

История сбора и ошибки доступа

{
  "date_from": "2026-09-01",
  "date_to": "2026-09-07"
}

{
  "limit": 20,
  "offset": 0
}

История показывает дни/разделы, частичные и неудачные загрузки; диапазон до 31 дня. Диагностика читает последнее сохранённое свидетельство и documented_requirements, не вызывает новый запрос WB.

403 сам по себе не доказывает отсутствие подписки или конкретной категории ключа. Причину и документированные требования проверяют отдельно. Успешный ответ также не доказывает, что собраны все страницы и даты.

Файлы, лимиты и проверка выгрузки

{
  "kind": "raw",
  "date_from": "2026-09-01",
  "date_to": "2026-09-07",
  "limit": 10
}

{
  "artifact_id": "00000000-0000-0000-0000-000000000001",
  "kind": "raw",
  "max_bytes": 10485760
}

UUID учебный: замените реальным ID из каталога. Скачивание по умолчанию до 10MiB, явно — до 128MiB. Части до 256KiB проверяются по размеру, непрерывности, scope и SHA-256; весь файл сохраняется атомарно в .xmp/data с приватными правами. Ответ содержит путь и метаданные.

ZIP не распаковывается; base64-документ внутри JSON не декодируется автоматически. Сначала проверьте формат, затем обрабатывайте локально с сохранением происхождения. Ошибочный ответ WB тоже может быть артефактом.

{
  "dataset_key": "orders",
  "max_rows": 10000,
  "max_bytes": 10485760
}

Экспорт сохраняет JSONL и manifest. До 100000 строк и 50MiB; по умолчанию 10000 строк и 10MiB. У export нет фильтров fields, nm_ids и периода: не переносите параметры query. complete описывает завершённость выдачи, а не полноту сбора.

Вызов MCP и чтение ответа

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "analysis.query",
    "arguments": {
      "date_from": "2026-09-01",
      "date_to": "2026-09-07",
      "metrics": [
        "ordered_gmv",
        "ad_spend"
      ],
      "sort_by": "ordered_gmv",
      "limit": 10
    }
  }
}

Обычно конверт формирует клиент агента. tools/list сообщает имена и inputSchema; arguments обязан соответствовать схеме. Методы без параметров получают {}. Секрет и выбор магазина в arguments не передаются. Формат результата различается по методам.

readOnlyHint — подсказка протокола, не вся модель эффектов. Скачивание пишет локальный файл, расчёт сохраняет историю, reconcile записывает проверку без повторной отправки цены. Сервер дополнительно проверяет права и сочетания параметров.

Неполные ответы и восстановление

Методы и параметры

Параметры ниже относятся к MCP arguments. Идентичность и ключ не передаются в них. Для полного объекта config следуйте руководству домена.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "skills": {
      "type": "array",
      "minItems": 1,
      "maxItems": 3,
      "uniqueItems": true,
      "items": {
        "type": "string"
      }
    }
  }
}

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "confirm"
  ],
  "properties": {
    "confirm": {
      "const": true
    },
    "auto_update": {
      "type": "boolean"
    }
  }
}

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "dataset_key"
  ],
  "properties": {
    "dataset_key": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_-]{1,127}$"
    },
    "fields": {
      "type": "array",
      "minItems": 1,
      "maxItems": 16,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_]*$"
      }
    },
    "nm_ids": {
      "type": "array",
      "maxItems": 20,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "pattern": "^[0-9]{1,19}$"
      }
    },
    "date_from": {
      "type": "string",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "format": "date"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000,
      "default": 0
    }
  }
}

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "dataset_key"
  ],
  "properties": {
    "dataset_key": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_-]{1,127}$"
    },
    "max_rows": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100000,
      "default": 10000
    },
    "max_bytes": {
      "type": "integer",
      "minimum": 1024,
      "maximum": 52428800,
      "default": 10485760
    }
  }
}

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    }
  },
  "required": []
}

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "date_from": {
      "type": "string",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "format": "date"
    }
  },
  "required": [
    "date_from",
    "date_to"
  ]
}

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    }
  },
  "required": []
}

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "entity": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_.-]{1,128}$"
    },
    "kind": {
      "type": "string",
      "enum": [
        "entity",
        "fact",
        "product"
      ]
    },
    "current_only": {
      "type": "boolean",
      "default": true
    },
    "after": {
      "type": "string",
      "format": "uuid"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 20
    },
    "date_from": {
      "type": "string",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "format": "date"
    }
  },
  "required": [
    "entity"
  ]
}

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "raw",
        "business"
      ]
    },
    "entity": {
      "type": "string"
    },
    "method_id": {
      "type": "string"
    },
    "date_from": {
      "type": "string",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "format": "date"
    },
    "after": {
      "type": "string",
      "format": "uuid"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": []
}

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "artifact_id": {
      "type": "string",
      "format": "uuid"
    },
    "kind": {
      "type": "string",
      "enum": [
        "raw",
        "business"
      ],
      "default": "raw"
    },
    "max_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 134217728,
      "default": 10485760
    }
  },
  "required": [
    "artifact_id"
  ]
}

Связанные возможности

MCP для AI-агента

Поручать работу с WB своему AI-помощнику

Доступно. Выберите доступный способ подключения в инструкции.

Сбор данных магазина

Анализировать магазин без ручных выгрузок

Доступно по источникам. Состав и свежесть зависят от прав доступа и загруженного периода.