@sky.ui/mcp 0.0.1 → 0.0.2

package/README.md

@@ -1,182 +1,191 @@
-# @sky.ui/mcp
-
-Model Context Protocol (MCP) server for [Sky UI](https://library.sky-ui.com). Gives AI coding assistants accurate component APIs, usage snippets, theme tokens, and utility classes—instead of guessing tag names or props.
-
-Transport: **stdio** (Cursor, VS Code, Claude Desktop, and other MCP clients).
-
----
-
-## Install
-
-```bash
-npm install @sky.ui/mcp @sky.ui/core
-```
-
-| Package | Required | Role |
-|---------|----------|------|
-| `@sky.ui/core` | yes | Component metadata (CEM / AST) |
-| `@sky.ui/utils` | no | Live utility-class catalog |
-| `@sky.ui/reactivity` | no | Reactivity layer docs (optional peer via snapshot) |
-
----
-
-## Quick start
-
-Add to **`.cursor/mcp.json`** or **`.vscode/mcp.json`**:
-
-```json
-{
-  "mcpServers": {
-    "sky-ui": {
-      "command": "npx",
-      "args": ["-y", "@sky.ui/mcp@latest"]
-    }
-  }
-}
-```
-
-Reload the MCP panel after saving.
-
-**Health check:**
-
-```bash
-npx @sky.ui/mcp -- --health
-```
-
-**Installed locally** (monorepo or app dependency):
-
-```json
-{
-  "mcpServers": {
-    "sky-ui": {
-      "command": "node",
-      "args": ["./node_modules/@sky.ui/mcp/dist/mcp-stdio-entry.js"]
-    }
-  }
-}
-```
-
-The process speaks over stdin/stdout. If it exits immediately in a plain terminal, that is normal—no MCP client is attached.
-
----
-
-## Tools
-
-| Tool | Description |
-|------|-------------|
-| `get_project_guide` | Installation and bundler setup (Lit, React, Vue) |
-| `sky_components` | List, search, or search-by-API over the component catalog |
-| `get_sky_component_docs` | Props, events, slots, methods, types, and live doc-page snippets |
-| `get_component_usage` | Copy-paste starter snippets for Lit, React, or Vue |
-| `get_reactivity_layer` | `@sky.ui/reactivity` API reference |
-| `get_chart_usage` | `sky-chart` option reference (Pro) |
-| `get_theme` | Theme authoring: guide, fields, variables, compose |
-| `get_docs` | Allowlisted guides (utils, charts, agent recipes) |
-| `utility_classes` | Search and validate `@sky.ui/utils` class names |
-
-Learn more: [modelcontextprotocol.io](https://modelcontextprotocol.io).
-
----
-
-## How documentation is sourced
-
-Sky UI MCP combines two layers:
-
-1. **Package metadata (authoritative API)** — `get_sky_component_docs` and `sky_components` read **`@sky.ui/core`** (installed in the project). Props, events, slots, and methods come from the Custom Elements Manifest and TypeScript sources.
-
-2. **Published docs site (examples & routing)** — By default, MCP enriches component docs from **[library.sky-ui.com](https://library.sky-ui.com)**:
-   - `GET /api/mcp/manifest`
-   - `GET /api/mcp/component/{id}`
-
-   Enrichment adds **`exampleSiteSections`** (HTML / Sky / Vue / React snippets from doc pages) and **`exampleSitePageAi`** (routing hints). Responses include `_skyUiMcp.truthLayer` so assistants treat package API as canonical and site data as supplementary.
-
-No configuration is required for production; the default origin is `https://library.sky-ui.com`.
-
----
-
-## Environment variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SKY_UI_EXAMPLE_SITE_BASE_URL` | `https://library.sky-ui.com` | Docs site origin (no path). Override for local dev, e.g. `http://localhost:3000`. |
-| `SKY_UI_EXAMPLE_SITE_DISABLE` | — | Set `1` to skip live site fetches (offline / air-gapped). |
-| `SKY_UI_EXAMPLE_SITE_EXTRA_HOSTS` | — | Comma-separated hostnames allowed after redirects. |
-| `SKY_UI_MAIN_PACKAGE_ROOT` | auto | Path to `@sky.ui/core` when not resolved from `node_modules`. |
-| `SKY_UI_PERSONAL_TOKEN` | — | Pro package access (see below). |
-| `SKY_UI_AUTH_TOKEN` | — | Alias for personal token. |
-
-**Local docs site** (while running the Sky UI documentation site locally):
-
-```json
-"env": {
-  "SKY_UI_EXAMPLE_SITE_BASE_URL": "http://localhost:3000"
-}
-```
-
----
-
-## Pro packages (`@sky.ui.pro/*`)
-
-Pro artifacts require a license token:
-
-1. Run `npx sky.ui.pro login` once, **or**
-2. Set `SKY_UI_PERSONAL_TOKEN` / `SKY_UI_AUTH_TOKEN` in the MCP server `env` block.
-
-Cursor does not inherit shell profile variables—set tokens explicitly in MCP config when needed.
-
----
-
-## Optional: HTTP POST server
-
-For clients that cannot use stdio:
-
-```bash
-npx @sky.ui/mcp serve:post
-```
-
-| Setting | Default |
-|---------|---------|
-| Port | `3001` (`SKY_UI_MCP_POST_PORT`) |
-| Endpoints | `GET /health`, `POST /tool`, Streamable HTTP on `/` |
-
-See `docs/cross-model-mcp-playbook.md` for auth, CORS, and rate-limit options.
-
----
-
-## Setup checklist
-
-1. Install `@sky.ui/mcp` and `@sky.ui/core` in the workspace (or use `npx`).
-2. Ensure `@sky.ui/core` is built (`custom-elements.json` present) or install a published version from npm.
-3. Add the MCP server to your editor config and reload.
-4. Run `npx @sky.ui/mcp -- --health` and confirm `docsReady` and `exampleSite.baseUrl`.
-
----
-
-## Troubleshooting
-
-| Symptom | Action |
-|---------|--------|
-| `COMPONENT_DOCS_FAILED` | Install `@sky.ui/core`; set `SKY_UI_MAIN_PACKAGE_ROOT` if needed |
-| `customElementsManifest: null` | Build `@sky.ui/core` or install a published build |
-| Missing `exampleSiteSections` | Confirm [library.sky-ui.com/api/mcp/manifest](https://library.sky-ui.com/api/mcp/manifest) is reachable, or set `SKY_UI_EXAMPLE_SITE_BASE_URL` |
-| Stale tools in Cursor | Reload MCP after upgrading `@sky.ui/mcp` |
-| `UTILS_SUGGESTION_FAILED` | Install `@sky.ui/utils` or upgrade MCP (includes snapshot fallback) |
-| Process exits in terminal | Expected without an MCP client on stdin |
-
----
-
-## Related packages
-
-| Package | Link |
-|---------|------|
-| `@sky.ui/core` | [npm](https://www.npmjs.com/package/@sky.ui/core) |
-| `@sky.ui/react` | [npm](https://www.npmjs.com/package/@sky.ui/react) |
-| `@sky.ui/vue` | [npm](https://www.npmjs.com/package/@sky.ui/vue) |
-| `@sky.ui/utils` | [npm](https://www.npmjs.com/package/@sky.ui/utils) |
-| `@sky.ui/reactivity` | [npm](https://www.npmjs.com/package/@sky.ui/reactivity) |
-
----
-
-## License
-
-[Sky UI Free EULA](./LICENSE.md) — proprietary; not open source.
+# @sky.ui/mcp
+
+Model Context Protocol (MCP) server for [Sky UI](https://library.sky-ui.com). Gives AI coding assistants accurate component APIs, usage snippets, theme tokens, and utility classes—instead of guessing tag names or props.
+
+Transport: **stdio** (Cursor, VS Code, Claude Desktop, and other MCP clients).
+
+---
+
+## Install
+
+```bash
+npm install "@sky.ui/mcp" "@sky.ui/core"
+```
+
+> Quote scoped names (`"@sky.ui/…"`) — required in PowerShell. See [powershell-scoped-packages.md](../../docs/powershell-scoped-packages.md).
+
+| Package | Required | Role |
+|---------|----------|------|
+| `@sky.ui/core` | yes | Component metadata (CEM / AST) |
+| `@sky.ui/utils` | no | Live utility-class catalog |
+| `@sky.ui/reactivity` | no | Reactivity layer docs (optional peer via snapshot) |
+
+---
+
+## Quick start
+
+Add to **`.cursor/mcp.json`** or **`.vscode/mcp.json`**:
+
+```json
+{
+  "mcpServers": {
+    "sky-ui": {
+      "command": "npx",
+      "args": ["-y", "@sky.ui/mcp@latest"]
+    }
+  }
+}
+```
+
+Reload the MCP panel after saving.
+
+**Global / `npx` (recommended pattern):** MCP resolves `@sky.ui/core` from your **workspace** `node_modules` (via `process.cwd()` / `INIT_CWD`), not from the global install — same as ESLint, Prettier, and PostCSS plugins. Still install `@sky.ui/core` in the project:
+
+```bash
+npm install "@sky.ui/mcp" "@sky.ui/core"
+```
+
+**Health check:**
+
+```bash
+npx @sky.ui/mcp -- --health
+```
+
+**Installed locally** (monorepo or app dependency):
+
+```json
+{
+  "mcpServers": {
+    "sky-ui": {
+      "command": "node",
+      "args": ["./node_modules/@sky.ui/mcp/dist/mcp-stdio-entry.js"]
+    }
+  }
+}
+```
+
+The process speaks over stdin/stdout. If it exits immediately in a plain terminal, that is normal—no MCP client is attached.
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_project_guide` | Installation and bundler setup (Lit, React, Vue) |
+| `sky_components` | List, search, or search-by-API over the component catalog |
+| `get_sky_component_docs` | Props, events, slots, methods, types, and live doc-page snippets |
+| `get_component_usage` | Copy-paste starter snippets for Lit, React, or Vue |
+| `get_reactivity_layer` | `@sky.ui/reactivity` API reference |
+| `get_chart_usage` | `sky-chart` option reference (Pro) |
+| `get_theme` | Theme authoring: guide, fields, variables, compose |
+| `get_docs` | Allowlisted guides (utils, charts, agent recipes) |
+| `utility_classes` | Search and validate `@sky.ui/utils` class names |
+
+Learn more: [modelcontextprotocol.io](https://modelcontextprotocol.io).
+
+---
+
+## How documentation is sourced
+
+Sky UI MCP combines two layers:
+
+1. **Package metadata (authoritative API)** — `get_sky_component_docs` and `sky_components` read **`@sky.ui/core`** (installed in the project). Props, events, slots, and methods come from the Custom Elements Manifest and TypeScript sources.
+
+2. **Published docs site (examples & routing)** — By default, MCP enriches component docs from **[library.sky-ui.com](https://library.sky-ui.com)**:
+   - `GET /api/mcp/manifest`
+   - `GET /api/mcp/component/{id}`
+
+   Enrichment adds **`exampleSiteSections`** (HTML / Sky / Vue / React snippets from doc pages) and **`exampleSitePageAi`** (routing hints). Responses include `_skyUiMcp.truthLayer` so assistants treat package API as canonical and site data as supplementary.
+
+No configuration is required for production; the default origin is `https://library.sky-ui.com`.
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SKY_UI_EXAMPLE_SITE_BASE_URL` | `https://library.sky-ui.com` | Docs site origin (no path). Override for local dev, e.g. `http://localhost:3000`. |
+| `SKY_UI_EXAMPLE_SITE_DISABLE` | — | Set `1` to skip live site fetches (offline / air-gapped). |
+| `SKY_UI_EXAMPLE_SITE_EXTRA_HOSTS` | — | Comma-separated hostnames allowed after redirects. |
+| `SKY_UI_MAIN_PACKAGE_ROOT` | auto | Path to `@sky.ui/core` when not resolved from `node_modules`. |
+| `SKY_UI_MCP_PROJECT_ROOT` | auto | Workspace root when MCP runs globally (`npx`) but deps live in a project (same idea as ESLint cwd). |
+| `SKY_UI_PERSONAL_TOKEN` | — | Pro package access (see below). |
+| `SKY_UI_AUTH_TOKEN` | — | Alias for personal token. |
+
+**Local docs site** (while running the Sky UI documentation site locally):
+
+```json
+"env": {
+  "SKY_UI_EXAMPLE_SITE_BASE_URL": "http://localhost:3000"
+}
+```
+
+---
+
+## Pro packages (`@sky.ui.pro/*`)
+
+Pro artifacts require a license token:
+
+1. Run `npx sky.ui.pro login` once, **or**
+2. Set `SKY_UI_PERSONAL_TOKEN` / `SKY_UI_AUTH_TOKEN` in the MCP server `env` block.
+
+Cursor does not inherit shell profile variables—set tokens explicitly in MCP config when needed.
+
+---
+
+## Optional: HTTP POST server
+
+For clients that cannot use stdio:
+
+```bash
+npx @sky.ui/mcp serve:post
+```
+
+| Setting | Default |
+|---------|---------|
+| Port | `3001` (`SKY_UI_MCP_POST_PORT`) |
+| Endpoints | `GET /health`, `POST /tool`, Streamable HTTP on `/` |
+
+See `docs/cross-model-mcp-playbook.md` for auth, CORS, and rate-limit options.
+
+---
+
+## Setup checklist
+
+1. Install `@sky.ui/mcp` and `@sky.ui/core` in the workspace (or use `npx`).
+2. Ensure `@sky.ui/core` is built (`custom-elements.json` present) or install a published version from npm.
+3. Add the MCP server to your editor config and reload.
+4. Run `npx @sky.ui/mcp -- --health` and confirm `docsReady` and `exampleSite.baseUrl`.
+
+---
+
+## Troubleshooting
+
+| Symptom | Action |
+|---------|--------|
+| `COMPONENT_DOCS_FAILED` | Install `@sky.ui/core`; set `SKY_UI_MAIN_PACKAGE_ROOT` if needed |
+| `customElementsManifest: null` | Build `@sky.ui/core` or install a published build |
+| Missing `exampleSiteSections` | Confirm [library.sky-ui.com/api/mcp/manifest](https://library.sky-ui.com/api/mcp/manifest) is reachable, or set `SKY_UI_EXAMPLE_SITE_BASE_URL` |
+| Stale tools in Cursor | Reload MCP after upgrading `@sky.ui/mcp` |
+| `UTILS_SUGGESTION_FAILED` | Install `@sky.ui/utils` or upgrade MCP (includes snapshot fallback) |
+| Process exits in terminal | Expected without an MCP client on stdin |
+
+---
+
+## Related packages
+
+| Package | Link |
+|---------|------|
+| `@sky.ui/core` | [npm](https://www.npmjs.com/package/@sky.ui/core) |
+| `@sky.ui/react` | [npm](https://www.npmjs.com/package/@sky.ui/react) |
+| `@sky.ui/vue` | [npm](https://www.npmjs.com/package/@sky.ui/vue) |
+| `@sky.ui/utils` | [npm](https://www.npmjs.com/package/@sky.ui/utils) |
+| `@sky.ui/reactivity` | [npm](https://www.npmjs.com/package/@sky.ui/reactivity) |
+
+---
+
+## License
+
+[Sky UI Free EULA](https://unpkg.com/@sky.ui/mcp/LICENSE.md) — proprietary; not open source.