@daisforge/ui-mcp 0.2.12 → 0.2.14
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 +110 -5
- package/data/component-index.json +20458 -17896
- package/dist/indexer/buildIndex.js +26 -18
- package/dist/indexer/buildIndex.js.map +1 -1
- package/dist/indexer/classify.js +1 -0
- package/dist/indexer/classify.js.map +1 -1
- package/dist/indexer/discoverComponents.js +11 -1
- package/dist/indexer/discoverComponents.js.map +1 -1
- package/dist/indexer/htmlAttributeDenylist.js +8 -2
- package/dist/indexer/htmlAttributeDenylist.js.map +1 -1
- package/dist/indexer/indexTypes.js +24 -1
- package/dist/indexer/indexTypes.js.map +1 -1
- package/dist/indexer/mergeAtomicData.js +24 -24
- package/dist/indexer/mergeAtomicData.js.map +1 -1
- package/dist/indexer/parseComponent.js +141 -61
- package/dist/indexer/parseComponent.js.map +1 -1
- package/dist/indexer/publicContract.js +71 -0
- package/dist/indexer/publicContract.js.map +1 -0
- package/dist/indexer/resolveImportPath.js +36 -12
- package/dist/indexer/resolveImportPath.js.map +1 -1
- package/dist/indexer/synthesizeExample.js +38 -6
- package/dist/indexer/synthesizeExample.js.map +1 -1
- package/dist/indexer/typeDisplay.js +93 -0
- package/dist/indexer/typeDisplay.js.map +1 -0
- package/dist/server.js +5 -10
- package/dist/server.js.map +1 -1
- package/dist/toolResponse.js +9 -0
- package/dist/toolResponse.js.map +1 -0
- package/dist/tools/getComponent.js +4 -5
- package/dist/tools/getComponent.js.map +1 -1
- package/dist/tools/getComponentExamples.js +4 -6
- package/dist/tools/getComponentExamples.js.map +1 -1
- package/dist/tools/getComponentProps.js +9 -9
- package/dist/tools/getComponentProps.js.map +1 -1
- package/dist/tools/getFeature.js +2 -3
- package/dist/tools/getFeature.js.map +1 -1
- package/dist/tools/getFeatureExamples.js +3 -6
- package/dist/tools/getFeatureExamples.js.map +1 -1
- package/dist/tools/getInstallationGuide.js +2 -1
- package/dist/tools/getInstallationGuide.js.map +1 -1
- package/dist/tools/getType.js +11 -19
- package/dist/tools/getType.js.map +1 -1
- package/dist/tools/listFeatures.js +2 -1
- package/dist/tools/listFeatures.js.map +1 -1
- package/dist/tools/searchComponents.js +4 -3
- package/dist/tools/searchComponents.js.map +1 -1
- package/dist/tools/searchVocabulary.js +21 -0
- package/dist/tools/searchVocabulary.js.map +1 -0
- package/dist/types.js +9 -2
- package/dist/types.js.map +1 -1
- package/dist/validate/auditContracts.js +255 -0
- package/dist/validate/auditContracts.js.map +1 -0
- package/dist/validate/knownOpenContracts.js +4 -0
- package/dist/validate/knownOpenContracts.js.map +1 -0
- package/dist/validate/openContractAudit.js +93 -0
- package/dist/validate/openContractAudit.js.map +1 -0
- package/dist/validate/validateIndex.js +150 -173
- package/dist/validate/validateIndex.js.map +1 -1
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# @daisforge/ui-mcp
|
|
2
2
|
|
|
3
|
-
MCP-сервер для `@daisforge/ui`
|
|
3
|
+
MCP-сервер для `@daisforge/ui` предоставляет кодовому агенту пропсы, типы,
|
|
4
|
+
категории, примеры и поиск по компонентам и возможностям библиотеки.
|
|
4
5
|
|
|
5
6
|
## Источники данных
|
|
6
7
|
|
|
@@ -12,8 +13,8 @@ MCP-сервер для `@daisforge/ui` — даёт кодовому агент
|
|
|
12
13
|
Версии, источники и контрольные суммы записаны в
|
|
13
14
|
`vendor/atomic-docs/provenance.json` и `vendor/atomic-mcp-data/provenance.json`.
|
|
14
15
|
Поле `installedLibVersion` относится к моменту загрузки снимка.
|
|
15
|
-
|
|
16
|
-
|
|
16
|
+
Ошибки API, конфигурации и запуска TypeScript приводят к ненулевому коду
|
|
17
|
+
`mcp:validate-index`. Известные открытые контракты выводятся как предупреждения.
|
|
17
18
|
|
|
18
19
|
## Быстрый старт
|
|
19
20
|
|
|
@@ -75,6 +76,10 @@ npm run mcp:build-index
|
|
|
75
76
|
|
|
76
77
|
Пишет `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`).
|
|
77
78
|
|
|
79
|
+
Если для обнаруженного компонента не удаётся подтвердить публичный импорт,
|
|
80
|
+
индексер сообщает его имя и останавливает сборку. Это защищает MCP и пакеты UI
|
|
81
|
+
от публикации индекса с заведомо нерабочим импортом.
|
|
82
|
+
|
|
78
83
|
### Курированная мета — обязательный вход, а не опция
|
|
79
84
|
|
|
80
85
|
`_docs/meta/components-meta.json` лежит в `.gitignore` (это build-артефакт `npm run meta`), поэтому на свежем клоне и в CI его нет. Без него из индекса молча исчезает всё, что приходит только оттуда: **features** (77 записей, 46 из них у одного `TableCanvas`), **guides.installation**, curated-описания/`keywords`/`chooseWhen` ui-kit компонентов и все примеры типа **full-code**. Ровно такой выпотрошенный индекс уехал в npm `0.1.1` — у потребителя `list_features` отвечал `0`, а поиск по фичам не находил ничего.
|
|
@@ -225,6 +230,106 @@ ALT_MCP_PACKAGE_NAME=@acme/ds-mcp ALT_LIB_PACKAGE_NAME=@acme/ds \
|
|
|
225
230
|
## Известные ограничения v1
|
|
226
231
|
|
|
227
232
|
- **Иконки, токены, миксины, утилиты не проиндексированы** — сознательная граница v1 (см. план). Следующий шаг.
|
|
228
|
-
- **Три пары внутренних sub-компонентов с одинаковым именем** в разных папках (`TableFilterSelectListItem`, `ContainerStyled`, `Canvas` — есть и в `Table`/`TableCanvas`/`TableGlide`) — при коллизии имён в индекс попадает только последняя обработанная запись. Не влияет на публичные компоненты, только на внутренние helper-подкомпоненты таблиц.
|
|
229
233
|
- **Поиск (`search_components`) — простой substring-скоринг**, без embeddings/NLP. Хорошо работает на прямых терминах и на курированных `hint`, слабее — на общих словах, которые встречаются во многих фичах одновременно (например "ячеек" — общее слово почти для всех табличных фич).
|
|
230
|
-
- **`atomicDataMissing: true
|
|
234
|
+
- **`atomicDataMissing: true`** означает, что в снимке SDDS нет API-таблицы
|
|
235
|
+
атома. Пропсы в этом случае берутся из публичных типов, а диагностика
|
|
236
|
+
индексера указывает причину отсутствия таблицы. Подробности в `ARCHITECTURE.md` §1.6b.
|
|
237
|
+
|
|
238
|
+
## Проверка MCP перед PR
|
|
239
|
+
|
|
240
|
+
Из корня после установки зависимостей:
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
npm run mcp:ci
|
|
244
|
+
npm run mcp:check
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
`mcp:check` пересобирает индекс и запускает lint, тесты, проверку API и поиска.
|
|
248
|
+
В pull request она запускается на Linux и Windows. Workflow публикации MCP
|
|
249
|
+
выполняет её перед изменением версии пакета. `mcp:ci` устанавливает зависимости
|
|
250
|
+
из lockfile.
|
|
251
|
+
|
|
252
|
+
- Контракты берутся из публичных экспортов установленной библиотеки. Объект `Canvas`
|
|
253
|
+
имеет `apiKind: "namespace"`: используйте `get_component_props({name: "Canvas", part: "Text"})`.
|
|
254
|
+
Классы движка Canvas и непубличные DataEditor/TableGlide/RootBridge не являются
|
|
255
|
+
отдельными компонентами каталога. API Canvas сохранён в его 15 JSX-частях и фичах TableCanvas.
|
|
256
|
+
- Обязательные props сохраняются, даже если совпадают с DOM-атрибутами по имени
|
|
257
|
+
и типу. Для полей из документации SDDS сверяем наличие, тип и обязательность с
|
|
258
|
+
полным публичным контрактом. Из снимка SDDS берём дополнительные описания,
|
|
259
|
+
значения по умолчанию и примеры.
|
|
260
|
+
- Валидатор проверяет все публичные импорты, включая компоненты без props; различает
|
|
261
|
+
namespace и компонент, учитывает styled-перегрузки и все ветви union. Ошибки в исходниках,
|
|
262
|
+
конфигурации, запуске компилятора и новые открытые контракты также приводят к провалу.
|
|
263
|
+
- Некоторые исходные типы допускают произвольные ключи. Явно объявленные поля
|
|
264
|
+
проверяются на наличие, тип и `required`; закрытость всего контракта доказать нельзя. Они явно перечислены в `src/validate/knownOpenContracts.ts`, выводятся как
|
|
265
|
+
предупреждения в отчёте и в `get_component_props`. Это ограничение покрытия, а не
|
|
266
|
+
утверждение, что неизвестные поля корректны. Список нельзя расширять ради зелёного CI;
|
|
267
|
+
сначала необходимо подтвердить открытый контракт и причину. Для полной проверки нужно
|
|
268
|
+
уточнить исходные публичные типы этих компонентов.
|
|
269
|
+
- Полный JSON-отчёт и вывод TypeScript: `.probe/validation-report.json` и
|
|
270
|
+
`.probe/validation-tsc.log`. CI хранит их семь дней в артефакте
|
|
271
|
+
`mcp-validation-<os>` вместе с отчётом по примерам каталога.
|
|
272
|
+
- Тест с намеренно испорченным индексом проверяет неверный экспорт, несуществующий проп,
|
|
273
|
+
ошибочный `required`, выдуманную часть и потерю публичной `Canvas.Image`. Он пишет
|
|
274
|
+
диагностический отчёт; следующий шаг `mcp:validate-index` заменяет его итогом для
|
|
275
|
+
настоящего индекса.
|
|
276
|
+
- Поиск проверяется 22 запросами на русском и английском, включая квалифицированные
|
|
277
|
+
имена типов. Любой промах возвращает ненулевой код; критерий — нужная сущность в топ-3.
|
|
278
|
+
- Протокольные тесты запускают настоящий stdio-сервер, проверяют все 11 инструментов,
|
|
279
|
+
версию пакета и `isError` для ошибочных запросов.
|
|
280
|
+
|
|
281
|
+
Проверка использует исходники через локальные алиасы. Перед релизом дополнительно
|
|
282
|
+
проверяйте установленные tarball-пакеты в отдельном потребителе: резолв опубликованных
|
|
283
|
+
путей и выбор индекса `workspace / installed / bundled` — отдельный уровень проверки.
|
|
284
|
+
|
|
285
|
+
## Независимые проверки контрактов
|
|
286
|
+
|
|
287
|
+
`npm test --prefix packages/mcp-server` теперь включает `test:consumer`:
|
|
288
|
+
ручные положительные и отрицательные JSX-примеры из `test/consumer.test.tsx`.
|
|
289
|
+
Они импортируют публичные `@daisforge/ui` пути, не используют helper индексера,
|
|
290
|
+
проверяют Box, Spinner, формы, TableCanvas/TableContract, Canvas и открытые контракты.
|
|
291
|
+
В том же файле компилируются четыре типа, полученные непосредственно через
|
|
292
|
+
`get_component_props`: ширина Spinner/Drawer, opened и callback фильтра.
|
|
293
|
+
Ожидания к допустимым значениям написаны вручную. Если неверный пример перестаёт
|
|
294
|
+
вызывать ошибку, `@ts-expect-error` делает весь прогон неуспешным.
|
|
295
|
+
Отдельно TypeScript компилирует импорты и `minimalUsage` из ответов
|
|
296
|
+
`get_component` для всех компонентов группы форм, `TableFilterSelect` и
|
|
297
|
+
`TableContract`. Тесты ответов MCP проверяют обязательный `name` у форм и базовые
|
|
298
|
+
props SDDS.
|
|
299
|
+
|
|
300
|
+
Для диагностики всего каталога запустите
|
|
301
|
+
`npm run test:consumer:report --prefix packages/mcp-server` после сборки индекса.
|
|
302
|
+
Команда сохраняет диагностику по компонентам в `.probe/minimal-usage-report.json`.
|
|
303
|
+
Ошибки в примерах записываются в отчёт. Сбой конфигурации или компиляции исходников
|
|
304
|
+
останавливает команду.
|
|
305
|
+
|
|
306
|
+
`mcp:validate-index` дополнительно выполняет `auditContracts.ts`. Он независимо
|
|
307
|
+
обходит публичные декларации (без `parseComponent` и `PUBLIC_PROPS_HELPERS`),
|
|
308
|
+
сравнивает имена полей в обе стороны, отображаемые типы и обязательность.
|
|
309
|
+
Ожидаемые JSX-части `Canvas` аудит получает из публичного контракта.
|
|
310
|
+
Политика фильтрации DOM-полей и формат отображения общие. Тесты ответов MCP
|
|
311
|
+
проверяют нужные поля напрямую и обнаруживают их исчезновение даже при ошибке
|
|
312
|
+
в общем фильтре.
|
|
313
|
+
Отдельный тест проверяет нормализацию типов на взаимную assignability с исходной
|
|
314
|
+
записью, включая функции, union и строковые литералы с пробелами.
|
|
315
|
+
|
|
316
|
+
46 открытых контрактов разобраны в [OPEN-CONTRACTS.md](OPEN-CONTRACTS.md).
|
|
317
|
+
Они не исключены из аудита: проверяются их именованные поля. Для шести записей
|
|
318
|
+
FiltersActions отдельно используется именованный Props-тип исходника, поскольку
|
|
319
|
+
styled стирает его в публичной сигнатуре. Этот источник выделен в отчёте и не
|
|
320
|
+
выдаётся за гарантию того, что JSX отвергает неправильное значение.
|
|
321
|
+
Новые и устаревшие исключения, а также не подтверждённые декларациями поля индекса
|
|
322
|
+
проваливают проверку.
|
|
323
|
+
|
|
324
|
+
В `validation-report.json` поле `contractCoverage` показывает для каждой записи
|
|
325
|
+
`checkedProps`, `declaredProps`, `unverifiedProps`, `truncatedProps`, а для открытых
|
|
326
|
+
контрактов — причину и исходный файл. `unverifiedProps` — ошибка, а не разрешённый skip.
|
|
327
|
+
Длинный отображаемый тип обрезается до 400 символов: аудит сравнивает его канонический
|
|
328
|
+
видимый фрагмент и отдельно отмечает это ограничение. Он не доказывает эквивалентность
|
|
329
|
+
всех вложенных структур за пределами фрагмента или корректность всех записей `get_type`.
|
|
330
|
+
Плоский список props также не описывает все связи между ветвями union: например,
|
|
331
|
+
у Spinner размеры допустимы парой. Это дополнительно проверяется настоящим JSX.
|
|
332
|
+
|
|
333
|
+
Резолв публичных импортов в consumer-тесте идёт к исходникам через paths. Проверка
|
|
334
|
+
package exports собранного UI tarball и рендеринг в браузере остаются отдельными
|
|
335
|
+
уровнями проверки; данные тесты не подменяют их.
|