@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/README.md

@@ -0,0 +1,124 @@
+# @sberbusiness/triplex-next-mcp-server
+
+MCP-сервер для дизайн-системы Triplex. Предоставляет AI-агентам документацию компонентов, дизайн-токены и примеры использования через [Model Context Protocol](https://modelcontextprotocol.io/).
+
+## Быстрый старт
+
+### Подключение к Claude Code
+
+Добавьте в `.mcp.json` вашего проекта:
+
+```json
+{
+  "mcpServers": {
+    "triplex": {
+      "command": "npx",
+      "args": ["@sberbusiness/triplex-next-mcp-server"]
+    }
+  }
+}
+```
+
+### Подключение к Cursor
+
+Добавьте в `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "triplex": {
+      "command": "npx",
+      "args": ["@sberbusiness/triplex-next-mcp-server"]
+    }
+  }
+}
+```
+
+После подключения AI-агент получает доступ к документации всех компонентов Triplex без необходимости клонировать репозиторий дизайн-системы.
+
+## Доступные tools
+
+| Tool                                | Описание                                                                                                      |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `list_components`                   | Список всех компонентов с кратким описанием и флагом `ai_ready`                                               |
+| `get_component(name)`               | Полная документация компонента: props, токены, примеры, ограничения                                           |
+| `get_tokens(component?)`            | Дизайн-токены — все или для конкретного компонента                                                            |
+| `list_icons(query?, size?, limit?)` | Иконки из `@sberbusiness/icons-next` с фильтрами по подстроке в имени и размеру (защита от галлюцинаций имён) |
+
+Флаг `ai_ready: true` означает, что у компонента есть полноценная AI-документация
+(`*-AI.md` с frontmatter, секциями и примерами). Для остальных компонентов сервер
+возвращает минимальный fallback — имя и путь к `stories`.
+
+## Примеры использования
+
+После подключения сервера AI-агент может отвечать на запросы вроде:
+
+- «Какие props есть у компонента Button?»
+- «Покажи пример использования Alert с типом error»
+- «Какие дизайн-токены использует Card?»
+- «Какой компонент подойдёт для отображения уведомлений?»
+- «Найди иконку со стрелкой размером 16px»
+
+## Разработка
+
+```bash
+# Установка зависимостей
+npm install
+
+# Сборка
+npm run build
+
+# Сборка в watch-режиме
+npm run dev
+
+# Запуск сервера
+npm run start
+
+# Отладка через MCP Inspector
+npm run inspect
+
+# Обновить bundle/ из последнего релиза triplex-next
+npm run fetch-bundle
+
+# Обновить bundle/icons.json из @sberbusiness/icons-next
+npm run fetch-icons
+
+# Проверка типов
+npm run typecheck
+
+# Тесты
+npm run test
+```
+
+## Источник данных
+
+Сервер читает документацию из дерева `bundle/` (авто-генерируется, руками
+не правим):
+
+```
+bundle/
+  manifest.json       — schemaVersion, triplexVersion, списки компонентов,
+                        гайдов и release notes
+  components/         — *-AI.md по AI-ready компонентам
+  guides/             — docs/ai/*.md (context, codestyle, tests, …)
+  release-notes/      — stories/release-notes/v1/*.mdx
+  icons.json          — список иконок @sberbusiness/icons-next для list_icons
+```
+
+Дерево генерируется командой `npm run fetch-bundle`: она скачивает
+`mcp-data.json` c последнего GitHub Release [triplex-next](https://github.com/SberBusiness/triplex-next)
+(или из локального файла через `--file <path>`) и раскладывает
+содержимое в поддиректории выше. Транзиентный `mcp-data.json` удаляется
+после раскладки.
+
+В triplex-next bundle собирается скриптом `scripts/generateMcpData.ts`
+(npm-команда `generateMcpData`) и автоматически прикладывается к релиз-ассетам
+через `.github/workflows/release.yml`.
+
+`bundle/icons.json` генерируется отдельно — командой `npm run fetch-icons`,
+которая тянет `@sberbusiness/icons-next` с jsdelivr и собирает список имён
+экспортов с размерами.
+
+## Лицензия
+
+MIT

package/bundle/components/AbstractTree.md

@@ -0,0 +1,198 @@
+---
+component: AbstractTree
+category: Utilities
+figma-node: ""
+figma-file: ""
+related: [TreeView, CollapsableTree, CheckboxTree]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# AbstractTree
+
+## Назначение
+
+Внутренняя утилита: дженерик-класс `AbstractTreeNode<T>` и функция обхода
+`traverseAbstractTree` для построения произвольных древовидных структур данных.
+
+Используется как базовый класс для специализированных нод (например,
+`TreeViewAbstractNode` в `src/components/TreeView/`). НЕ является React-компонентом,
+не рендерит UI и не экспортируется из публичного API библиотеки — только для
+внутреннего переиспользования между компонентами дерева.
+
+Используй когда: нужна модель узла дерева с API добавления/удаления/обхода детей
+внутри компонента, работающего с иерархическими данными.
+Не используй когда: нужен просто массив. Не импортируй из приложений-потребителей —
+это internal API без гарантий стабильности.
+
+---
+
+## Файловая структура
+
+```text
+src/components/AbstractTree/
+└── AbstractTreeNode.ts   # Класс AbstractTreeNode<T> + функция traverseAbstractTree
+```
+
+Особенности:
+- Нет `index.ts` (barrel) — импорт только по прямому пути `./AbstractTreeNode`.
+- Нет TSX, LESS, stories, тестов — это чистая TypeScript-утилита.
+- Зависимость от внешней библиотеки: `lodash-es` (`isEqual` для сравнения нод).
+
+---
+
+## Публичный API модуля
+
+### Класс `AbstractTreeNode<T extends AbstractTreeNode<T>>`
+
+Дженерик-класс с рекурсивным типом — `T` должен расширять сам `AbstractTreeNode<T>`.
+Это позволяет наследникам возвращать из методов конкретный подтип, а не базовый.
+
+| Метод | Сигнатура | Описание |
+|---|---|---|
+| `getChildren` | `() => T[]` | Возвращает массив дочерних нод (ссылку на приватный массив). |
+| `addChild` | `(node: T, prevNode?: T, nextNode?: T) => void` | Добавляет ноду. По умолчанию — в конец. С `prevNode` — после указанной. С `nextNode` — перед указанной. Автоматически выставляет `parent` у добавляемой ноды. |
+| `removeChild` | `(node: T) => void` | Удаляет дочернюю ноду по `isEqual`. Сбрасывает её `parent` в `null`. No-op, если не найдена. |
+| `setChildren` | `(nodes: T[]) => void` | Полностью заменяет детей. У старых детей `parent` обнуляется, у новых — выставляется на `this`. |
+| `getParent` | `() => T \| null` | Возвращает родительскую ноду. `null` для корневой. |
+| `setParent` | `(node: T \| null) => void` | Устанавливает родителя. Обычно вызывается внутри `addChild`/`removeChild`/`setChildren`, но экспонирован публично (используется в `traverse` и в наследниках). |
+
+Приватные поля:
+- `children: T[] = []`
+- `parent: T \| null = null`
+
+### Функция `traverseAbstractTree<VisionNode>(node, callback)`
+
+```ts
+function traverseAbstractTree<VisionNode extends AbstractTreeNode<VisionNode>>(
+    node: VisionNode,
+    callback: (node: VisionNode) => boolean,
+): void
+```
+
+Обходит дерево в глубину сверху вниз (pre-order DFS), начиная с переданной
+ноды. На каждой ноде вызывает `callback`.
+
+- Если `callback` возвращает `false` — обход поддерева текущей ноды прекращается
+  (её дочерние ноды не будут посещены). Это **не** прерывает весь обход — только
+  спуск в текущую ветку.
+- Если `callback` возвращает `true` — обход продолжается рекурсивно по детям.
+
+Пример паттерна "найти и выйти" в TreeView — `callback` сохраняет найденную ноду
+в замыкание и возвращает `false` для остановки спуска:
+
+```ts
+let result;
+traverseAbstractTree(rootNode, (n) => {
+    if (n.getId() === nodeId) {
+        result = n;
+        return false; // прервать ветку
+    }
+    return true;
+});
+```
+
+---
+
+## Ключевые особенности реализации
+
+### Сравнение нод через `lodash.isEqual`
+
+`addChild`, `removeChild` находят позицию по `isEqual(n, prevNode/nextNode/node)`
+— глубокое рекурсивное сравнение, а не по идентичности ссылок (`===`).
+
+**Последствие:** если у двух нод идентичная структура данных (одинаковые id, одинаковые
+дети, одинаковый parent в момент сравнения), они будут считаться равными и `removeChild`
+удалит первую совпавшую. В текущем использовании (TreeView) это нивелируется тем, что
+наследник `TreeViewAbstractNode` имеет уникальный `id`, но для новых наследников
+стоит учитывать эту семантику.
+
+### Public `setParent`
+
+`setParent` помечен как public, хотя логически это "приватный" метод внутри графа
+связей. Это сделано потому, что `addChild`/`setChildren` вызывают `node.setParent(this)`
+на чужом инстансе — TypeScript не разрешает это для private-методов без `@ts-ignore`.
+В файле есть два `@ts-ignore` именно для этой ситуации — это осознанный компромисс,
+не удалять.
+
+### Методы как arrow-свойства
+
+Все методы объявлены как arrow-функции-свойства (`public addChild = (...) => {}`),
+а не как обычные методы класса. Это захватывает `this` в замыкание, и экземпляры
+можно безопасно передавать в callback'и без потери контекста (`node.addChild`
+без `.bind(this)` работает корректно).
+
+**Последствие:** каждый инстанс имеет свою копию функций (не в prototype). Для деревьев
+с тысячами нод это заметный оверхед по памяти. Учитывай при профилировании.
+
+### Порядок вставки при `addChild`
+
+Приоритет аргументов: `prevNode` проверяется **раньше** `nextNode`. Если переданы
+оба — `nextNode` игнорируется, вставка произойдёт после `prevNode`.
+
+### `setChildren` не очищает переданные ноды
+
+Если переданная в `setChildren` нода уже имеет `parent` в другом дереве — её старый
+`parent` НЕ будет знать, что она ушла (его `children` по-прежнему содержит ссылку).
+Перемещение нод между деревьями требует ручного вызова `removeChild` на старом
+родителе.
+
+---
+
+## Инварианты
+
+- **Рекурсивный дженерик `T extends AbstractTreeNode<T>`** — не упрощать до
+  `AbstractTreeNode` или `any`. Это обеспечивает типобезопасность наследников
+  (например, `TreeViewAbstractNode.getChildren()` возвращает `TreeViewAbstractNode[]`,
+  а не базовый тип).
+- **`lodash-es` как источник `isEqual`** — не заменять на самописное сравнение или
+  shallow `===`, это меняет контракт `removeChild`/`addChild`.
+- **`@ts-ignore` на вызовах `setParent` чужого инстанса** — не удалять, не заменять
+  на `as any` (см. раздел выше о `public setParent`).
+- **Pre-order DFS обхода** — порядок посещения узлов в `traverseAbstractTree`
+  является контрактом (TreeView полагается на него при поиске активной ноды и
+  клавиатурной навигации). Не менять на BFS или post-order.
+- **Возврат `false` прерывает только текущее поддерево**, а не весь обход —
+  этот контракт используется для "find and stop descent" в `TreeViewAbstractNodeUtils`.
+- **Отсутствие `index.ts`** — не добавлять. Модуль не предназначен для публичного
+  экспорта из библиотеки, только для внутренних импортов через прямой путь.
+
+---
+
+## Accessibility
+
+N/A — утилитарный модуль данных, не рендерит DOM.
+
+---
+
+## Дизайн-токены
+
+Нет — у модуля нет стилей.
+
+---
+
+## Связанные компоненты
+
+- `TreeView` (`src/components/TreeView/TreeViewAbstractNode.tsx`) — наследуется от
+  `AbstractTreeNode`, добавляет поля `id`, `active`, `opened`, `tabIndex`.
+- `TreeView` (`src/components/TreeView/TreeViewAbstractNodeUtils.ts`) — использует
+  `traverseAbstractTree` для поиска активной ноды, получения ноды по `id`,
+  сброса флагов активности.
+- Потенциальные будущие потребители: `CollapsableTree`, `CheckboxTree`,
+  `CheckboxTreeExtended`. На момент документа они реализованы иначе (не через
+  `AbstractTreeNode`), но могут быть переведены на эту модель.
+
+---
+
+## Stories
+
+Нет — утилитарный модуль без UI не имеет stories.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/AccordionBase.md

@@ -0,0 +1,227 @@
+---
+component: AccordionBase
+category: Internals
+figma-node: ""
+figma-file: ""
+related: [ExpandAnimation, CollapsableTree, Spoiler]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# AccordionBase
+
+## Назначение
+
+Внутренний безстилевой базовый компонент раскрывающегося блока (аккордеон). Реализует
+логику controlled/uncontrolled состояния, анимацию раскрытия через `ExpandAnimation`,
+генерацию уникального id и `aria-controls`/`aria-expanded` атрибутов. Визуальное
+оформление и вёрстка header/body целиком делегируются потребителю через render-props
+(`renderHeader`, `renderBody`).
+
+Используется как низкоуровневый примитив: на его основе построены `CollapsableTree`
+(древовидный UI с раскрывающимися нодами). Папка `protected/` и отсутствие экспорта
+из публичного barrel — явный сигнал, что это internal API.
+
+Используй когда: строишь новый высокоуровневый раскрывающийся компонент (например,
+другой вариант tree / spoiler), и хочешь переиспользовать логику состояния + анимацию.
+Не используй когда: нужен готовый аккордеон с визуалом — это НЕ пользовательский
+компонент, импортируй уровнем выше (`CollapsableTreeNode`, `Spoiler`).
+Не импортируй из приложений-потребителей — internal API без гарантий стабильности.
+
+---
+
+## Файловая структура
+
+```text
+src/components/AccordionBase/
+├── types.ts                          # IAccordionBaseProps, IAccordionBodyProvideProps, IAccordionHeaderProvideProps
+└── protected/
+    └── AccordionBase.tsx             # Class-component React.Component (не forwardRef, не функциональный)
+```
+
+Особенности:
+- Нет `index.ts` (barrel) — импорты только по прямым путям.
+- Нет LESS — модуль без собственных стилей.
+- Нет stories, нет тестов — тестируется косвенно через `CollapsableTree`.
+- Папка `protected/` — конвенция для internal-компонентов, не попадающих в публичный API.
+
+---
+
+## Варианты и props
+
+### `IAccordionBaseProps`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `renderHeader` | `(props: IAccordionHeaderProvideProps) => JSX.Element` | Да | Рендер-функция видимой (всегда видимой) части. Получает `isOpen`, `toggle`, `animating`, `ariaAttributes`. |
+| `renderBody` | `(props: IAccordionBodyProvideProps) => React.ReactNode` | Да | Рендер-функция сворачиваемого контента. Оборачивается в `ExpandAnimation`. |
+| `isOpen` | `boolean` | Нет | **Наличие prop = controlled mode.** Если передан — состояние управляется снаружи. Если `undefined` — uncontrolled, состояние держит сам AccordionBase. |
+| `toggle` | `(isOpen: boolean) => void` | Нет | Для controlled mode: вызывается при клике, потребитель должен обновить `isOpen`. |
+| `onToggle` | `(isOpen: boolean) => void` | Нет | Вызывается **после окончания анимации** (не при клике). Для side-эффектов, не связанных с управлением состоянием. |
+| `expandAnimationClassName` | `string` | Нет | Пробрасывается в `ExpandAnimation` (`className` на контейнер с animated max-height). |
+| `children` | `never` | — | Явно запрещены через `never` — только render-props. |
+
+### `IAccordionHeaderProvideProps` (передаётся в `renderHeader`)
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `isOpen` | `boolean` | Текущее состояние (учитывает controlled/uncontrolled). |
+| `toggle` | `() => void` | Вызов для переключения. Потребитель должен повесить на клик/keypress. |
+| `animating` | `boolean` | `true` во время анимации раскрытия/сворачивания. |
+| `ariaAttributes` | `TAriaHTMLAttributes` | Готовые aria-атрибуты для header: `controls` (id body) и `expanded` (строка "true"/"false"). Потребитель обязан применить их к интерактивному элементу. |
+
+### `IAccordionBodyProvideProps` (передаётся в `renderBody`)
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `isOpen` | `boolean` | Текущее состояние. |
+| `toggle` | `() => void` | Доступен и в body — например, чтобы закрыть изнутри. |
+| `animating` | `boolean` | `true` во время анимации. Полезно для условного размонтирования контента. |
+
+**В body `ariaAttributes` не передаётся** — aria-id ставится на контейнер
+`ExpandAnimation` автоматически (атрибут `id={instanceId}`), связь `aria-controls` →
+`id` работает через него.
+
+---
+
+## Ключевые особенности реализации
+
+### Controlled/uncontrolled mode
+
+Определяется **один раз в конструкторе** по `typeof props.isOpen !== "undefined"`
+и сохраняется в `state.controlled`. Это значит: **если потребитель начал с `isOpen=undefined`,
+а потом передал `true` — переход в controlled mode НЕ произойдёт**. Следствие: не меняй
+управляющий контракт в рантайме, фиксируй его при первом рендере.
+
+### Класс-компонент, не forwardRef
+
+`AccordionBase extends React.Component` — единственный случай class-компонента среди
+документированных базовых примитивов. Не переписывать на функциональный компонент без
+согласования: наследники (например, `CollapsableTreeNode`) тоже class-компоненты и
+полагаются на lifecycle-методы (`componentDidUpdate`).
+
+**`forwardRef` здесь не применяется** — это внутренний API, и ref на корневой узел
+не имеет смысла (render возвращает фрагмент `<>{header}{body}</>`, корневого DOM-элемента
+нет).
+
+### `uniqueId` из `lodash-es`
+
+`instanceId = \`AccordionBase-${uniqueId()}\`` — генерируется один раз при создании.
+Используется для связи `aria-controls` (на header) → `id` (на body-контейнере). Не
+заменять на `React.useId` — компонент классовый, и любой переход на `useId` требует
+перевода на функциональный компонент целиком.
+
+### `animating` не делает два разных состояния
+
+`animating` устанавливается в `true` при смене `isOpen` (в `componentDidUpdate` для
+controlled, в `toggle` для uncontrolled) и сбрасывается в `false` в коллбеке
+`ExpandAnimation.onEnd`. Между двумя этими событиями `onToggle` НЕ вызывается —
+он стреляет только в `setState-callback` после сброса `animating`. Значит: `onToggle`
+— сигнал "анимация завершена", не "клик произошёл".
+
+### `expandAnimationClassName` и закомментированные классы
+
+В `renderBody` есть закомментированный блок со старыми глобальными классами
+(`cssClass[globalExpandAnimationAnimating]`, `cssClass[globalExpandAnimationOpened]`).
+Это artifact миграции со старой LESS-системы — не расширять, не включать обратно
+без согласования, сейчас дополнительные классы отсутствуют намеренно.
+
+### Render возвращает Fragment
+
+```tsx
+return (
+    <>
+        {header}
+        {body}
+    </>
+);
+```
+
+Нет обёртывающего DOM-узла. Потребитель renderHeader/renderBody сам решает, нужен
+ли корневой контейнер. Это делает компонент максимально неинвазивным для вёрстки
+потребителя.
+
+---
+
+## Инварианты
+
+- **Class-компонент на `React.Component`** — не переписывать на функциональный без
+  согласования. Наследники завязаны на lifecycle-методы.
+- **`displayName = "AccordionBase"`** — публичное имя для React DevTools, не
+  переименовывать (используется при дебаге деревьев).
+- **`controlled` вычисляется в конструкторе и не меняется** — не добавлять логику
+  переключения режимов в рантайме.
+- **`onToggle` стреляет после анимации, `toggle` — при клике** — не менять семантику,
+  наследники полагаются на неё (`CollapsableTreeNode` использует `onToggle` для
+  синхронизации состояния дерева).
+- **`children?: never`** в `IAccordionBaseProps` — не превращать в `children: ReactNode`.
+  Компонент намеренно render-props, не children-as-function.
+- **`ariaAttributes` для header** — не изменять набор передаваемых полей (`controls`,
+  `expanded`), потребители (`CollapsableTreeNode`, `Spoiler`) раскладывают их
+  спредом на свой `<button>`.
+- **Отсутствие `index.ts` и `protected/` в пути** — сигнал internal API. Не
+  добавлять barrel, не выносить из `protected/` без обсуждения архитектуры
+  публичного экспорта.
+- **Зависимость от `ExpandAnimation`** — AccordionBase не реализует анимацию сам,
+  всегда делегирует. Не дублировать max-height логику здесь.
+
+---
+
+## Accessibility
+
+AccordionBase сам по себе не ставит ARIA-роли и не обрабатывает клавиатуру —
+это задача потребителя `renderHeader`. Что AccordionBase даёт:
+
+- **`ariaAttributes.controls`** — уникальный id (`AccordionBase-{n}`), связывающий
+  header с body. Потребитель **обязан** применить к header-элементу:
+  `<button aria-controls={ariaAttributes.controls} aria-expanded={ariaAttributes.expanded}>`.
+- **`ariaAttributes.expanded`** — строка `"true"` / `"false"` (не boolean, уже
+  приведено через `.toString()`).
+- **`id` на body-контейнере** — автоматически применяется к `ExpandAnimation`,
+  чтобы `aria-controls` указывал на валидный элемент.
+
+**Что обязан сделать потребитель:**
+- Использовать семантический интерактивный элемент в `renderHeader` (`<button>`,
+  не `<div onClick>`), чтобы клавиатура и screen reader работали из коробки.
+- Повесить `toggle` на `onClick` (и, при необходимости, на `onKeyDown` для кастомных
+  триггеров).
+- При необходимости передать `role="region"` и `aria-labelledby` в body (AccordionBase
+  не делает этого автоматически).
+
+**Что НЕ делает AccordionBase:** управление фокусом, обработка клавиатурных событий,
+`aria-disabled`, `role` — всё это задача потребителя.
+
+---
+
+## Дизайн-токены
+
+Нет — компонент без собственных стилей.
+
+---
+
+## Связанные компоненты
+
+- `ExpandAnimation` (`src/components/ExpandAnimation`) — оборачивает body, реализует
+  анимацию max-height. AccordionBase использует напрямую, без возможности замены.
+- `CollapsableTree` / `CollapsableTreeNode` (`src/components/CollapsableTree`) —
+  главный потребитель. Оборачивает AccordionBase в узел TreeView с клавиатурной
+  навигацией и интеграцией в дерево.
+- `Spoiler` (`src/components/Spoiler`) — концептуально близкий компонент (раскрывающийся
+  блок), в текущей реализации не использует AccordionBase, но мог бы.
+- `lodash-es` (`uniqueId`) — внешняя зависимость для генерации instanceId.
+
+---
+
+## Stories
+
+Нет — internal-компонент без UI, покрывается stories/тестами потребителей
+(`CollapsableTree`).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |