@daisforge/ui-mcp 0.2.3 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -27,15 +27,10 @@ MCP-сервер для `@daisforge/ui` — даёт кодовому агент
27
27
  - `get_component_props({ name, part? })` — полные пропсы (собственные + унаследованные от атома). Пропсы отсортированы: `required` → с описанием → без описания → `deprecated` в конец, по алфавиту внутри яруса (T7) — при обрезке по бюджету теряется наименее нужное, а не случайное подмножество. Описания, дословно совпадающие с JSDoc React DOM-типизации того же имени, не попадают в индекс (T7). У части пропсов есть `default` — значение по умолчанию, извлечённое из деструктуризации параметра render-функции или тега `@default` в JSDoc (T6); поле опционально, отсутствует, если дефолт не резолвлен
28
28
  - `get_component_examples({ name, title? })` — только настоящие примеры, до 4 суммарно, из трёх источников: `full-code`/`args-only` из curated Storybook-стори, `usage` — реальное JSX-вхождение, найденное грепом по остальным пакетам монорепо, `vendor` — curated-пример из вендоренного снэпшота `@salutejs/sdds-finai` с переписанным на `@daisforge/ui` импортом, в том числе из "чужого" файла снэпшота — например, примеры `AccordionItem` находятся внутри `Accordion.json` (T3); отсортированы `full-code → usage → vendor → args-only`. У `usage` есть `sourceFile` (путь относительно корня монорепо)
29
29
  - `list_features({ component })`, `get_feature({ component, feature })`, `get_feature_examples({ component, feature, title? })`
30
+ - `list_categories()` — категории каталога с количеством компонентов по типам; значения `category` отсюда подходят как фильтр для `list_components` (они же продублированы прямо в описании `list_components`, чтобы фильтр можно было применить без этого вызова)
31
+ - `get_installation_guide()` — установка пакета, подключение стилей и токенов, использование компонентов и иконок; на него ссылается `dataVersionNotice`, когда `@daisforge/ui` в проекте не установлен
30
32
 
31
- Девять тулов — `list_categories` и `get_installation_guide` были тулами без аргументов, отдающими статический контент, не зависящий от вызова (T8); переведены в MCP-ресурсы (см. ниже), чтобы не занимать слот в списке тулов, который агент читает при каждом запросе. Значения `category`, которые раньше приходилось узнавать через `list_categories()`, теперь прямо в описании `list_components`.
32
-
33
- ## Ресурсы
34
-
35
- - `daisforge-ui://catalog/categories` — категории каталога с количеством компонентов по типам (то же содержимое, что раньше отдавал тул `list_categories`)
36
- - `daisforge-ui://catalog/installation-guide` — гайд по установке и подключению `@daisforge/ui` (то же содержимое, что раньше отдавал тул `get_installation_guide`)
37
-
38
- Оба читаются через `resources/read` (`resources/list` — для обнаружения), контент — тот же JSON-формат, что и у тулов (`{ type: 'text', text: '<json>' }` → `{ uri, mimeType: 'application/json', text: '<json>' }`).
33
+ Одиннадцать тулов. Ресурсов (`resources/list`/`resources/read`) сервер не объявляет вовсе: `list_categories`/`get_installation_guide` были переведены в ресурсы в T8 (аргументов не принимают, контент не зависит от вызова) и возвращены в тулы в T16 — **ресурс агент может прочитать, только зная его URI заранее**, а список ресурсов, в отличие от списка тулов, сам в контекст агента не приходит. В транскриптах A/B-замера (40 прогонов с MCP, 279 вызовов инструментов) не было ни одного чтения ресурса.
39
34
 
40
35
  ## Ручное тестирование тулов (MCP Inspector)
41
36
 
@@ -89,20 +84,58 @@ npm run mcp:build-index
89
84
 
90
85
  Пропсы атомарных компонентов подмешиваются в `inheritedProps[]` из **закоммиченного статического снэпшота** (`vendor/atomic-mcp-data/`), а не через живой MCP атомарной команды — так наш сервер не зависит от установленного `@salutejs/sdds-mcp` и работает полностью оффлайн.
