MCP-сервер Dashboard Builder

Позволяет ИИ-клиенту обнаруживать ваши наборы данных и создавать дашборды в Dashboard Builder.

Он общается с приложением Next.js по HTTP как обычный API-клиент, поэтому все проверки разрешений, политики зависимостей и правила валидации в приложении по-прежнему действуют. В основном приложении ничего не меняется.

Запускается двумя способами:

Хостинг — это обычное развёртывание, и именно его описывает этот документ. Локальный режим предназначен для разработки самого сервера или для индивидуальной идентичности и описан в DEVELOPMENT.md.

Для пользователей: подключение к хостинг-серверу

Вам понадобятся две вещи от того, кто его развернул: URL и ваш ключ доступа. Ничего клонировать, никаких файлов, на которые нужно указывать, никакого .env.

Добавьте это в claude_desktop_config.json (Claude Desktop) или .mcp.json (Claude Code):

{
  "mcpServers": {
    "dashboard-builder": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.yourcompany.com/mcp",
        "--header", "Authorization: Bearer YOUR_KEY_HERE",
        "--header", "X-Dashboard-Username: you",
        "--header", "X-Dashboard-Password: your-dashboard-password"
      ]
    }
  }
}

mcpServers — это ключ верхнего уровня, сосед preferences — не вложенный внутрь него. Закройте Claude Desktop из системного трея и откройте заново; закрытие окна недостаточно.

С двумя заголовками X-Dashboard-* сервер автоматически входит в систему от вашего имени при первом использовании и снова при каждом истечении сессии — больше ничего делать не нужно, и каждый вызов действует как вы: ваши разрешения, ваш аудит-трейл. Обратная сторона: ваш пароль от дашборда хранится в этом конфигурационном файле и передаётся (по HTTPS) с каждым запросом. Если пароль содержит символы вне ASCII, используйте приведённую ниже привязку через curl — HTTP-заголовки не передают их надёжно.

Альтернатива: привязать один раз через curl, не хранить пароль в конфиге

Опустите два заголовка X-Dashboard-* и вместо этого привяжите свой ключ один раз — пароль используется только для этого единственного входа и нигде не сохраняется; сервер хранит только полученные токены сессии, точно так же, как браузер хранит куки:

curl -X POST https://mcp.yourcompany.com/auth/bind \
  -H "Authorization: Bearer YOUR_KEY_HERE" \
  -H "content-type: application/json" \
  -d '{"username":"you","password":"your-dashboard-password"}'

Отличие от маршрута с заголовками: когда цепочка сессий в конце концов истекает, вы повторно запускаете эту команду, тогда как заголовки привязываются автоматически. DELETE /auth/bind с тем же заголовком Authorization в любом случае подписывает ключ.

Alice's Claude ──[gate key]──> MCP server ──[Alice's session cookies]──> Dashboard API
                     ^                                ^
              client config              bound via credential headers or
                                         POST /auth/bind; refreshed
                                         automatically after that

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

mcp-remote — это небольшой мост, который запускается локально и пересылает запросы на сервер, поэтому на машине пользователя должен быть установлен Node. Чтобы избежать даже этого, в Claude Desktop Настройки → Коннекторы → Добавить пользовательский коннектор принимает URL напрямую без локальных компонентов — этот путь ожидает OAuth, а не статический ключ, и доступность зависит от версии Desktop.

Развёртывание сервера

server.js — это стартовый файл. Он слушает PORT как server.js в Next.js и ставит API-ключевой шлюз перед каждым MCP-запросом, чтобы неаутентифицированные вызывающие отклонялись до того, как что-либо достигнет системы дашбордов.

Конечные точки: POST /mcp (защищён), POST /auth/bind и DELETE /auth/bind (защищены — привязка или отвязка идентичности дашборда вызывающего ключа), и GET /health (открыт, для проверки работоспособности платформы). Всё остальное возвращает 404.

Переменные окружения

Обязательные — без них сервер не запустится

Сгенерируйте ключи с помощью openssl rand -hex 24. Метка перед двоеточием появляется в журналах и в корзинах ограничения скорости; сам секрет никогда не логируется. Отзовите доступ одному человеку, удалив его запись и перезапустив сервер — и удалите его файл сессии в ~/.dashboard-mcp/sessions/, чтобы также сбросить привязанную идентичность.

