@sky.ui/mcp

Model Context Protocol (MCP) server for Sky UI. 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

npm install "@sky.ui/mcp" "@sky.ui/core"

Quote scoped names ("@sky.ui/…") — required in PowerShell. See 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:

{
  "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:

npm install "@sky.ui/mcp" "@sky.ui/core"

Health check:

npx @sky.ui/mcp -- --health

Installed locally (monorepo or app dependency):

{
  "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.

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:

   • 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):

"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:

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 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 | | @sky.ui/react | npm | | @sky.ui/vue | npm | | @sky.ui/utils | npm | | @sky.ui/reactivity | npm |

License

Sky UI Free EULA — proprietary; not open source.