91
86
 
92
- Обновление снэпшота (вручную, при значимых апдейтах `@salutejs/sdds-finai`):
87
+ Обновление снэпшота — одной командой, без чужого чекаута:
93
88
 
94
89
  ```bash
95
- # в репозитории plasma, внутри website/sdds-finai-docs
96
- npm run generate-mcp-data
90
+ npm run mcp:vendor-atomic:check # сухой прогон: что приедет, ничего не пишется
91
+ npm run mcp:vendor-atomic # обновить снэпшот
92
+ npm run mcp:vendor-refresh # то же + следом собрать документацию (см. ниже)
93
+ ```
94
+
95
+ Данные тянутся с `https://plasma.sberdevices.ru/mcp/<lib>/<version>/` — **того же CDN, поверх которого работает официальный `@salutejs/sdds-mcp`** (в их npm-пакете лежит только `dist/`, данных нет; `MANIFEST_BASE_URL` в их `dist/config.js` указывает ровно сюда). В рантайме нашего MCP-сервера сеть по-прежнему не используется: снэпшот закоммичен, загрузка — только на этапе обновления.
96
+
97
+ Версия берётся **не `latest`, а та, что реально установлена** (`node_modules/@salutejs/sdds-finai/package.json`), чтобы индекс не обещал пропсы, которых у потребителя нет. Флаги:
98
+
99
+ | Флаг | Назначение |
100
+ | --- | --- |
101
+ | `--version <x.y.z\|latest>` | явная версия вместо установленной |
102
+ | `--on-missing keep\|latest\|fail` | что делать, если версии нет на CDN (по умолчанию `keep` — оставить текущий снэпшот и предупредить) |
103
+ | `--dry-run` | показать дифф, ничего не записывать |
104
+ | `--force` | разрешить даунгрейд (по умолчанию снэпшот нельзя перезаписать более старой версией) |
105
+ | `--lib`, `--base-url` | другая дизайн-система / другое зеркало CDN |
106
+ | `--source <dir>` | прежний офлайн-режим: взять локальный каталог `mcpData` вместо сети |
107
+
108
+ Что важно знать (подробно — `ARCHITECTURE.md` §1.6b):
109
+
110
+ - **Опубликованы не все версии.** `0.355.0`/`0.351.0` на CDN нет вовсе, и запрос несуществующей версии отвечает **301 на главную страницу сайта, которая отдаёт HTML с кодом 200** — поэтому скрипт не следует редиректам и проверяет форму каждого файла до записи. Пропущенная версия не валит релиз: срабатывает `--on-missing=keep`.
111
+ - **Бандл доков может быть новее одноимённого npm-пакета.** На `0.360.0` снэпшот принёс пропсы, которых в типах установленного `@salutejs/sdds-finai@0.360.0` нет (`Sheet.snapPoints`, `Modal.focusTrapSelectors`, `DatePicker.onChangeVisibleDate`, `Popover.stretchHeight`, `Skeleton.animationDuration`) — `mcp:validate-index` показывает их как +8 диагностик. Пин по версии нужен, но полной гарантии не даёт.
112
+ - **Со страницы доков берётся только первая таблица пропсов** — 14 таблиц (`AccordionItem`, `CalendarBase`, `Col`, `DatePickerRange`, `ListItem`, `NotificationsProvider`, `SegmentItem`, `RectSkeleton`/`TextSkeleton`, `TabItem`/`TabsController` и др.) в бандл не попадают вовсе, и перевендоринг этого не чинит — это дефект генератора атомарной команды.
113
+ - **`vendor/atomic-mcp-data/provenance.json`** (пишется скриптом, не приходит с CDN) фиксирует, откуда и когда взяты данные: `resolvedVersion`, `installedLibVersion`, `sourceUrl`, `fetchedAt`, счётчики по секциям и sha256 каждого файла.
114
+ - Помимо `components/` и `beta/` снэпшот теперь несёт **гайды** (`form`, `utils`, `tokens`, `how-to-icons`, `intro`, `FAQ`, `next`, `react_17`, `mcp`) — они складываются в снэпшот, но в индекс пока не попадают; секции берутся из самого манифеста, поэтому новая приедет сама.
97
115
 
