@sky.ui/mcp 0.0.1 → 0.0.2

package/docs/utils-usage-guide.md

@@ -1,110 +1,112 @@
-# Using @sky.ui/utils
-
-Sky UI utilities are **JIT CSS classes** you add in HTML/JSX/Vue/Lit templates (`class` / `className`). A **PostCSS plugin** scans your project, reads **`skyui.config.js`**, and emits only the CSS you use.
-
-## Install
-
-```bash
-npm install @sky.ui/utils postcss
-```
-
-Register in PostCSS (exact wiring depends on your bundler — use MCP **`get_project_guide`** with `kind: setup`):
-
-```js
-import skyui from '@sky.ui/utils/postcss';
-
-export default {
-  plugins: [skyui()]
-};
-```
-
-**Peer dependency:** `postcss` >= 8.4.
-
-## Public imports
-
-| Import | Use |
-| --- | --- |
-| `@sky.ui/utils` / `@sky.ui/utils/postcss` | PostCSS plugin (**`SkyUIPlugin`**) |
-| `@sky.ui/utils/vite` | Vite integration |
-| `@sky.ui/utils/css-data` | VS Code `css.customData` — silences “Unknown at rule” for `@apply` / `@skyui` |
-| `@sky.ui/utils/suggestion-engine` | Editor completions (optional) |
-| `@sky.ui/utils/prettier-plugin` | Sort class strings in `class` / `@apply` |
-| `@sky.ui/utils/runtime` | Browser **`skyui`** helper for static pages |
-
-## `skyui.config.js`
-
-Typical fields:
-
-| Field | Purpose |
-| --- | --- |
-| `content` | Globs of files to scan for class names |
-| `safelist` | Classes always generated (strings or `{ pattern, variants }`) |
-| `plugins` | Built-ins such as `@skyuicss/forms`, `@skyuicss/typography`, `@skyuicss/container-queries` |
-| `theme` / `theme.extend` | Colors, spacing, screens, `preflight`, `formsStrategy`, animations |
-| `breakpoints` | Screen map for `sm:`, `md:`, … |
-
-The plugin discovers config by walking up from the processed CSS file.
-
-## VS Code CSS validation
-
-Add to `.vscode/settings.json` so `@apply` and `@skyui` are not flagged as unknown at-rules:
-
-```json
-{
-  "css.customData": ["./node_modules/@sky.ui/utils/skyui.css-data.json"]
-}
-```
-
-Or install the **Sky UI IntelliSense** extension (bundles the same custom data).
-
-## CSS layers and `@skyui` directives
-
-Declare layer order once:
-
-```css
-@layer skyui.base, skyui.components, skyui.utilities;
-@skyui utilities;
-```
-
-| Directive | Purpose |
-| --- | --- |
-| `@apply` | Compose utilities inside component CSS |
-| `@skyui theme { … }` | CSS-first design tokens |
-| `@skyui source "glob"` | Extra scan paths |
-| `@skyui source inline("a b")` | Safelist in CSS |
-| `@skyui reference` | Tokens only in scoped styles (pair with global utilities) |
-| `@skyui utility` / `@skyui variant` | Custom utility or variant |
-| `@skyui plugin "…"` | Load a plugin spec |
-
-## Built-in plugins (`@skyuicss/*`)
-
-| Spec | Role |
-| --- | --- |
-| `@skyuicss/forms` | Form control utilities; optional `formsStrategy`: `class` \| `base` \| `both` |
-| `@skyuicss/typography` | `prose` utilities (`--sky-prose-*` variables) |
-| `@skyuicss/container-queries` | Container-query variants from theme screens |
-
-Short aliases: `forms`, `typography`, `container-queries`.
-
-## Preflight
-
-`theme.preflight`: `true` | `"minimal"` | `"full"` — optional base reset in `@layer skyui.base` (default off).
-
-## Variants (common families)
-
-Responsive (`sm:`, `md:`, `max-sm:`), dark/light, state (`hover:`, `focus:`, `disabled:`), `not-*`, `group-*` / `peer-*`, `starting:`, `aria-*`, arbitrary (`has-[…]:`, `[&…]:`).
-
-Use MCP **`utility_classes`** (`operation: variant_prefixes`) for the full prefix list, **`search_classes`** to browse names, **`check_class`** to validate a token.
-
-## Theme alignment with components
-
-Use MCP **`get_theme`** — start with **`operation: guide`**, then **`fields`** / **`field`** for `userTheme` paths, and **`operation: variables`** for emitted **`--sky-*`** names. Align `skyui.config` `theme.extend` with tokens from **`@sky.ui/core`**. Prefer utility classes for layout/spacing/typography around **`<sky-*>`** elements.
-
-## Styling workflow for assistants
-
-1. **`get_project_guide`** — install + bundler wiring  
-2. **`utility_classes`** — validate and discover class names  
-3. **`get_theme`** — token names for custom theme keys  
-4. **`get_docs`** — `packages/mcp/docs/utils-usage-guide.md` (this file) when needed  
-
-Prefer utility `class` / `className` over large hand-written CSS unless the user asks otherwise.
+# Using @sky.ui/utils
+
+Sky UI utilities are **JIT CSS classes** you add in HTML/JSX/Vue/Lit templates (`class` / `className`). A **PostCSS plugin** scans your project, reads **`skyui.config.js`**, and emits only the CSS you use.
+
+## Install
+
+```bash
+npm install "@sky.ui/utils" postcss
+```
+
+> Quote scoped names (`"@sky.ui/…"`) — required in PowerShell.
+
+Register in PostCSS (exact wiring depends on your bundler — use MCP **`get_project_guide`** with `kind: setup`):
+
+```js
+import skyui from '@sky.ui/utils/postcss';
+
+export default {
+  plugins: [skyui()]
+};
+```
+
+**Peer dependency:** `postcss` >= 8.4.
+
+## Public imports
+
+| Import | Use |
+| --- | --- |
+| `@sky.ui/utils` / `@sky.ui/utils/postcss` | PostCSS plugin (**`SkyUIPlugin`**) |
+| `@sky.ui/utils/vite` | Vite integration |
+| `@sky.ui/utils/css-data` | VS Code `css.customData` — silences “Unknown at rule” for `@apply` / `@skyui` |
+| `@sky.ui/utils/suggestion-engine` | Editor completions (optional) |
+| `@sky.ui/utils/prettier-plugin` | Sort class strings in `class` / `@apply` |
+| `@sky.ui/utils/runtime` | Browser **`skyui`** helper for static pages |
+
+## `skyui.config.js`
+
+Typical fields:
+
+| Field | Purpose |
+| --- | --- |
+| `content` | Globs of files to scan for class names |
+| `safelist` | Classes always generated (strings or `{ pattern, variants }`) |
+| `plugins` | Built-ins such as `@skyuicss/forms`, `@skyuicss/typography`, `@skyuicss/container-queries` |
+| `theme` / `theme.extend` | Colors, spacing, screens, `preflight`, `formsStrategy`, animations |
+| `breakpoints` | Screen map for `sm:`, `md:`, … |
+
+The plugin discovers config by walking up from the processed CSS file.
+
+## VS Code CSS validation
+
+Add to `.vscode/settings.json` so `@apply` and `@skyui` are not flagged as unknown at-rules:
+
+```json
+{
+  "css.customData": ["./node_modules/@sky.ui/utils/skyui.css-data.json"]
+}
+```
+
+Or install the **Sky UI IntelliSense** extension (bundles the same custom data).
+
+## CSS layers and `@skyui` directives
+
+Declare layer order once:
+
+```css
+@layer skyui.base, skyui.components, skyui.utilities;
+@skyui utilities;
+```
+
+| Directive | Purpose |
+| --- | --- |
+| `@apply` | Compose utilities inside component CSS |
+| `@skyui theme { … }` | CSS-first design tokens |
+| `@skyui source "glob"` | Extra scan paths |
+| `@skyui source inline("a b")` | Safelist in CSS |
+| `@skyui reference` | Tokens only in scoped styles (pair with global utilities) |
+| `@skyui utility` / `@skyui variant` | Custom utility or variant |
+| `@skyui plugin "…"` | Load a plugin spec |
+
+## Built-in plugins (`@skyuicss/*`)
+
+| Spec | Role |
+| --- | --- |
+| `@skyuicss/forms` | Form control utilities; optional `formsStrategy`: `class` \| `base` \| `both` |
+| `@skyuicss/typography` | `prose` utilities (`--sky-prose-*` variables) |
+| `@skyuicss/container-queries` | Container-query variants from theme screens |
+
+Short aliases: `forms`, `typography`, `container-queries`.
+
+## Preflight
+
+`theme.preflight`: `true` | `"minimal"` | `"full"` — optional base reset in `@layer skyui.base` (default off).
+
+## Variants (common families)
+
+Responsive (`sm:`, `md:`, `max-sm:`), dark/light, state (`hover:`, `focus:`, `disabled:`), `not-*`, `group-*` / `peer-*`, `starting:`, `aria-*`, arbitrary (`has-[…]:`, `[&…]:`).
+
+Use MCP **`utility_classes`** (`operation: variant_prefixes`) for the full prefix list, **`search_classes`** to browse names, **`check_class`** to validate a token.
+
+## Theme alignment with components
+
+Use MCP **`get_theme`** — start with **`operation: guide`**, then **`fields`** / **`field`** for `userTheme` paths, and **`operation: variables`** for emitted **`--sky-*`** names. Align `skyui.config` `theme.extend` with tokens from **`@sky.ui/core`**. Prefer utility classes for layout/spacing/typography around **`<sky-*>`** elements.
+
+## Styling workflow for assistants
+
+1. **`get_project_guide`** — install + bundler wiring  
+2. **`utility_classes`** — validate and discover class names  
+3. **`get_theme`** — token names for custom theme keys  
+4. **`get_docs`** — `packages/mcp/docs/utils-usage-guide.md` (this file) when needed  
+
+Prefer utility `class` / `className` over large hand-written CSS unless the user asks otherwise.

