@daisforge/ui-mcp 0.2.3 → 0.2.4
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 +51 -18
- package/data/component-index.json +1903 -632
- package/dist/indexer/exportAtomicDocs.js +91 -0
- package/dist/indexer/exportAtomicDocs.js.map +1 -0
- package/dist/indexer/harvestAtomicDocs.js +272 -0
- package/dist/indexer/harvestAtomicDocs.js.map +1 -0
- package/dist/indexer/vendorAtomicData.js +519 -38
- package/dist/indexer/vendorAtomicData.js.map +1 -1
- package/dist/indexer/vendorShared.js +132 -0
- package/dist/indexer/vendorShared.js.map +1 -0
- package/dist/resolveIndex.js +1 -1
- package/dist/resolveIndex.js.map +1 -1
- package/dist/server.js +9 -29
- package/dist/server.js.map +1 -1
- package/package.json +1 -1
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
|
-
|
|
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
|
-
Обновление снэпшота
|
|
87
|
+
Обновление снэпшота — одной командой, без чужого чекаута:
|
|
93
88
|
|
|
94
89
|
```bash
|
|
95
|
-
#
|
|
96
|
-
npm run
|
|
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
|
-
|
|
99
|
-
|
|
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
|
-
|
|
136
|
+
По умолчанию пишет в `.probe/` (в `.gitignore`), чтобы в репозитории не лежала вторая копия тех же данных. Сверено с оригинальным выводом их скрипта: metadata совпадает 87/87, контент 83/87 — расхождение ровно на 4 страницы, которые менялись между тегом версии и `master`.
|
|
103
137
|
|
|
104
|
-
|
|
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` §
|
|
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` у
|
|
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.
|