98
- # в dais/ui
99
- npm run mcp:vendor-atomic -- --source /путь/к/plasma/website/sdds-finai-docs/mcpData
116
+ ## Документация атомарки (`vendor/atomic-docs/`)
117
+
118
+ В бандле на CDN прозы нет: их генератор режет `summary` компонента по 300 символов — медиана **44 символа**, у 34 из 74 компонентов остаётся голое имя. Текст берётся отдельно, из **первого** скрипта их же пайплайна (`generate-index`), где страница лежит целиком:
119
+
120
+ ```bash
121
+ npm run mcp:harvest-docs:check # сухой прогон
122
+ npm run mcp:harvest-docs # собрать документацию
123
+ ```
124
+
125
+ Скрипт делает sparse-чекаут тега `@salutejs/sdds-finai@<установленная версия>` (только каталог доков — 17 МБ), ставит пять парсер-пакетов в отдельную папку, прогоняет их `generateIndex` и раскладывает результат в `vendor/atomic-docs/<slug>.json` (`{name, slug, category, url, content}`). Весь цикл — **~10 секунд**, 87 страниц, 706 685 символов; медиана текста на компонент вырастает с 44 до **5 902** символов.
126
+
127
+ Сборка докусауруса не нужна: раскрытие `<PropsTable>` у них опционально (`fs.existsSync`), а пропсы у нас и так из ts-morph и с CDN. Недоступен GitHub или нет тега под версию — `::warning::` и каталог остаётся прежним (`--on-missing=keep`), релиз не падает. Флаги: `--version`, `--ref`, `--repo`, `--on-missing keep|fail`, `--dry-run`.
128
+
129
+ Обратная операция — склеить каталог в один файл ровно того формата, что отдаёт их `generateIndex` (`[{pageContent, metadata}]`, готово к заливке в векторную базу):
130
+
131
+ ```bash
132
+ npm run mcp:export-docs # → packages/mcp-server/.probe/atomic-docs-index.json
133
+ npm run mcp:export-docs -- --out /путь.json # свой путь
100
134
  ```
101
135
 
102
- Перед обновлением стоит знать две особенности снэпшота (подробно — `ARCHITECTURE.md` §1.6b):
136
+ По умолчанию пишет в `.probe/` (в `.gitignore`), чтобы в репозитории не лежала вторая копия тех же данных. Сверено с оригинальным выводом их скрипта: metadata совпадает 87/87, контент 83/87 — расхождение ровно на 4 страницы, которые менялись между тегом версии и `master`.
103
137
 
104
- - **`generate-mcp-data` даёт один файл на СТРАНИЦУ доков, не на атом**, и берёт со страницы только первую таблицу пропсов. В доках 87 таблиц `<PropsTable>` на 74 страницы — 14 таблиц (`AccordionItem`, `CalendarBase`, `Col`, `DatePickerRange`, `ListItem`, `NotificationsProvider`, `SegmentItem`, `RectSkeleton`/`TextSkeleton`, `TabItem`/`TabsController` и др.) в снэпшот не попадают вовсе. Прирост от перевендоринга будет заметным только вместе с исправлением их `extractProps`.
105
- - **Проверяйте версию**: `vendor/atomic-mcp-data/manifest.json` содержит версию `@salutejs/sdds-finai`, из которой собран текущий снэпшот (сейчас `0.355.0`, установленный в монорепо пакет — `0.351.0`). Прогон на более старом чекауте plasma перезапишет снэпшот более бедным — `vendorAtomicData.ts` сносит папку целиком и не сверяет версии.
138
+ **Пока это только сырьё**: в индекс проза не попадает и тулами не отдаётся — медиана 5.9k символов на компонент не помещается в карточку `get_component` при бюджете ответа 25k. Как отдавать (отдельный тул или клип со ссылкой на `url`) — отдельная задача.
106
139
 
107
140
  ## Курированные данные каталога (description/category/keywords)
108
141
 
