datalens-dev-mcp

Русский · English

Документация автономного workflow: контракт и выполнение,
Project Journal, реестр портфельных стилей,
typed data validation, уровни evidence и
миграция с legacy surface.

Быстрый старт · Доступ к DataLens · Подключение · Инструменты · Интерактивный JS Cookbook · Сценарии · Источники · Безопасность · English

datalens-dev-mcp — локальный MCP-сервер, который подключает Codex, Claude и другие MCP-клиенты к Yandex DataLens. Пользователь описывает задачу в клиенте обычным языком, клиент вызывает типизированные инструменты сервера, а сервер читает актуальные объекты через DataLens Public API, проверяет зависимости и схемы запросов, готовит изменения, сохраняет их и при необходимости публикует с контрольным чтением результата.

Это не отдельный интерфейс DataLens и не самостоятельный AI-ассистент. Проект даёт MCP-клиенту управляемый локальный доступ к операциям разработки DataLens и работает только с правами текущего пользователя.

Что это даёт

После подключения можно:

• найти нужный воркбук, дашборд, чарт, датасет или подключение;
• разобраться в структуре дашборда, его объектах и зависимостях;
• получить локальный снимок связанного графа и провести аудит без изменений;
• подготовить план, создать объект или точечно изменить существующий;
• сохранить черновик либо сохранить и опубликовать проверенную версию;
• получить saved/published readback, отчёты и пути к локальным артефактам.

Например:

Исправь чарт <CHART_ID> в воркбуке <WORKBOOK_ID>: <ТРЕБОВАНИЕ>. Сохрани и опубликуй результат, затем проверь сохранённую и опубликованную версии.

Перейти к быстрому старту

Сервер работает локально через stdio, не открывает входящий HTTP-порт и не использует отдельный облачный посредник. Это независимый Alpha-проект, не относящийся к официальным продуктам Yandex или Yandex Cloud.

Как это работает

Пользователь
  -> Codex / Claude / другой MCP-клиент
  -> локальный datalens-dev-mcp
  -> Yandex DataLens Public API

project root
  <- снимки, планы, проверки, readback и отчёты

Пользователь формулирует цель, а MCP-клиент выбирает и вызывает подходящие инструменты. Сервер применяет проверки, обращается к DataLens API и сохраняет локальные артефакты внутри выбранного project root. Клиент показывает результат пользователю и, если у него доступен браузер, может дополнительно проверить отображение в интерфейсе DataLens.

Возможности

Открыть интерактивный JavaScript Visualization Cookbook →

В нём собраны стартовые Tips, 34 готовые JavaScript-визуализации, три связанных
прикладных кейса, контракты источников и полный набор вкладок для копирования.
Markdown-каталог и исходники доступны прямо в репозитории.

Что делает сервер, а что остаётся за MCP-клиентом

У сервера нет собственной языковой модели, чата или пользовательского веб-интерфейса. Он не заменяет DataLens UI и не гарантирует визуальное качество без отдельной проверки отображения.

Чем это отличается от разрозненных вызовов DataLens API

• MCP-клиент использует типизированные операции вместо самостоятельной сборки произвольных HTTP-запросов.
• Изменение строится поверх актуальной сохранённой версии объекта.
• Перед записью проверяются точная цель, ревизия и payload.
• Неизвестные и нетронутые поля сохраняются, а изменяется только объявленная область.
• Save и publish разделены и подтверждаются отдельными контрольными чтениями.
• Связанные действия можно применить как одну проверяемую группу, а планы и результаты остаются локальными артефактами.

Такой процесс снижает риск записи не в тот объект, потери полей и публикации непроверенной версии. При конфликте или неопределённом результате цикл останавливается вместо скрытого повтора записи.

Примеры задач

Проверка подключения

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

Для этого клиент использует dl_runtime_status, а затем минимальную реальную проверку dl_auth_probe.

Аудит без записи

Проведи аудит дашборда <DASHBOARD_ID> в воркбуке <WORKBOOK_ID>. Покажи структуру, связанные объекты, зависимости и основные риски. Ничего не сохраняй и не публикуй.

План без применения

Составь план изменения чарта <CHART_ID>: <ТРЕБОВАНИЕ>. Покажи, какие поля и объекты будут затронуты, но ничего не сохраняй.

Сохранение без публикации

Обнови <ТИП ОБЪЕКТА> <OBJECT_ID>: <ТРЕБОВАНИЕ>. Сохрани изменение и проверь saved-версию, но не публикуй.

Обычное изменение

Исправь чарт <CHART_ID> в воркбуке <WORKBOOK_ID>: <ТРЕБОВАНИЕ>. Сохрани и опубликуй результат, затем проверь сохранённую и опубликованную версии.

Создание объекта

Создай <ТИП ОБЪЕКТА> в воркбуке <WORKBOOK_ID> по следующим требованиям: <ТРЕБОВАНИЯ>. Проверь зависимости и данные запроса, затем сохрани и опубликуй результат.

HTML-страница