package/docs/vue-wrapper-v-model.md

@@ -1,36 +1,36 @@
-# Vue wrappers: `v-model` support and usage
-
-## When `v-model` works
-
-Use `v-model` on a `@sky.ui/vue` wrapper **when that component is documented for two-way binding**—confirm the primary value prop and update event in **`get_sky_component_docs`** (props/events surfaces).
-
-If the component does **not** document a two-way pair, treat it as **one-way**: bind with `:prop` / `@event` using the names from those tools. Do not assume `v-model` matches other UI libraries.
-
-## Usage patterns
-
-**Default `v-model`** — when the primary bound prop is the default for that component (often `modelValue` / `value`-style APIs exposed to Vue):
-
-```vue
-<SkyExample v-model="selected" />
-```
-
-**Named `v-model`** — when you bind a specific prop (replace `propName` with the actual prop from docs):
-
-```vue
-<SkyExample v-model:propName="selected" />
-```
-
-**Explicit two-way** — use the prop and event names from docs (`get_component_events`). Payload is on **`CustomEvent.detail`**:
-
-```vue
-<SkyExample :foo="state" @foo-changed="onFooChanged" />
-```
-
-```ts
-function onFooChanged(e: Event) {
-  const detail = (e as CustomEvent).detail;
-  // Map detail to local state using the shape documented for this component.
-}
-```
-
-Sky UI elements expose **`CustomEvent`** payloads on **`detail`**; wrappers follow the same contract where two-way binding applies.
+# Vue wrappers: `v-model` support and usage
+
+## When `v-model` works
+
+Use `v-model` on a `@sky.ui/vue` wrapper **when that component is documented for two-way binding**—confirm the primary value prop and update event in **`get_sky_component_docs`** (props/events surfaces).
+
+If the component does **not** document a two-way pair, treat it as **one-way**: bind with `:prop` / `@event` using the names from those tools. Do not assume `v-model` matches other UI libraries.
+
+## Usage patterns
+
+**Default `v-model`** — when the primary bound prop is the default for that component (often `modelValue` / `value`-style APIs exposed to Vue):
+
+```vue
+<SkyExample v-model="selected" />
+```
+
+**Named `v-model`** — when you bind a specific prop (replace `propName` with the actual prop from docs):
+
+```vue
+<SkyExample v-model:propName="selected" />
+```
+
+**Explicit two-way** — use the prop and event names from docs (`get_component_events`). Payload is on **`CustomEvent.detail`**:
+
+```vue
+<SkyExample :foo="state" @foo-changed="onFooChanged" />
+```
+
+```ts
+function onFooChanged(e: Event) {
+  const detail = (e as CustomEvent).detail;
+  // Map detail to local state using the shape documented for this component.
+}
+```
+
+Sky UI elements expose **`CustomEvent`** payloads on **`detail`**; wrappers follow the same contract where two-way binding applies.

