@daisforge/ui-mcp 0.1.1

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.
Files changed (75) hide show
  1. package/README.md +140 -0
  2. package/data/component-index.json +45769 -0
  3. package/dist/indexer/buildIndex.js +323 -0
  4. package/dist/indexer/buildIndex.js.map +1 -0
  5. package/dist/indexer/classify.js +129 -0
  6. package/dist/indexer/classify.js.map +1 -0
  7. package/dist/indexer/classifyRole.js +58 -0
  8. package/dist/indexer/classifyRole.js.map +1 -0
  9. package/dist/indexer/collectUsageExamples.js +261 -0
  10. package/dist/indexer/collectUsageExamples.js.map +1 -0
  11. package/dist/indexer/diagnostics.js +85 -0
  12. package/dist/indexer/diagnostics.js.map +1 -0
  13. package/dist/indexer/discoverComponents.js +119 -0
  14. package/dist/indexer/discoverComponents.js.map +1 -0
  15. package/dist/indexer/htmlAttributeDenylist.js +254 -0
  16. package/dist/indexer/htmlAttributeDenylist.js.map +1 -0
  17. package/dist/indexer/indexFeatures.js +56 -0
  18. package/dist/indexer/indexFeatures.js.map +1 -0
  19. package/dist/indexer/indexTypes.js +44 -0
  20. package/dist/indexer/indexTypes.js.map +1 -0
  21. package/dist/indexer/mergeAtomicCuratedMeta.js +45 -0
  22. package/dist/indexer/mergeAtomicCuratedMeta.js.map +1 -0
  23. package/dist/indexer/mergeAtomicData.js +188 -0
  24. package/dist/indexer/mergeAtomicData.js.map +1 -0
  25. package/dist/indexer/mergeMeta.js +85 -0
  26. package/dist/indexer/mergeMeta.js.map +1 -0
  27. package/dist/indexer/parseComponent.js +715 -0
  28. package/dist/indexer/parseComponent.js.map +1 -0
  29. package/dist/indexer/resolveImportPath.js +69 -0
  30. package/dist/indexer/resolveImportPath.js.map +1 -0
  31. package/dist/indexer/synthesizeExample.js +41 -0
  32. package/dist/indexer/synthesizeExample.js.map +1 -0
  33. package/dist/indexer/tsProject.js +24 -0
  34. package/dist/indexer/tsProject.js.map +1 -0
  35. package/dist/indexer/vendorAtomicData.js +57 -0
  36. package/dist/indexer/vendorAtomicData.js.map +1 -0
  37. package/dist/indexer/vendorExamples.js +60 -0
  38. package/dist/indexer/vendorExamples.js.map +1 -0
  39. package/dist/indexer/vendorUsageExamples.js +111 -0
  40. package/dist/indexer/vendorUsageExamples.js.map +1 -0
  41. package/dist/resolveIndex.js +87 -0
  42. package/dist/resolveIndex.js.map +1 -0
  43. package/dist/server.js +114 -0
  44. package/dist/server.js.map +1 -0
  45. package/dist/tools/getComponent.js +99 -0
  46. package/dist/tools/getComponent.js.map +1 -0
  47. package/dist/tools/getComponentExamples.js +28 -0
  48. package/dist/tools/getComponentExamples.js.map +1 -0
  49. package/dist/tools/getComponentProps.js +60 -0
  50. package/dist/tools/getComponentProps.js.map +1 -0
  51. package/dist/tools/getFeature.js +19 -0
  52. package/dist/tools/getFeature.js.map +1 -0
  53. package/dist/tools/getFeatureExamples.js +27 -0
  54. package/dist/tools/getFeatureExamples.js.map +1 -0
  55. package/dist/tools/getInstallationGuide.js +8 -0
  56. package/dist/tools/getInstallationGuide.js.map +1 -0
  57. package/dist/tools/getType.js +34 -0
  58. package/dist/tools/getType.js.map +1 -0
  59. package/dist/tools/listCategories.js +19 -0
  60. package/dist/tools/listCategories.js.map +1 -0
  61. package/dist/tools/listComponents.js +51 -0
  62. package/dist/tools/listComponents.js.map +1 -0
  63. package/dist/tools/listFeatures.js +17 -0
  64. package/dist/tools/listFeatures.js.map +1 -0
  65. package/dist/tools/searchComponents.js +176 -0
  66. package/dist/tools/searchComponents.js.map +1 -0
  67. package/dist/tools/shared.js +39 -0
  68. package/dist/tools/shared.js.map +1 -0
  69. package/dist/tools/truncate.js +81 -0
  70. package/dist/tools/truncate.js.map +1 -0
  71. package/dist/types.js +9 -0
  72. package/dist/types.js.map +1 -0
  73. package/dist/validate/validateIndex.js +200 -0
  74. package/dist/validate/validateIndex.js.map +1 -0
  75. package/package.json +59 -0
