@sky.ui/mcp 0.0.1

package/dist/server.js

@@ -0,0 +1,786 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as z from 'zod/v4';
+import { getMainPackageVersion, loadSkyComponentsCached, normalizeComponentKey, resolveComponentEntry, resolveMainPackageRoot } from './catalog.js';
+import { proInstallLine } from './component-tier.js';
+import { isCemManifestPresent, readCustomElementsManifestText } from './cem.js';
+import { getDocsPage, listDocsPaths } from './docs-read.js';
+import { handleGetChartUsage } from './chart-usage-tool.js';
+import { handleGetComponentUsage } from './component-usage-tool.js';
+import { handleGetSkyComponentDocs } from './component-docs-tool.js';
+import { handleGetReactivityLayer } from './reactivity-layer-tool.js';
+import { handleGetTheme } from './theme-tool.js';
+import { searchComponentsByApiBatch, searchSkyComponents } from './docs.js';
+import { McpErrorCode, mcpErrorJson, mcpToolErr } from './mcp-tool-errors.js';
+import { withSkyUiMcpMeta } from './mcp-response-truth.js';
+import { checkUtilityClass, getUtilityVariantPrefixes, searchUtilityClasses, utilityEngineSource } from './utils-suggestion-grounding.js';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const instructions = 'Sky UI MCP helps users build with Sky UI — not inspect internal implementation. Free: @sky.ui/core|vue|react. Pro: @sky.ui.pro/core|vue|react (install @sky.ui.pro/vue or @sky.ui.pro/react — free deps install automatically). Use get_project_guide (kind installation|setup) for install and bundler setup. Use sky_components (operation list|search|search_by_api) for discovery. get_sky_component_docs for component API. get_component_usage for lit/react/vue snippets. get_reactivity_layer for @sky.ui/reactivity. get_chart_usage for sky-chart (pro). get_theme (operation guide|fields|field|variables) to build userTheme on sky-theme-provider — start with guide. get_docs for allowlisted guides. utility_classes for @sky.ui/utils class names. Prefer utility classes for layout unless the user asks otherwise. Responses include _skyUiMcp.truthLayer; follow agentMust. Read-only.';
+/** Optional flags: MCP clients often send JSON `null` for omitted fields; Zod `.optional()` rejects `null`. */
+const optionalBooleanArg = () => z.boolean().nullish();
+export function assertCoreDependencyAvailable() {
+    const mainRoot = resolveMainPackageRoot();
+    if (mainRoot)
+        return;
+    throw new Error([
+        'Missing required dependency: @sky.ui/core',
+        'Install it alongside @sky.ui/mcp before starting the server.',
+        'Example:',
+        '  npm install @sky.ui/mcp @sky.ui/core'
+    ].join('\n'));
+}
+function compact(input) {
+    return input.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+function parseFramework(input) {
+    if (!input)
+        return 'core';
+    const v = compact(input);
+    if (['core', 'webcomponent', 'webcomponents', 'vanilla', 'wc'].includes(v))
+        return 'core';
+    if (['lit', 'litelement'].includes(v))
+        return 'lit';
+    if (['react', 'reactjs', 'jsx'].includes(v))
+        return 'react';
+    if (['vue', 'vue3', 'sfc'].includes(v))
+        return 'vue';
+    if (['reactivity', 'reactive', 'signals', 'reactiveutils'].includes(v))
+        return 'reactivity';
+    if (v.startsWith('reactiv'))
+        return 'reactivity';
+    if (v.startsWith('rea'))
+        return 'react';
+    if (v.startsWith('vu'))
+        return 'vue';
+    if (v.startsWith('li'))
+        return 'lit';
+    return null;
+}
+function parseBundler(input) {
+    if (!input)
+        return null;
+    const v = compact(input);
+    if (['vite', 'vit'].includes(v))
+        return 'vite';
+    if (['webpack', 'webpak', 'wp'].includes(v))
+        return 'webpack';
+    if (['rollup', 'roll'].includes(v))
+        return 'rollup';
+    if (['rolldown', 'rdown', 'rdown'].includes(v))
+        return 'rolldown';
+    if (['parcel', 'prcl'].includes(v))
+        return 'parcel';
+    if (v.startsWith('web'))
+        return 'webpack';
+    if (v.startsWith('rolld'))
+        return 'rolldown';
+    if (v.startsWith('roll'))
+        return 'rollup';
+    if (v.startsWith('par'))
+        return 'parcel';
+    return null;
+}
+function installationGuide(framework) {
+    const lines = [];
+    lines.push('Sky UI installation guide');
+    lines.push('');
+    lines.push('1) Install dependencies from monorepo root:');
+    lines.push('   npm install');
+    lines.push('');
+    lines.push('2) Build needed packages:');
+    lines.push('   npm run build:main');
+    if (framework === 'react')
+        lines.push('   npm run build:react');
+    if (framework === 'vue')
+        lines.push('   npm run build:vue');
+    if (framework === 'reactivity')
+        lines.push('   npm run build:reactivity');
+    lines.push('');
+    if (framework === 'reactivity') {
+        lines.push('3) Add @sky.ui/reactivity to apps that need the lightweight reactive runtime:');
+        lines.push('   npm install @sky.ui/reactivity');
+        lines.push('   (In this monorepo, workspace linking already exposes it after npm install.)');
+        lines.push('');
+        lines.push('4) Import primitives:');
+        lines.push("   import { reactive, ref, computed, watch, effect } from '@sky.ui/reactivity';");
+        lines.push('');
+        lines.push('5) API surface: get_reactivity_layer (operation list_topics then get_topic) or get_docs packages/reactivity/README.md.');
+        lines.push('');
+        lines.push('Tip: get_project_guide with kind setup and framework reactivity (any bundler) for generic ESM/bundler notes.');
+        return lines.join('\n');
+    }
+    if (framework === 'core' || framework === 'lit') {
+        lines.push('3) Use component side-effect imports:');
+        lines.push("   import '@sky.ui/core/sky-button';");
+        lines.push('');
+        lines.push('4) Render custom element tags directly (Lit/vanilla):');
+        lines.push('   <sky-button>Click</sky-button>');
+    }
+    else if (framework === 'react') {
+        lines.push('3) Use React wrapper imports:');
+        lines.push("   import { SkyButton } from '@sky.ui/react/sky-button';");
+        lines.push('');
+        lines.push('4) Render wrapper component:');
+        lines.push('   <SkyButton>Click</SkyButton>');
+    }
+    else {
+        lines.push('3) Use Vue wrapper imports:');
+        lines.push("   import { SkyButton } from '@sky.ui/vue/sky-button';");
+        lines.push('');
+        lines.push('4) Register/consume in Vue component templates.');
+    }
+    lines.push('');
+    lines.push('Pro components (@sky.ui.pro/*): install one wrapper — free packages are npm dependencies.');
+    lines.push(`   ${proInstallLine(framework === 'react' ? 'react' : framework === 'vue' ? 'vue' : 'main')}`);
+    lines.push('   Pro imports: @sky.ui.pro/core/<tag>, @sky.ui.pro/vue/<tag>, @sky.ui.pro/react/<tag>');
+    lines.push('');
+    lines.push('Tip: run get_project_guide with kind setup for bundler-specific plugin setup.');
+    return lines.join('\n');
+}
+function setupGuide(framework, bundler) {
+    if (framework === 'reactivity') {
+        return [
+            'Sky UI setup guide (@sky.ui/reactivity)',
+            '',
+            'No Sky UI-specific Vite/Webpack/Rollup plugin is required for @sky.ui/reactivity.',
+            'It is a small ESM package: configure your bundler like any other dependency (resolve package.json `exports`).',
+            '',
+            'Monorepo: from the repo root run `npm install` and `npm run build:reactivity` before consuming it from test apps.',
+            '',
+            'Use get_reactivity_layer (operation list_topics then get_topic) or get_docs with packages/reactivity/README.md for the full guide.'
+        ].join('\n');
+    }
+    const lines = [];
+    lines.push(`Sky UI setup guide (${framework} + ${bundler})`);
+    lines.push('');
+    if (bundler === 'vite') {
+        if (framework === 'react') {
+            lines.push("Use `SkyUIReactVitePlugin` from `@sky.ui/react/vite` in `vite.config`.");
+            lines.push('Then use React wrappers in JSX.');
+        }
+        else if (framework === 'vue') {
+            lines.push("Use `SkyUIVueVitePlugin` from `@sky.ui/vue/vite` in `vite.config`.");
+            lines.push('Then use Vue wrappers in SFC templates.');
+        }
+        else {
+            lines.push("Use `SkyUIMainVitePlugin({ mode: 'auto-import' })` from `@sky.ui/core/vite`.");
+            lines.push('Then use `<sky-*>` tags in HTML/Lit templates.');
+        }
+    }
+    else if (bundler === 'webpack') {
+        if (framework === 'react') {
+            lines.push("Use `SkyUIReactWebpackPlugin()` from `@sky.ui/react/webpack`.");
+            lines.push('Add wrapper imports in app code.');
+        }
+        else if (framework === 'vue') {
+            lines.push("Use `SkyUIVueWebpackPlugin()` from `@sky.ui/vue/webpack`.");
+            lines.push('Use Vue component resolver plugin for auto imports if desired.');
+        }
+        else {
+            lines.push("Use `SkyUIMainWebpackPlugin()` from `@sky.ui/core/webpack`.");
+            lines.push("Add `@sky.ui/core/auto-import-loader` in webpack config for auto imports.");
+        }
+    }
+    else if (bundler === 'rollup' || bundler === 'rolldown') {
+        if (framework === 'react') {
+            lines.push("Use `SkyUIReactRollupPlugin()` from `@sky.ui/react/rollup`.");
+        }
+        else if (framework === 'vue') {
+            lines.push("Use `SkyUIVueRollupPlugin()` from `@sky.ui/vue/rollup`.");
+        }
+        else {
+            lines.push("Use `SkyUIMainRollupPlugin({ mode: 'auto-import', entryHtml: 'index.html' })` from `@sky.ui/core/rollup`.");
+        }
+    }
+    else {
+        lines.push('Parcel generally works with manual imports.');
+        if (framework === 'core' || framework === 'lit') {
+            lines.push("Import core components explicitly, e.g. `import '@sky.ui/core/sky-button';`");
+        }
+        else {
+            lines.push(`Import wrapper component modules from @sky.ui/${framework}.`);
+        }
+    }
+    lines.push('');
+    lines.push('Tip: inspect `test/` apps in this repo for working reference configs.');
+    return lines.join('\n');
+}
+export function createSkyUiMcpServer() {
+    const server = new McpServer({ name: 'sky-ui', version: '1.0.0' }, { instructions });
+    server.registerTool('get_project_guide', {
+        title: 'Installation or bundler setup guide',
+        description: 'kind=installation: Sky UI install steps for core/lit/react/vue/reactivity. kind=setup: bundler-specific setup (vite/webpack/rollup/rolldown/parcel); bundler is ignored when framework resolves to reactivity.',
+        inputSchema: z.discriminatedUnion('kind', [
+            z.object({
+                kind: z.literal('installation'),
+                framework: z
+                    .string()
+                    .optional()
+                    .describe('Target framework (aliases: core/vanilla/webcomponents, lit, react, vue, reactivity/reactive/signals)')
+            }),
+            z.object({
+                kind: z.literal('setup'),
+                framework: z
+                    .string()
+                    .optional()
+                    .describe('Target framework (aliases accepted, default: core). Use reactivity for @sky.ui/reactivity.'),
+                bundler: z
+                    .string()
+                    .optional()
+                    .describe('Bundler/runtime (vite/webpack/rollup/rolldown/parcel; aliases). Required when framework is not reactivity.')
+            })
+        ])
+    }, async (input) => {
+        if (input.kind === 'installation') {
+            const fw = parseFramework(input.framework);
+            if (!fw) {
+                return mcpToolErr(McpErrorCode.INSTALL_GUIDE_INVALID_FRAMEWORK, `Unknown framework: ${input.framework}`, {
+                    supported: ['core', 'lit', 'react', 'vue', 'reactivity']
+                });
+            }
+            const text = installationGuide(fw);
+            return { content: [{ type: 'text', text }] };
+        }
+        const fw = parseFramework(input.framework);
+        if (fw === 'reactivity') {
+            const text = setupGuide('reactivity', 'vite');
+            return { content: [{ type: 'text', text }] };
+        }
+        const b = parseBundler(input.bundler);
+        if (!fw || !b) {
+            return mcpToolErr(McpErrorCode.SETUP_GUIDE_INVALID_INPUT, 'Unknown framework or bundler input', {
+                input: { framework: input.framework, bundler: input.bundler },
+                supported: {
+                    framework: ['core', 'lit', 'react', 'vue', 'reactivity'],
+                    bundler: ['vite', 'webpack', 'rollup', 'rolldown', 'parcel']
+                }
+            });
+        }
+        const text = setupGuide(fw, b);
+        return { content: [{ type: 'text', text }] };
+    });
+    server.registerTool('sky_components', {
+        title: 'Sky UI component discovery',
+        description: 'operation=list: paginated catalog. operation=search: keyword search on names + summaries. operation=search_by_api: one or more API keywords (props/events/slots/methods).',
+        inputSchema: z.discriminatedUnion('operation', [
+            z.object({
+                operation: z.literal('list'),
+                offset: z.number().int().min(0).optional().describe('0-based index (default 0)'),
+                limit: z.number().int().min(1).max(500).optional().describe('Page size (default 100)')
+            }),
+            z.object({
+                operation: z.literal('search'),
+                query: z.string().describe('Space-separated keywords, e.g. "table pivot"'),
+                limit: z.number().int().min(1).max(50).optional().describe('Max hits (default 20)')
+            }),
+            z.object({
+                operation: z.literal('search_by_api'),
+                queries: z.array(z.string()).min(1).max(20).describe('API keywords, e.g. ["disabled","loading"]'),
+                limit_per_query: z.number().int().min(1).max(50).optional().describe('Max hits per query (default 10)')
+            })
+        ])
+    }, async (input) => {
+        if (input.operation === 'list') {
+            const loaded = loadSkyComponentsCached();
+            if (!loaded.ok) {
+                return mcpToolErr(McpErrorCode.COMPONENT_CATALOG_FAILED, loaded.error);
+            }
+            const off = input.offset ?? 0;
+            const lim = input.limit ?? 100;
+            const total = loaded.components.length;
+            const slice = loaded.components.slice(off, off + lim);
+            const body = {
+                source: loaded.path,
+                total,
+                offset: off,
+                limit: lim,
+                returned: slice.length,
+                nextOffset: off + slice.length < total ? off + slice.length : null,
+                mainVersion: getMainPackageVersion(),
+                customElementsManifest: isCemManifestPresent()
+                    ? 'packages/main/dist/custom-elements.json (run npm run build:main after clone)'
+                    : null,
+                components: slice.map((c) => ({
+                    name: c.name,
+                    tier: c.tier,
+                    import: c.npmImport,
+                    vueImport: c.vueImport,
+                    reactImport: c.reactImport
+                }))
+            };
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(withSkyUiMcpMeta(body, 'api_source'), null, 2) }
+                ]
+            };
+        }
+        if (input.operation === 'search') {
+            const lim = input.limit ?? 20;
+            const result = searchSkyComponents(input.query, lim);
+            if (!result.ok) {
+                return mcpToolErr(McpErrorCode.COMPONENT_SEARCH_FAILED, result.error);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(withSkyUiMcpMeta({ query: input.query, limit: lim, hits: result.hits }, 'heuristic_search'), null, 2)
+                    }
+                ]
+            };
+        }
+        const lim = input.limit_per_query ?? 10;
+        const r = searchComponentsByApiBatch(input.queries, lim);
+        if (!r.ok) {
+            return mcpToolErr(McpErrorCode.COMPONENT_API_SEARCH_FAILED, r.error);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(withSkyUiMcpMeta({ limitPerQuery: lim, results: r.results }, 'heuristic_search'), null, 2)
+                }
+            ]
+        };
+    });
+    server.registerTool('get_theme', {
+        title: 'Build userTheme for sky-theme-provider',
+        description: 'Start with operation=guide (userTheme shape + workflow). operation=fields lists entries; operation=field returns examplePatch; operation=match_intent maps user phrasing to field_ids; operation=compose merges patches; operation=variables lists --sky-* CSS names.',
+        inputSchema: z.discriminatedUnion('operation', [
+            z.object({
+                operation: z.literal('guide').describe('Start here: userTheme shape, merge rules, groups, minimal example')
+            }),
+            z.object({
+                operation: z.literal('fields'),
+                group: z
+                    .string()
+                    .optional()
+                    .describe('Filter: color, surface, overlay, typography, density, shape, effects, motion, stacking, opacity')
+            }),
+            z.object({
+                operation: z.literal('field'),
+                field_id: z.string().describe('Field id from fields catalog, e.g. color_active')
+            }),
+            z.object({
+                operation: z.literal('variables'),
+                max_names: z.number().int().min(10).max(500).optional().describe('Cap on --sky-* names (default 200)')
+            }),
+            z.object({
+                operation: z.literal('match_intent'),
+                phrase: z.string().describe('User wording, e.g. "brand color", "more padding", "frosted glass"')
+            }),
+            z.object({
+                operation: z.literal('compose'),
+                field_ids: z
+                    .array(z.string())
+                    .min(1)
+                    .describe('Field ids from fields or match_intent — merges examplePatch into one userTheme object')
+            })
+        ])
+    }, async (input) => handleGetTheme(input));
+    server.registerTool('get_docs', {
+        title: 'Read allowed repository documentation file',
+        description: 'Returns markdown/text for allowlisted paths under the Sky UI monorepo (e.g. packages/mcp/README.md, packages/mcp/docs/sky-chart-option-api.md). Safe path-only reads.',
+        inputSchema: {
+            path: z.string().describe('Repo-relative path, e.g. packages/mcp/README.md'),
+            max_bytes: z.number().int().min(1_000).max(800_000).optional()
+        }
+    }, async ({ path: docPath, max_bytes }) => {
+        const r = getDocsPage(docPath, { max_bytes: max_bytes ?? undefined });
+        if (!r.ok) {
+            return mcpToolErr(McpErrorCode.DOCS_READ_FAILED, r.error, { allowed: listDocsPaths() });
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(withSkyUiMcpMeta({
+                        code: 'OK',
+                        path: r.path,
+                        mimeType: r.mimeType,
+                        truncated: r.truncated,
+                        content: r.content
+                    }, 'static_reference'), null, 2)
+                }
+            ]
+        };
+    });
+    server.registerTool('get_sky_component_docs', {
+        title: 'Get Sky UI component documentation',
+        description: 'Structured component API: summary, properties, slots, cssParts, events, methods, examples, and type definitions. Use name for one component or names[] for batch. Optional surface returns one member list (props|events|slots|methods). include_deprecations adds deprecation signals. Example-site enrichment applies when configured. Pair sky-chart with get_docs packages/mcp/docs/sky-chart-option-api.md.',
+        inputSchema: z
+            .object({
+            name: z.string().optional().describe('Single component name, e.g. sky-table or table'),
+            names: z
+                .array(z.string())
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('Batch: multiple component names in one call'),
+            surface: z
+                .enum(['props', 'events', 'slots', 'methods'])
+                .optional()
+                .describe('Return only one API surface instead of the full doc'),
+            include_deprecations: optionalBooleanArg().describe('If true, include deprecations payload inferred from documentation text'),
+            max_example_chars: z.number().int().min(500).max(100_000).nullish().describe('Max characters per @example body (default 12000)'),
+            include_raw_lead: optionalBooleanArg().describe('If true, include rawLeadTrivia (JSDoc + decorators text before class keyword)'),
+            include_internal_lifecycle_methods: optionalBooleanArg().describe('If true, include browser/Lit lifecycle methods in the methods array. Default false.')
+        })
+            .superRefine((val, ctx) => {
+            const hasName = Boolean(val.name?.trim());
+            const hasNames = Boolean(val.names?.length);
+            if (hasName === hasNames) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: 'Provide exactly one of name (single) or names (batch).'
+                });
+            }
+        })
+    }, async (input) => handleGetSkyComponentDocs(input));
+    server.registerTool('get_component_usage', {
+        title: 'Component import path and usage snippet',
+        description: 'Returns lit/react/vue import paths and copy-paste starter snippets. React/Vue include wrapper metadata (Pascal name, barrel vs subpath, conventions). Optional import_style for react/vue: per_component | barrel | auto_import_note.',
+        inputSchema: {
+            framework: z.string().describe('Target framework: lit, react, or vue (aliases accepted)'),
+            name: z.string().describe('Component name, e.g. sky-button or button'),
+            import_style: z
+                .enum(['per_component', 'barrel', 'auto_import_note'])
+                .optional()
+                .describe('React/Vue only. Default per_component.')
+        }
+    }, async (input) => {
+        const result = handleGetComponentUsage(input);
+        return result;
+    });
+    server.registerTool('get_reactivity_layer', {
+        title: '@sky.ui/reactivity layer guide',
+        description: 'operation=list_topics: README section index. operation=get_topic: one section by id or alias. operation=package: named exports from @sky.ui/reactivity entry.',
+        inputSchema: z.discriminatedUnion('operation', [
+            z.object({ operation: z.literal('list_topics') }),
+            z.object({
+                operation: z.literal('get_topic'),
+                topic: z.string().min(1).describe('Topic id or alias (e.g. ref, sky-for); use list_topics first.'),
+                max_chars: z.number().int().min(2_000).max(400_000).optional()
+            }),
+            z.object({
+                operation: z.literal('package'),
+                export_substring: z.string().optional().describe('Filter named exports (case-insensitive substring)')
+            })
+        ])
+    }, async (input) => handleGetReactivityLayer(input));
+    server.registerTool('get_chart_usage', {
+        title: 'sky-chart types and usage',
+        description: 'operation=list_types: supported host chart types. operation=get_type: API sections + starter snippet for a type (optional framework lit|react|vue). operation=option_guide: compact EChartsOption mental model. Pair with get_sky_component_docs(name: sky-chart) for live props/events.',
+        inputSchema: z.discriminatedUnion('operation', [
+            z.object({ operation: z.literal('list_types') }),
+            z.object({
+                operation: z.literal('get_type'),
+                chart_type: z.string().describe('Chart type key, e.g. bar, line, pie, radar, brush'),
+                framework: z.enum(['lit', 'react', 'vue']).optional().describe('Snippet framework (default lit)'),
+                import_style: z.enum(['per_component', 'barrel', 'auto_import_note']).optional()
+            }),
+            z.object({
+                operation: z.literal('option_guide'),
+                max_bytes: z.number().int().min(1_000).max(800_000).optional()
+            })
+        ])
+    }, async (input) => handleGetChartUsage(input));
+    server.registerTool('utility_classes', {
+        title: '@sky.ui/utils — discover and validate utility class names',
+        description: 'User-facing class grounding only: variant_prefixes (responsive/state prefixes), search_classes (prefix browse), check_class (validate one token). Setup and config: get_project_guide + get_docs packages/mcp/docs/utils-usage-guide.md.',
+        inputSchema: z.discriminatedUnion('operation', [
+            z.object({ operation: z.literal('variant_prefixes') }),
+            z.object({
+                operation: z.literal('search_classes'),
+                starts_with: z.string().min(2).describe('Prefix on base utility names (min 2 chars)'),
+                limit: z.number().int().min(1).max(500).nullish(),
+                offset: z.number().int().min(0).nullish()
+            }),
+            z.object({
+                operation: z.literal('check_class'),
+                class_token: z
+                    .string()
+                    .min(1)
+                    .describe('One utility token with variants, e.g. hover:p-4, sm:bg-red-500')
+            })
+        ])
+    }, async (input) => {
+        if (input.operation === 'variant_prefixes') {
+            const r = await getUtilityVariantPrefixes();
+            if (!r.ok) {
+                return mcpToolErr(McpErrorCode.UTILS_SUGGESTION_FAILED, r.error);
+            }
+            const text = JSON.stringify(withSkyUiMcpMeta({ code: 'OK', variants: r.variants, count: r.count, disclaimer: r.disclaimer }, 'deterministic'), null, 2);
+            return { content: [{ type: 'text', text }] };
+        }
+        if (input.operation === 'search_classes') {
+            const r = await searchUtilityClasses({
+                starts_with: input.starts_with,
+                limit: input.limit ?? 80,
+                offset: input.offset ?? 0
+            });
+            if (!r.ok) {
+                return mcpToolErr(McpErrorCode.UTILS_SUGGESTION_FAILED, r.error);
+            }
+            const text = JSON.stringify(withSkyUiMcpMeta({
+                code: 'OK',
+                starts_with: r.starts_with,
+                limit: r.limit,
+                offset: r.offset,
+                totalMatches: r.totalMatches,
+                returned: r.returned,
+                classes: r.classes,
+                disclaimer: r.disclaimer
+            }, 'deterministic'), null, 2);
+            return { content: [{ type: 'text', text }] };
+        }
+        const raw = input.class_token.trim();
+        const parts = raw.split(/\s+/).filter(Boolean);
+        if (parts.length > 1 && !raw.includes(':')) {
+            const checks = await Promise.all(parts.map((p) => checkUtilityClass(p)));
+            const failed = checks.find((c) => !c.ok);
+            if (failed && !failed.ok) {
+                return mcpToolErr(McpErrorCode.UTILS_SUGGESTION_FAILED, failed.error);
+            }
+            const tokens = checks.filter((c) => c.ok);
+            const text = JSON.stringify(withSkyUiMcpMeta({
+                code: 'OK',
+                operation: 'check_class',
+                input: raw,
+                tokenCount: tokens.length,
+                engineSource: utilityEngineSource(),
+                tokens,
+                allKnownInCatalog: tokens.every((t) => t.knownInCatalog),
+                tip: 'Pass one class at a time when using variant prefixes (e.g. sm:hover:flex).'
+            }, 'deterministic'), null, 2);
+            return { content: [{ type: 'text', text }] };
+        }
+        const r = await checkUtilityClass(input.class_token);
+        if (!r.ok) {
+            return mcpToolErr(McpErrorCode.UTILS_SUGGESTION_FAILED, r.error);
+        }
+        const { ok: _ok2, ...body2 } = r;
+        const text = JSON.stringify(withSkyUiMcpMeta({ code: 'OK', operation: 'check_class', engineSource: utilityEngineSource(), ...body2 }, 'deterministic'), null, 2);
+        return { content: [{ type: 'text', text }] };
+    });
+    server.registerPrompt('sky_tool_router', {
+        title: 'Map user intent to Sky UI MCP tools',
+        description: 'Quick reference: which MCP tool to call for common questions (read-only; does not modify user projects).',
+        argsSchema: {}
+    }, async () => {
+        const body = [
+            '**Discovery**',
+            '- Catalog / keyword search / API search → `sky_components` (operation list | search | search_by_api)',
+            '',
+            '**Documentation**',
+            '- Full structured doc → `get_sky_component_docs` with `name`',
+            '- Batch docs → `get_sky_component_docs` with `names[]`',
+            '- One API surface → `get_sky_component_docs` with `surface` props|events|slots|methods',
+            '- Deprecations → `get_sky_component_docs` with `include_deprecations: true`',
+            '- Import + starter snippet → `get_component_usage` (lit | react | vue)',
+            '- Example-site agent recipe → `get_docs` with `packages/mcp/docs/agent-recipe-example-site.md`',
+            '- sky-chart → `get_chart_usage` then `get_sky_component_docs` with name `sky-chart`',
+            '',
+            '**Theme / userTheme**',
+            '- Start → `get_theme` operation **guide** (shape, merge rules, minimal example)',
+            '- Catalog → `get_theme` operation **fields** (what each entry does + JSON paths); optional group',
+            '- One entry + example JSON → `get_theme` operation **field** + field_id',
+            '- Map user phrasing → field ids → `get_theme` operation **match_intent** + phrase',
+            '- Merge several fields → `get_theme` operation **compose** + field_ids',
+            '- Emitted CSS var names → `get_theme` operation **variables**',
+            '- Prose companion → `get_docs` with `packages/mcp/docs/theme-config-guide.md`',
+            '- Cross-model routing → `get_docs` with `packages/mcp/docs/cross-model-mcp-playbook.md`',
+            '',
+            '**@sky.ui/reactivity**',
+            '- Topics → `get_reactivity_layer` (operation list_topics | get_topic | package)',
+            '- Full README → `get_docs` with `packages/reactivity/README.md`',
+            '- Install/setup → `get_project_guide` with framework `reactivity`',
+            '',
+            '**sky-chart**',
+            '- Types + snippets → `get_chart_usage` (operation list_types | get_type | option_guide)',
+            '- Live props/events → `get_sky_component_docs` with name `sky-chart`',
+            '',
+            '**@sky.ui/utils**',
+            '- Setup → `get_docs` with `packages/mcp/docs/utils-usage-guide.md` + `get_project_guide` (kind setup)',
+            '- Class names → `utility_classes` (variant_prefixes | search_classes | check_class)',
+            '',
+            '**Project setup**',
+            '- Install + bundler setup → `get_project_guide` (kind installation | setup)',
+            '',
+            'Epistemic: follow `_skyUiMcp.agentMust` before citing outputs as facts.',
+            'Resource: `sky-ui://catalog/tools` for machine-readable tool list.'
+        ].join('\n');
+        return {
+            description: 'Sky UI MCP tool routing',
+            messages: [{ role: 'user', content: { type: 'text', text: body } }]
+        };
+    });
+    server.registerPrompt('sky_lit_component', {
+        title: 'Lit + Sky UI component starter',
+        description: 'User message template for adding a Sky UI web component with correct import and tag usage.',
+        argsSchema: {
+            component: z.string().describe('Component name, e.g. sky-button or button')
+        }
+    }, async ({ component }) => {
+        const loaded = loadSkyComponentsCached();
+        const resolved = loaded.ok ? resolveComponentEntry(component, loaded.components) : null;
+        const fallbackKey = normalizeComponentKey(component);
+        const imp = resolved?.entry.npmImport ?? `@sky.ui/core/${fallbackKey}`;
+        const tag = resolved?.entry.name ?? fallbackKey;
+        const body = [
+            `Add the Sky UI component **${tag}** to a Lit project.`,
+            ``,
+            `- Import: \`import '${imp}';\` (side-effect import registers the custom element)`,
+            `- Use the tag \`<${tag}>...</${tag}>\` in Lit \`html\` templates.`,
+            `- Call **get_sky_component_docs** with name "${component}" for properties, slots, events, and examples.`,
+            `- Official docs: use the \`documentation\` field in that response when set.`
+        ].join('\n');
+        return {
+            description: `Starter instructions for ${tag}`,
+            messages: [{ role: 'user', content: { type: 'text', text: body } }]
+        };
+    });
+    server.registerResource('sky-ui-tools-catalog', 'sky-ui://catalog/tools', {
+        title: 'Sky UI MCP tools (summary)',
+        description: 'Machine-readable list of tool names and short descriptions for routing.',
+        mimeType: 'application/json'
+    }, async () => {
+        const tools = [
+            { name: 'get_project_guide', description: 'Installation (kind) or bundler setup (kind+framework+bundler)' },
+            { name: 'sky_components', description: 'List | keyword search | API batch search (operation discriminant)' },
+            { name: 'get_sky_component_docs', description: 'Structured component API; optional surface, batch names[], deprecations' },
+            { name: 'get_component_usage', description: 'Lit/react/vue import paths and starter snippets' },
+            { name: 'get_reactivity_layer', description: 'Reactivity README list_topics | get_topic | package exports' },
+            { name: 'get_chart_usage', description: 'sky-chart list_types | get_type | option_guide' },
+            { name: 'get_theme', description: 'userTheme authoring: guide | fields | field | variables' },
+            { name: 'get_docs', description: 'Read allowlisted repo documentation files' },
+            {
+                name: 'utility_classes',
+                description: '@sky.ui/utils variant_prefixes | search_classes | check_class'
+            }
+        ];
+        return {
+            contents: [
+                {
+                    uri: 'sky-ui://catalog/tools',
+                    mimeType: 'application/json',
+                    text: JSON.stringify({ tools }, null, 2)
+                }
+            ]
+        };
+    });
+    server.registerResource('sky-ui-component-catalog', 'sky-ui://catalog/components', {
+        title: 'Sky UI component catalog',
+        description: 'JSON list of @sky.ui/core and @sky.ui.pro/core component subpaths and tier-aware imports',
+        mimeType: 'application/json'
+    }, async () => {
+        const loaded = loadSkyComponentsCached();
+        if (!loaded.ok) {
+            return {
+                contents: [
+                    {
+                        uri: 'sky-ui://catalog/components',
+                        mimeType: 'application/json',
+                        text: mcpErrorJson(McpErrorCode.COMPONENT_CATALOG_FAILED, loaded.error)
+                    }
+                ]
+            };
+        }
+        const payload = {
+            source: loaded.path,
+            customElementsManifest: isCemManifestPresent(),
+            components: loaded.components
+        };
+        return {
+            contents: [
+                {
+                    uri: 'sky-ui://catalog/components',
+                    mimeType: 'application/json',
+                    text: JSON.stringify(payload, null, 2)
+                }
+            ]
+        };
+    });
+    server.registerResource('sky-ui-custom-elements-manifest', 'sky-ui://manifest/custom-elements.json', {
+        title: 'Sky UI Custom Elements Manifest',
+        description: 'Merged custom-elements.json from @sky.ui/core and @sky.ui.pro/core (after npm run build:main / build:main-pro). Standard schema for web component tooling.',
+        mimeType: 'application/json'
+    }, async () => {
+        const raw = readCustomElementsManifestText();
+        if (!raw) {
+            return {
+                contents: [
+                    {
+                        uri: 'sky-ui://manifest/custom-elements.json',
+                        mimeType: 'application/json',
+                        text: JSON.stringify({
+                            error: 'Manifest not found. From the monorepo root run: npm run build:main'
+                        })
+                    }
+                ]
+            };
+        }
+        return {
+            contents: [
+                {
+                    uri: 'sky-ui://manifest/custom-elements.json',
+                    mimeType: 'application/json',
+                    text: raw
+                }
+            ]
+        };
+    });
+    return server;
+}
+/** Opt-in stderr lines for stdio transport (stdout is reserved for MCP JSON-RPC). */
+function skyUiMcpStdioLogEnabled() {
+    const v = process.env.SKY_UI_MCP_STDIO_LOG?.trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes';
+}
+/** stdio MCP server (used by `mcp-stdio-entry` bin and tests). */
+export async function startSkyUiMcpStdio() {
+    assertCoreDependencyAvailable();
+    const server = createSkyUiMcpServer();
+    const transport = new StdioServerTransport();
+    if (skyUiMcpStdioLogEnabled()) {
+        console.error('[sky-ui-mcp] stdio server starting (waiting for MCP client on stdin). ' +
+            'If this process exits instantly with no error, stdin was closed—run from your editor MCP config, not a pipe or tool that closes stdin.');
+    }
+    process.stdin.on('end', () => {
+        if (skyUiMcpStdioLogEnabled()) {
+            console.error('[sky-ui-mcp] stdin closed; exiting (no MCP session).');
+        }
+        process.exit(0);
+    });
+    await server.connect(transport);
+}
+/**
+ * Legacy: `node …/dist/server.js` (not recommended — use `sky-ui-mcp` / `mcp-stdio-entry.js`).
+ * Must stay false when this module is imported (e.g. post-endpoint-server).
+ */
+function isRunAsServerScriptDirectly() {
+    if (typeof process === 'undefined' || !process.argv[1])
+        return false;
+    const selfPath = path.resolve(fileURLToPath(import.meta.url));
+    const argvPath = path.resolve(process.argv[1]);
+    if (selfPath === argvPath)
+        return true;
+    if (process.platform === 'win32' && selfPath.toLowerCase() === argvPath.toLowerCase())
+        return true;
+    try {
+        return realpathSync.native(selfPath) === realpathSync.native(argvPath);
+    }
+    catch {
+        return false;
+    }
+}
+if (isRunAsServerScriptDirectly()) {
+    startSkyUiMcpStdio().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=server.js.map