@@ -125,7 +158,7 @@ npm run mcp:ab:app # собрать из ответов работающ
125
158
  npm run mcp:ab:selfcheck # поверка самого скорера, без запуска агента
126
159
  ```
127
160
 
128
- Последний замер (20 задач × 3 руки, sonnet): вызовов инструментов до первой строчки кода — **24.3 без MCP против 7.1 с MCP**, доля ответов, проходящих `tsc`, — **60% против 85%**. Разбор, оговорки и разрез по сложности задач — `ARCHITECTURE.md` §7, подробности харнесса — `ab/README.md`.
161
+ Последний замер (20 задач × 3 руки, sonnet): вызовов инструментов до первой строчки кода — **24.3 без MCP против 7.1 с MCP**, доля ответов, проходящих `tsc`, — **60% против 85%**. Разбор, оговорки и разрез по сложности задач — `ARCHITECTURE.md` §9, подробности харнесса — `ab/README.md`.
129
162
 
130
163
  ## Публикация
131
164
 
@@ -181,4 +214,4 @@ ALT_MCP_PACKAGE_NAME=@acme/ds-mcp ALT_LIB_PACKAGE_NAME=@acme/ds \
181
214
  - **Иконки, токены, миксины, утилиты не проиндексированы** — сознательная граница v1 (см. план). Следующий шаг.
182
215
  - **Три пары внутренних sub-компонентов с одинаковым именем** в разных папках (`TableFilterSelectListItem`, `ContainerStyled`, `Canvas` — есть и в `Table`/`TableCanvas`/`TableGlide`) — при коллизии имён в индекс попадает только последняя обработанная запись. Не влияет на публичные компоненты, только на внутренние helper-подкомпоненты таблиц.
183
216
  - **Поиск (`search_components`) — простой substring-скоринг**, без embeddings/NLP. Хорошо работает на прямых терминах и на курированных `hint`, слабее — на общих словах, которые встречаются во многих фичах одновременно (например "ячеек" — общее слово почти для всех табличных фич).
184
- - **`atomicDataMissing: true` у 35 записей из 243** — вендорных пропсов нет по двум причинам: у 11 таблица в доках атомарной команды есть, но не первая на своей странице, и снэпшот её теряет (`CalendarBase*`, `DatePickerRange`, `NotificationsProvider`, `SegmentItem`, `TextSkeleton`, `TabItem`, `TabsController`); у 24 таблицы нет в доках вовсе (`Divider` и его обёртки, compound-части `DrawerHeader`/`DrawerContent`/`DrawerFooter`, `Rating`, `SegmentIconItem`, `IconTabItem`, `ToastProvider`, `Typography` + 13 атомов типографики). Пропсы у всех 35 есть — из собственного резолва ts-morph, причём с описаниями и `required`, которых вендор не несёт вовсе. Сборка не падает, диагностика индексера помечает каждую дыру её причиной. Подробности — `ARCHITECTURE.md` §1.6b.
217
+ - **`atomicDataMissing: true` у 31 записи из 247** (было 34 до перевендоринга на `0.360.0`: у `Divider`, `ModalDFDivider` и `WidgetDivider` страница в доках появилась; `ToolbarDivider` остался — его `atomicBase` называется так же, как он сам, а страницы с таким именем нет) — вендорных пропсов нет по двум причинам: у 11 таблица в доках атомарной команды есть, но не первая на своей странице, и снэпшот её теряет (`CalendarBase*`, `DatePickerRange`, `NotificationsProvider`, `SegmentItem`, `TextSkeleton`, `TabItem`, `TabsController`); у остальных таблицы нет в доках вовсе (compound-части `DrawerHeader`/`DrawerContent`/`DrawerFooter`, `SegmentIconItem`, `IconTabItem`, `ToastProvider`, `Typography` + 13 атомов типографики). Пропсы у всех 31 есть — из собственного резолва ts-morph, причём с описаниями и `required`, которых вендор не несёт вовсе. Сборка не падает, диагностика индексера помечает каждую дыру её причиной. Подробности — `ARCHITECTURE.md` §1.6b.