Затем каждый ключ привязывается к учётной записи дашборда его владельцем через POST /auth/bind — см. раздел для пользователей выше. Никакие учётные данные дашборда не хранятся в окружении сервера.

Необязательный устаревший запасной вариант — общая сервисная учётная запись

Если задано, ключи, которые не были привязаны, действуют как эта общая учётная запись вместо ошибки — как и ключ, чья привязка истекла, пока он не будет привязан заново. Полезно во время миграции; пропустите для новых развёртываний, чтобы у каждого вызывающего была своя идентичность.

Настоятельно рекомендуется

Оставьте DASHBOARD_MCP_PERSIST_SESSION по умолчанию (true): привязки хранятся по одному файлу на ключ и переживают перезапуски. Установка false хранит привязки только в памяти, поэтому каждый перезапуск — и каждый воркер в многопроцессном хосте — требует повторной привязки.

MCP_ALLOWED_HOSTS и MCP_ALLOWED_ORIGINS — необязательны — сервер работает без них, и API-ключевой шлюз всё равно действует. Установка любого из них включает защиту транспорта от DNS-ребдинга. Если оба не заданы, журнал запуска явно сообщает об этом.

Необязательные

Дополнительные переменные настройки — путь к файлу сессии, таймаут запроса, ограничения ответа и переопределение идентификатора вида дашборда — задокументированы встроенно в .env.example, который организован по режимам и перечисляет все переменные, которые читает сервер.

Примечание о нескольких воркерах

Привязки хранятся по одному файлу на ключ, и воркер, чей токен в памяти был ротирован другим воркером, восстанавливается, перечитывая этот файл, который уже обновил выигравший воркер. Окно сбоя — два воркера, обновляющие один и тот же токен в один и тот же момент; проигравший восстанавливается при следующей попытке, а в худшем случае ключ нужно привязать заново. Сам MCP-транспорт не имеет состояния, поэтому запросы могут попадать на любой воркер.

Настройка Plesk

Добавьте в Дополнительные директивы nginx домена:

proxy_buffering off;
proxy_read_timeout 300s;

MCP отвечает как Server-Sent Events, и nginx по умолчанию буферизует проксируемые ответы. Без proxy_buffering off запросы выглядят зависшими, а не завершающимися ошибкой, что является запутанным способом потерять полдня.

Держите порт Node вне публичного брандмауэра. nginx Plesk проксирует на него и устанавливает X-Forwarded-For, что делает логируемые IP-адреса клиентов достоверными.

Доступ против идентичности

Ключ доступа управляет доступом; идентичность исходит из привязки. Ключ пропускает вызывающего через шлюз, а сессия, привязанная к этому ключу, определяет, кого видит дашборд — их разрешения, их аудит-трейл. Эти две вещи намеренно разделены: ротация секрета ключа сбрасывает его привязку (сессия хранится под дайджестом ключа), а отзыв ключа удаляет доступ, не затрагивая учётную запись.

Привязка работает так же, как вход в браузере. POST /auth/bind один раз запускает реальный /api/auth/login приложения, пароль отбрасывается после обмена, и сохраняется только вращающаяся сессия с refresh-токеном — один файл на ключ, режим 0600. Поскольку приложение вращает refresh-токен при каждом использовании, утёкший файл сессии быстро умирает; поскольку пароль никогда не хранится, нечего долго хранить. Компромисс: когда цепочка refresh-токенов истекает или ломается, этот ключ повторно привязывается одной командой curl.

Стабильные учётные данные на запрос (ApiKey в основной системе или OAuth) устранили бы даже эту повторную привязку, но требуют изменений в основном приложении. Этот дизайн намеренно не требует никаких.

Разработка или локальный запуск

Запуск сервера на вашей собственной машине — для разработки или для индивидуальной идентичности без хостинга — задокументирован отдельно в DEVELOPMENT.md.

Инструменты

Заметки по дизайну

Контекстная дисциплина. Вся поверхность инструментов занимает около 3.6 KB — 13 описаний плюс инструкции сервера — поэтому её дёшево держать загруженной. Ответы — это компактный текст, а не сырой JSON, и каждый список завершается явным примечанием о том, что было опущено. get_dashboard намеренно опускает конфиги виджетов; когда нужен конфиг конкретного виджета, вы запрашиваете один виджет по id.