Создай self-contained HTML-страницу в воркбуке <WORKBOOK_ID>: <ТРЕБОВАНИЕ>. Проверь sandbox-контракт, сохрани, прочитай saved-версию, опубликуй её по revId и проверь published-версию.

Как выглядит результат

Ниже — схема ответа, а не точный JSON-контракт:

Результат
- целевой объект найден
- изменение проверено
- сохранённая версия прочитана и совпала с планом
- опубликованная версия прочитана
- создан отчёт
- пути к локальным артефактам возвращены
- проверка интерфейса выполнена либо явно отмечена как недоступная

Если операция остановлена, пользователь получает причину и следующий безопасный шаг: например, повторно прочитать объект после конфликта ревизии или проверить DataLens вручную после неопределённого результата.

Режимы работы

Формулировка задачи определяет точку остановки; изучать названия всех инструментов для выбора режима не требуется.

Явное значение 0 в write/save/publish env-переменной жёстко отключает соответствующую возможность и имеет приоритет над запросом. Обычный цикл не удаляет целые объекты; отдельное подтверждение применяется только к объявленному в project manifest действию retire_legacy_objects с точными ID и неизменившимся планом.

Поддерживаемые объекты и ограничения

Поддерживается

• просмотр доступных воркбуков и их содержимого;
• чтение связей, дашбордов, Wizard/Editor/QL-чартов, датасетов и подключений;
• создание и обновление поддерживаемых дашбордов, чартов, HTML-страниц, датасетов и подключений через plan и Safe Apply;
• точечное изменение вкладки дашборда и защищённое изменение модели датасета;
• локальный снимок дашборда и его графа зависимостей;
• локальная генерация self-contained HTML artifacts, проверка sandbox-контракта и guarded lifecycle HTML Pages через Public API;
• заранее объявленные dry-run/apply процессы через project manifest;
• сохранение планов, снимков, readback и отчётов внутри project root.

Wizard, Editor и QL

• Новые стандартные KPI, таблицы, линии, области, столбцы, комбинированные чарты, круговые диаграммы, scatter/bubble, treemap, воронки и карты по умолчанию используют Wizard.
• При обновлении существующего чарта сохраняются его технология и visualization_id.
• Editor выбирается по прямому запросу на JavaScript либо при документированном недостатке Wizard.
• QL используется только по прямому запросу и с явным payload или актуальной QL-версией; он не выбирается автоматически и не служит fallback.
• Create и full redesign автоматически используют standard_dashboard:
  role-based заголовки, dashboard composition, защищённый Editor runtime и финальная
  payload/QA attestation; автономная поверхность оставляет lifecycle-вызовы внутри сервера.

Подробная политика: docs/route-policy.md.

Ограничения

• Сервер не является hosted service, чат-ботом или пользовательским интерфейсом DataLens.
• Он не предоставляет права сверх прав текущего пользователя.
• Произвольное удаление целого объекта, включая целый QL-объект, недоступно.
• Перемещение объектов, изменение прав доступа, лицензий и учётных данных не поддерживаются.
• Локальный HTML-генератор сам не выполняет live-запись; создание и обновление HTML Pages идут отдельным guarded lifecycle, а whole-object delete остаётся недоступным.
• dl_diagnose анализирует переданные данные, но не выполняет самостоятельные запросы к базам данных.
• API-readback подтверждает структуру объекта; визуальная проверка зависит от браузера и возможностей MCP-клиента.
• Snapshot покрывает граф зависимостей выбранного дашборда, а не гарантированно всю организацию.
• Метод может присутствовать в API-каталоге, но оставаться неподдерживаемым для записи.

Проект не заявляет поддержку DataLens целиком и не заменяет ручную проверку важных изменений.

Быстрый старт

Требования: Python 3.11+, локальный stdio MCP-клиент и, для live-доступа, ID организации, IAM-токен и права на целевой воркбук.

git clone https://github.com/ADIKANT/datalens-dev-mcp.git
cd datalens-dev-mcp
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install .
.venv/bin/datalens-dev-mcp --version
python3 scripts/smoke_mcp_stdio.py

В Windows используйте .venv\Scripts\python.exe и .venv\Scripts\datalens-dev-mcp.exe. Для разработки сервера установите .venv/bin/python -m pip install -e '.[test]'.

Настройте доступ по пошаговой инструкции. Минимальный защищённый env-файл:

DATALENS_ORG_ID=<ID_ОРГАНИЗАЦИИ>
DATALENS_IAM_TOKEN=<IAM_ТОКЕН>
DATALENS_API_BASE_URL=https://api.datalens.tech
DATALENS_MCP_ENABLE_WRITES=1
DATALENS_MCP_LIVE_ALLOW_SAVE=1
DATALENS_MCP_LIVE_ALLOW_PUBLISH=1
DATALENS_ENABLE_TOKEN_REFRESH_ON_401=1
DATALENS_MCP_ENABLE_EXPERT_RPC=0

Храните файл вне репозитория с правами 0600 и передайте его абсолютный путь через DATALENS_ENV_FILE. При настроенном yc сервер может получить начальный IAM-токен и один раз обновить истёкший токен.

Подключение MCP-клиента