package/package.json

@@ -1,63 +1,72 @@
-{
-  "name": "@sky.ui/mcp",
-  "version": "0.0.1",
-  "private": false,
-  "description": "MCP server for Sky UI — component catalog, docs, theme tokens, and live snippets from library.sky-ui.com for AI coding assistants.",
-  "type": "module",
-  "bin": {
-    "sky-ui-mcp": "dist/mcp-stdio-entry.js"
-  },
-  "exports": {
-    ".": "./dist/server.js",
-    "./docs": "./dist/docs.js",
-    "./package.json": "./package.json"
-  },
-  "license": "SEE LICENSE IN LICENSE.md",
-  "files": [
-    "dist",
-    "data",
-    "docs",
-    "README.md",
-    "LICENSE.md"
-  ],
-  "scripts": {
-    "build": "node ./scripts/gen-chart-api-sections.mjs && node ./scripts/gen-utils-suggestion-fallback.mjs && node ./scripts/gen-reactivity-readme-snapshot.mjs && tsc -p tsconfig.json && node ./scripts/verify-mcp-tool-parity.mjs && node ./scripts/validate-guideline-component-refs.mjs && node ./scripts/scan-guideline-banned-patterns.mjs && npm run check:guideline-coverage",
-    "start": "node ./dist/mcp-stdio-entry.js",
-    "dev": "tsx ./src/server.ts",
-    "serve:post": "tsx ./src/post-endpoint-server.ts",
-    "serve:post:dist": "node ./dist/post-endpoint-server.js",
-    "check:guideline-coverage": "node ./scripts/check-guideline-coverage.mjs",
-    "check:guideline-coverage:strict": "node ./scripts/check-guideline-coverage.mjs --strict",
-    "check:guideline-banned-patterns": "node ./scripts/scan-guideline-banned-patterns.mjs",
-    "clean": "rimraf dist"
-  },
-  "dependencies": {
-    "@fastify/cors": "^11.2.0",
-    "@fastify/rate-limit": "^10.3.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "fastify": "^5.8.5",
-    "typescript": "^5.9.3",
-    "zod": "^3.25.0"
-  },
-  "peerDependencies": {
-    "@sky.ui/core": ">=0.0.1",
-    "@sky.ui/utils": ">=0.0.1"
-  },
-  "peerDependenciesMeta": {
-    "@sky.ui/utils": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "rimraf": "^6.1.2",
-    "tsx": "^4.19.0"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+{
+  "name": "@sky.ui/mcp",
+  "version": "0.0.2",
+  "private": false,
+  "description": "MCP server for Sky UI — component catalog, docs, theme tokens, and live snippets from library.sky-ui.com for AI coding assistants.",
+  "type": "module",
+  "bin": {
+    "sky-ui-mcp": "dist/mcp-stdio-entry.js"
+  },
+  "exports": {
+    ".": "./dist/server.js",
+    "./docs": "./dist/docs.js",
+    "./package.json": "./package.json"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "files": [
+    "dist",
+    "data",
+    "docs",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "node ./scripts/gen-chart-api-sections.mjs && node ./scripts/gen-utils-suggestion-fallback.mjs && node ./scripts/gen-reactivity-readme-snapshot.mjs && tsc -p tsconfig.json && node ./scripts/verify-mcp-tool-parity.mjs && node ./scripts/validate-guideline-component-refs.mjs && node ./scripts/scan-guideline-banned-patterns.mjs && npm run check:guideline-coverage",
+    "start": "node ./dist/mcp-stdio-entry.js",
+    "dev": "tsx ./src/server.ts",
+    "serve:post": "tsx ./src/post-endpoint-server.ts",
+    "serve:post:dist": "node ./dist/post-endpoint-server.js",
+    "check:guideline-coverage": "node ./scripts/check-guideline-coverage.mjs",
+    "check:guideline-coverage:strict": "node ./scripts/check-guideline-coverage.mjs --strict",
+    "check:guideline-banned-patterns": "node ./scripts/scan-guideline-banned-patterns.mjs",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.2.0",
+    "@fastify/rate-limit": "^10.3.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fastify": "^5.8.5",
+    "typescript": "^5.9.3",
+    "zod": "^3.25.0"
+  },
+  "peerDependencies": {
+    "@sky.ui/core": ">=0.0.1",
+    "@sky.ui/utils": ">=0.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@sky.ui/utils": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "rimraf": "^6.1.2",
+    "tsx": "^4.19.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/sky_ui/sky-ui.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/sky_ui/sky-ui/-/issues"
+  },
+  "homepage": "https://library.sky-ui.com"
+}