package/README.md ADDED
@@ -0,0 +1,140 @@
1
+ # @daisforge/ui-mcp
2
+
3
+ MCP-сервер для `@daisforge/ui` — даёт кодовому агенту точные пропсы, типы, категории (wrapper/composition/standalone/form) и примеры для 260+ компонентов библиотеки, а не только для ~40 задокументированных в Storybook. `description`/`category`/`keywords` для выбора компонента под задачу заполнены у всех 243 неошибочных записей индекса (T2), не только у тех, что описаны в Storybook.
4
+
5
+ ## Быстрый старт
6
+
7
+ Внутри монорепо dais/ui сервер уже зарегистрирован в корневом `.mcp.json` — ничего дополнительно делать не нужно.
8
+
9
+ Для потребителей (`npm install @daisforge/ui @daisforge/ui-mcp`):
10
+
11
+ ```json
12
+ {
13
+ "mcpServers": {
14
+ "daisforge-ui": {
15
+ "command": "node",
16
+ "args": ["node_modules/@daisforge/ui-mcp/dist/server.js"]
17
+ }
18
+ }
19
+ }
20
+ ```
21
+
22
+ ## Инструменты
23
+
24
+ - `list_components({ type?, category?, scope?, role?, limit?, offset? })` — ответ `{ items, shown, total, hasMore?, truncationNotice? }`. По умолчанию отдаёт только `role: "primary"` (~177 из 243 компонентов) — слоты вроде `DrawerDFHeader` и служебные примитивы вроде `CanvasRect` скрыты; `role: "all"` снимает фильтр. Каждый элемент несёт `description`/`category` (100% покрытие, см. T2 в `TASKS.MD`); `keywords` в этом компактном списке **не** дублируются — они участвуют в скоринге `search_components`, а не в беглом обзоре. Без `limit` список сам бюджетируется под лимит ответа: с полными description/category у всех 177 primary-компонентов за один вызов без фильтров помещается ~120 из них — это ожидаемо (не баг), `truncationNotice` объясняет, чем добрать остаток (фильтры или `limit`/`offset`)
25
+ - `search_components({ query })` — ищет и по компонентам, и по фичам (TableCanvas/Filtering и т.п.); скорит `hint`, `keywords` (2-4 синонима задачи на ru/en на компонент) и `description` — `keywords` весят наравне с `hint` (+20); `role: "internal"` понижается штрафом, но не исключается. Результаты по компонентам несут `supersededBy`/`chooseWhen`, если заполнены — выбор между конкурирующими компонентами происходит именно здесь (T9)
26
+ - `get_component({ name })` — компактная карточка, несёт `description`/`category`/`keywords`. У `part`/`internal`-записей — `parentComponent` (куда идти за деталями); у владельца папки — `relatedExports` (какие части/внутренние примитивы у него есть, раз их не видно в `list_components` по умолчанию); у записей, дублирующих compound-часть родителя (`compoundPartOf`), пропсы не повторяются — карточка сразу отсылает к `get_component_props({ name: parent, part })`. `minimalUsage` — синтетический `<Component requiredProp={...} />` из обязательных пропсов, есть у 100% записей всегда; `exampleTitles` — заголовки настоящих примеров (может быть `[]`, это честное «примеров нет», не повод звать `get_component_examples`). У `legacy: true` — `supersededBy` (что брать вместо); у компонентов из конкурирующих групп (`Table`/`TableCanvas`, `Select`/`FormSelect`, `Popover`/`PopoverBeta` и т.п., 34 компонента) — `chooseWhen`, одна строка, при каких условиях брать именно этот (T9)
27
+ - `get_component_props({ name, part? })` — полные пропсы (собственные + унаследованные от атома). Пропсы отсортированы: `required` → с описанием → без описания → `deprecated` в конец, по алфавиту внутри яруса (T7) — при обрезке по бюджету теряется наименее нужное, а не случайное подмножество. Описания, дословно совпадающие с JSDoc React DOM-типизации того же имени, не попадают в индекс (T7). У части пропсов есть `default` — значение по умолчанию, извлечённое из деструктуризации параметра render-функции или тега `@default` в JSDoc (T6); поле опционально, отсутствует, если дефолт не резолвлен
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
+ - `list_features({ component })`, `get_feature({ component, feature })`, `get_feature_examples({ component, feature, title? })`
30
+
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>' }`).
39
+
40
+ ## Ручное тестирование тулов (MCP Inspector)
41
+
42
+ Чтобы точечно повызывать любой тул (`get_component`, `search_components` и т.д.) через UI, без настройки клиента:
43
+
44
+ ```bash
45
+ npm run mcp:inspect
46
+ ```
47
+
48
+ Команда собирает сервер (`tsc`) и поднимает [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector) (через `npx`, ничего не ставится в зависимости проекта) — откроется браузер со списком тулов, формой аргументов под каждый и живым JSON-ответом. Сервер запускается как stdio-процесс (`node ./dist/server.js`), сеть наружу не используется.
49
+
50
+ Тот же скрипт есть и в корне монорепо: `npm run mcp:inspect` (пересобирает индекс перед запуском).
51
+
52
+ ## Разработка
53
+
54
+ ```bash
55
+ npx nx typecheck @daisforge/ui-mcp # tsc --noEmit
56
+ npx nx lint @daisforge/ui-mcp # eslint (тот же конфиг, что и у остальных пакетов монорепо)
57
+ npx nx build @daisforge/ui-mcp # tsc -p tsconfig.lib.json → dist/
58
+ ```
59
+
60
+ `ts-morph` — devDependency (нужна только индексеру на этапе сборки индекса, не публикуется в рантайме MCP-сервера); соответствующее исключение для `import/no-extraneous-dependencies` настроено в `.eslintrc.json` только для `src/indexer/**`.
61
+
62
+ ## Сборка индекса
63
+
64
+ ```bash
65
+ npm run mcp:build-index
66
+ ```
67
+
68
+ Пишет `packages/mcp-server/data/component-index.json` (запасной индекс, вшивается в публикуемый `@daisforge/ui-mcp`) и, если уже собран `dist/packages/ui-kit` — также `dist/packages/ui-kit/mcp-data/component-index.json` (уезжает вместе с публикацией `@daisforge/ui`). Автоматически запускается после `npm run build` (см. корневой `postbuild`).
69
+
70
+ ## Резолв индекса — три уровня
71
+
72
+ 1. **workspace** — если рядом физически лежит `packages/ui-kit` (мы внутри монорепо), сервер читает свежесобранный локальный индекс.
73
+ 2. **installed** — версия `@daisforge/ui`, установленная у потребителя, уже содержит `mcp-data/component-index.json`.
74
+ 3. **bundled** — запасной индекс, вшитый в сам `@daisforge/ui-mcp`. Нужен для версий `@daisforge/ui`, опубликованных до появления mcp-data (то есть всех текущих!), и для случая, когда библиотека вообще не установлена. В этом случае в ответах присутствует `dataVersionNotice`/`libNotInstalled`.
75
+
76
+ Всё работает полностью оффлайн — сервер никогда не обращается по сети.
77
+
78
+ ## Атомарный слой (`@salutejs/sdds-finai`)
79
+
80
+ Пропсы атомарных компонентов подмешиваются в `inheritedProps[]` из **закоммиченного статического снэпшота** (`vendor/atomic-mcp-data/`), а не через живой MCP атомарной команды — так наш сервер не зависит от установленного `@salutejs/sdds-mcp` и работает полностью оффлайн.
81
+
82
+ Обновление снэпшота (вручную, при значимых апдейтах `@salutejs/sdds-finai`):
83
+
84
+ ```bash
85
+ # в репозитории plasma, внутри website/sdds-finai-docs
86
+ npm run generate-mcp-data
87
+
88
+ # в dais/ui
89
+ npm run mcp:vendor-atomic -- --source /путь/к/plasma/website/sdds-finai-docs/mcpData
90
+ ```
91
+
92
+ Перед обновлением стоит знать две особенности снэпшота (подробно — `ARCHITECTURE.md` §1.6b):
93
+
94
+ - **`generate-mcp-data` даёт один файл на СТРАНИЦУ доков, не на атом**, и берёт со страницы только первую таблицу пропсов. В доках 87 таблиц `<PropsTable>` на 74 страницы — 14 таблиц (`AccordionItem`, `CalendarBase`, `Col`, `DatePickerRange`, `ListItem`, `NotificationsProvider`, `SegmentItem`, `RectSkeleton`/`TextSkeleton`, `TabItem`/`TabsController` и др.) в снэпшот не попадают вовсе. Прирост от перевендоринга будет заметным только вместе с исправлением их `extractProps`.
95
+ - **Проверяйте версию**: `vendor/atomic-mcp-data/manifest.json` содержит версию `@salutejs/sdds-finai`, из которой собран текущий снэпшот (сейчас `0.349.0`). Прогон на более старом чекауте plasma перезапишет снэпшот более бедным — `vendorAtomicData.ts` сносит папку целиком и не сверяет версии.
96
+
97
+ ## Курированные данные каталога (description/category/keywords)
98
+
99
+ Индексер сам находит компоненты, пропсы и типы из исходников, но `description`/`category`/`keywords` — курированный контент, у которого два независимых редактируемых источника (оба читаются на этапе `mcp:build-index`, сами по себе НЕ индексер):
100
+
101
+ 1. **`generators/meta-info/config/meta-config.json`** (поле `components`) — для компонентов с собственным кодом в `ui-kit` (wrapper/composition/standalone с реальной логикой поверх атома или самостоятельной реализацией). Этот файл — вход генератора `npm run meta` (`generators/meta-info/generate-meta.js`), который пишет `_docs/meta/components-meta.json`. **`_docs/meta/components-meta.json` — build-артефакт, полностью перезаписывается при каждом `npm run meta` — редактировать его руками нельзя**, правки делаются только в `meta-config.json`. `mergeMeta.ts` читает уже сгенерированный `_docs/meta/components-meta.json`.
102
+ 2. **`packages/mcp-server/vendor/atomic-curated-meta.json`** — для компонентов без единой строчки собственного кода: чистых реэкспортов атомов `@salutejs/sdds-finai` (`export { X } from '@salutejs/sdds-finai'`). У них нет ни JSDoc, ни своей Storybook-страницы, поэтому `generators/meta-info` их не видит в принципе (резолвит по папке в `packages/storybook/src/stories/<Name>/`, которой у реэкспортов нет). Читается напрямую через `mergeAtomicCuratedMeta.ts`, идёт сразу за `mergeMeta` в пайплайне `buildIndex.ts` — независимый источник, не проходит через генератор `npm run meta`.
103
+
104
+ Оба источника — "curated wins": непустое значение перекрывает то, что нашёл индексер сам (JSDoc-описание, эвристику `category`).
105
+
106
+ ## A/B-замер: помогает ли индекс
107
+
108
+ `npm run mcp:validate-index` проверяет, что индекс не врёт. Проверка того, что он **помогает**, живёт в `ab/` — одни и те же 20 задач на генерацию кода решаются агентом с MCP и без, в обстановке настоящего потребителя (песочница вне репозитория с опубликованным `@daisforge/ui` из npm, без исходников библиотеки).
109
+
110
+ ```bash
111
+ npm run mcp:ab:consumer # собрать стенд потребителя
112
+ npm run mcp:ab:drift # карта расхождений «индекс ↔ установленный пакет»
113
+ npm run mcp:ab # прогон + метрики (.probe/ab/report.md)
114
+ npm run mcp:ab:app # собрать из ответов работающее приложение + vite build
115
+ npm run mcp:ab:selfcheck # поверка самого скорера, без запуска агента
116
+ ```
117
+
118
+ Последний замер (20 задач × 3 руки, sonnet): вызовов инструментов до первой строчки кода — **24.3 без MCP против 7.1 с MCP**, доля ответов, проходящих `tsc`, — **60% против 85%**. Разбор, оговорки и разрез по сложности задач — `ARCHITECTURE.md` §7, подробности харнесса — `ab/README.md`.
119
+
120
+ ## Публикация
121
+
122
+ `@daisforge/ui-mcp` версионируется и публикуется **независимо** от `@daisforge/ui` — не через Lerna (пакет не входит в npm workspaces и не виден `lerna version`), а через отдельный workflow `.github/workflows/publish-mcp-server.yml`.
123
+
124
+ Запуск — вручную, из Actions UI или через `gh`:
125
+
126
+ ```bash
127
+ gh workflow run publish-mcp-server.yml -f bump=patch -f dry_run=true # проверочный прогон, ничего не публикует
128
+ gh workflow run publish-mcp-server.yml -f bump=patch -f dry_run=false # реальный релиз
129
+ ```
130
+
131
+ `bump` — `patch`/`minor`/`major`. Workflow сам поднимает версию в `package.json` (`npm version`), коммитит и тегирует (`ui-mcp-vX.Y.Z` — отдельный неймспейс от тегов `ui-kit`, `vX.Y.Z`), затем публикует в тот же `registry.npmjs.org`, что и `@daisforge/ui`.
132
+
133
+ Workflow объявлен и как `workflow_call` — задел на будущее, если релиз `ui-mcp` решат триггерить автоматически из `publish-npm.yml` вместо ручного запуска.
134
+
135
+ ## Известные ограничения v1
136
+
137
+ - **Иконки, токены, миксины, утилиты не проиндексированы** — сознательная граница v1 (см. план). Следующий шаг.
138
+ - **Три пары внутренних sub-компонентов с одинаковым именем** в разных папках (`TableFilterSelectListItem`, `ContainerStyled`, `Canvas` — есть и в `Table`/`TableCanvas`/`TableGlide`) — при коллизии имён в индекс попадает только последняя обработанная запись. Не влияет на публичные компоненты, только на внутренние helper-подкомпоненты таблиц.
139
+ - **Поиск (`search_components`) — простой substring-скоринг**, без embeddings/NLP. Хорошо работает на прямых терминах и на курированных `hint`, слабее — на общих словах, которые встречаются во многих фичах одновременно (например "ячеек" — общее слово почти для всех табличных фич).
140
+ - **`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.