Прогрессивное раскрытие. Конфиг графика содержит примерно 59 полей. Если поместить это в описание инструмента, он будет доминировать в контексте клиента при каждом запросе, поэтому describe_widget_kind предоставляет контракт по требованию: имена полей, типы, примечания, минимальный рабочий пример и — самое полезное — реальный конфиг, извлечённый из существующего виджета этого типа в вашем собственном рабочем пространстве. Копировать форму, которая уже рендерится, лучше, чем изобретать её по именам полей.

Геометрией занимается сервер. Модели ненадёжны в 2D-упаковке. add_widget принимает подсказку size (small, medium, large, full) и сам находит первую свободную непересекающуюся ячейку на 12-колоночной сетке. arrange_dashboard в режиме auto переупаковывает всю панель.

Сбой до API, а не после. Конфиги виджетов хранятся приложением как непрозрачный JSON, поэтому опечатка в ключе приводит к пустому виджету, а не к ошибке. add_widget сначала проверяет конфиг на соответствие контракту типа — обязательные ключи, допустимые имена агрегаций, наличие field, когда того требует агрегация — и возвращает конкретный список того, чего не хватает.

Виджеты соответствуют тому, что создал бы UI. Палитра приложения снабжает каждый новый виджет defaultConfig соответствующего типа из реестра (config === undefined ? def.defaultConfig : config). add_widget повторяет это: значения по умолчанию типа подкладываются под всё, что передаёт вызывающая сторона, поэтому диаграмма, созданная через MCP, несёт тот же базовый уровень paginationMode и maxPoints, что и созданная вручную, вместо разреженного конфига, на который рендереру приходится опираться. Проверяется именно объединённый объект.

Слияние вместо повторной отправки. PATCH /widgets/:id заменяет объект конфига целиком. update_widget по умолчанию сливает ваши ключи с существующим конфигом, поэтому изменение одного параметра не означает повторную отправку всего конфига.

Безопасный отказ при запуске. HTTP-сервер отказывается запускаться без хотя бы одной записи MCP_API_KEYS и отклоняет ключи короче 24 символов. Неаутентифицированный MCP-эндпоинт никогда не должен появиться случайно. Ключи сравниваются как SHA-256-дайджесты с помощью timingSafeEqual, и логируются только метки.

Известные ограничения

• Каталог типов виджетов — это копия. src/catalog/widget-kinds.ts зеркалит src/features/dashboard/widgets/registry.ts — включая defaultConfig каждого типа — и интерфейсы конфигов для каждого типа. Реестр приложения — клиентский компонент и импортирует React, поэтому его нельзя импортировать здесь. Если у типа виджета появляется новое поле или изменяется значение defaultConfig, обновите и каталог, иначе виджеты, созданные через MCP, будут расходиться с созданными через UI.

• Покрытие каталога высокое, но не полное. Документированные и фактические поля конфигов: table 18/21, stat 22/25, chart 39/59, select 9/12, text 16/17. Опущены в основном косметические варианты (стили для круговых/линейных/столбчатых диаграмм, переопределения правой оси) и устаревшие ключи взаимодействия, заменённые highlightBindings. Живой пример, возвращаемый describe_widget_kind, служит для них справочником. Поля сгруппированы в core / display / interaction, чтобы контракт данных читался в первую очередь.

• Привязки истекают вместе с цепочкой обновления. Сессия ключа живёт, пока приложение поддерживает свой сменный refresh-токен в активном состоянии. Когда она истекает, вызовы завершаются ошибкой, указывающей исправление, и держатель ключа повторно привязывает его одной командой curl. Для бессрочной идентичности нужно подключить ApiKey в src/lib/api-guard.ts в основной системе, а этого не сделано.

• Записи выполняются напрямую. В приложении есть рабочий процесс черновиков изменений и утверждения (ChangeDraft, ApprovalRequest). Эти инструменты пишут напрямую с правами вошедшей учётной записи. Если панели, созданные ИИ, должны проверяться перед публикацией, направляйте инструменты записи на /api/change-drafts вместо этого и оставьте разрешения учётной записи только для чтения.