Замените /absolute/path/... абсолютными путями. --project-root задаёт локальную папку для входных файлов и артефактов; ID объектов DataLens указываются отдельно в задаче.

Codex

Добавьте в ~/.codex/config.toml или .codex/config.toml доверенного проекта:

[mcp_servers.datalens_dev]
command = "/absolute/path/to/datalens-dev-mcp/.venv/bin/datalens-dev-mcp"
args = ["stdio", "--project-root", "/absolute/path/to/your/dashboard-project"]
cwd = "/absolute/path/to/your/dashboard-project"
env = { DATALENS_ENV_FILE = "/absolute/path/to/home/.config/datalens-dev-mcp/env" }
default_tools_approval_mode = "approve"
startup_timeout_sec = 20
tool_timeout_sec = 120

Или зарегистрируйте ту же команду через CLI:

codex mcp add datalens_dev \
  --env DATALENS_ENV_FILE=/absolute/path/to/home/.config/datalens-dev-mcp/env \
  -- /absolute/path/to/datalens-dev-mcp/.venv/bin/datalens-dev-mcp \
  stdio --project-root /absolute/path/to/your/dashboard-project

Проверьте codex mcp list, перезапустите Codex и откройте /mcp. Подробности: настройка Codex.

Claude Code

claude mcp add --transport stdio --scope local \
  --env DATALENS_ENV_FILE=/absolute/path/to/home/.config/datalens-dev-mcp/env \
  datalens-dev -- \
  /absolute/path/to/datalens-dev-mcp/.venv/bin/datalens-dev-mcp \
  stdio --project-root /absolute/path/to/your/dashboard-project

Проверьте регистрацию командой claude mcp list.

Claude Desktop и другие stdio-клиенты

{
  "mcpServers": {
    "datalens-dev": {
      "command": "/absolute/path/to/datalens-dev-mcp/.venv/bin/datalens-dev-mcp",
      "args": ["stdio", "--project-root", "/absolute/path/to/your/dashboard-project"],
      "env": {
        "DATALENS_ENV_FILE": "/absolute/path/to/home/.config/datalens-dev-mcp/env"
      }
    }
  }
}

Готовые конфигурации: examples/clients/.

Первая сессия

Начните с read-only проверки:

Используй DataLens MCP. Вызови dl_runtime_status, затем dl_auth_probe. Покажи, доступны ли чтение, сохранение и публикация. Ничего не изменяй и не выводи учётные данные.

dl_runtime_status проверяет локальную конфигурацию и жёсткие выключатели. dl_auth_probe выполняет минимальный реальный getWorkbooksList. После успешной проверки можно искать объекты, читать их связи или использовать один из готовых сценариев.

Безопасность изменений

Перед записью сервер:

1. повторно читает актуальную сохранённую версию;
2. проверяет точный тип и ID цели;
3. сверяет ревизию и ожидаемые поля;
4. накладывает только требуемое изменение и сохраняет нетронутые поля;
5. валидирует payload и связанные условия;
6. после save читает и проверяет saved-версию;
7. строит publish только из проверенного saved state;
8. после publish читает published-версию.

При конфликте ревизии, блокировке, нарушении уникальности или неопределённом результате записи цикл останавливается. Значения DATALENS_MCP_ENABLE_WRITES=0, DATALENS_MCP_LIVE_ALLOW_SAVE=0 и DATALENS_MCP_LIVE_ALLOW_PUBLISH=0 имеют приоритет над запросом.

API-readback подтверждает структуру и состояние объекта. Фактическое отображение подтверждает отдельная browser-проверка со стороны MCP-клиента; если она недоступна, это ограничение должно быть явно указано в результате.

Подробнее: модель безопасности и Safe Apply.

Документация

Точная схема активной поверхности текущей установки доступна через MCP tools/list. По умолчанию это компактный профиль autonomous-v2; профиль legacy-v1 сохраняет прежние 39 lifecycle-инструментов.

Статус проекта

• Независимый проект, не относящийся к официальным продуктам Yandex или Yandex Cloud.
• Статус Python-пакета: Alpha.
• Для реальных записей рекомендуется выбирать специальные целевые объекты и проверять результат.
• main содержит единственную актуальную реализацию сервера; история изменений сохраняется в Git и прошедших review pull requests.
• Источник точного набора инструментов — tools/list текущей установки; поверхность по умолчанию autonomous-v2 содержит 8 task-level инструментов.

Разработка

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
python3 scripts/check_docs_consistency.py
python3 scripts/run_quick_checks.py
python3 scripts/run_offline_acceptance.py

Финальное доказательство установленного публичного workflow выполняется только
на frozen release candidate и отдельном target по контракту
docs/public-autonomy-canary.md.

Offline acceptance не использует реальные учётные данные DataLens и не выполняет live-запись.

Лицензия и источники

Код и оригинальная документация проекта распространяются по Apache License 2.0. Справочные данные, адаптированные из документации Yandex Cloud, сопровождаются атрибуцией по CC BY 4.0. Официальные страницы перечислены в docs/sources.md, полные уведомления — в THIRD_PARTY_NOTICES.md.