@c2n/mcp 0.0.7

package/dist/render.js

@@ -0,0 +1,181 @@
+/** Compact markdown renderers for tool results. */
+import { groupCssProperties } from "./lib/group-css.js";
+export const MAX_CHARS = 12_000;
+export function truncate(text, max = MAX_CHARS) {
+    return text.length <= max ? text : `${text.slice(0, max)}\n\n… (truncated at ${max} characters; narrow the request with a filter, limit or offset)`;
+}
+function table(headers, rows) {
+    const esc = (v) => v.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+    return [`| ${headers.join(' | ')} |`, `| ${headers.map(() => '---').join(' | ')} |`, ...rows.map((r) => `| ${r.map(esc).join(' | ')} |`)].join('\n');
+}
+function code(value) {
+    return value === undefined || value === '' ? '—' : `\`${value}\``;
+}
+export function renderComponentList(components, installed) {
+    const rows = components.map((c) => [
+        c.tagPattern ? `\`${c.tagPattern}\` (${c.icons?.length ?? 0} icons)` : c.elements.map((e) => `\`${e.tag}\``).join(', '),
+        c.package,
+        c.category,
+        c.description || c.intro || '',
+        installed(c.package)?.version ?? '—',
+    ]);
+    return `${components.length} components\n\n${table(['Tag', 'Package', 'Category', 'Description', 'Installed'], rows)}\n\nNext: \`get_component\` for the API, \`get_examples\` for markup, \`get_theme\` before writing CSS.`;
+}
+export function renderComponent(component, options) {
+    const { include, installed, concrete } = options;
+    const out = [];
+    const primary = concrete ?? { tag: component.elements[0].tag, modulePath: component.elements[0].modulePath, className: component.elements[0].className };
+    out.push(`# ${component.title} (${primary.tag})`);
+    out.push(component.description || component.intro || '');
+    out.push('');
+    out.push(`- Package: \`${component.package}\` ${installed ? `(installed ${installed.version})` : `— not installed. \`${component.install.npm}\``}`);
+    out.push(`- Status: ${component.status} · Category: ${component.category} · Docs: ${component.docsUrl}`);
+    out.push(`- Register: \`import '${primary.modulePath}'\` · Class: \`import { ${primary.className} } from '${primary.modulePath}'\``);
+    if (component.tagPattern)
+        out.push(`- Icon set: tags follow \`${component.tagPattern}\`, ${component.icons?.length} icons (use \`search_components\` with the icon name).`);
+    for (const element of component.elements) {
+        const api = installed?.elements?.get(element.tag) ?? element;
+        const heading = component.elements.length > 1 || component.tagPattern ? `\n## ${element.tag}\n` : '';
+        out.push(heading);
+        if (element.description && component.elements.length > 1)
+            out.push(element.description);
+        if (include.has('attributes') && api.attributes.length) {
+            out.push('\n### Attributes\n');
+            out.push(table(['Name', 'Type', 'Default', 'Description'], api.attributes.map((a) => [code(a.name), code(a.type), code(a.default), a.description ?? ''])));
+        }
+        if (include.has('slots') && api.slots.length) {
+            out.push('\n### Slots\n');
+            out.push(table(['Slot', 'Description'], api.slots.map((s) => [code(s.name || '(default)'), s.description ?? ''])));
+        }
+        if (include.has('events') && api.events.length) {
+            out.push('\n### Events\n');
+            out.push(table(['Event', 'Type', 'Description'], api.events.map((e) => [code(e.name), code(e.type), e.description ?? ''])));
+        }
+        if (include.has('parts') && api.cssParts.length) {
+            out.push('\n### CSS parts\n');
+            out.push('Use with `::part(name)` when CSS custom properties do not cover the required change.\n');
+            out.push(table(['Part', 'Description'], api.cssParts.map((part) => [code(part.name), part.description ?? ''])));
+        }
+        if (include.has('css') && api.cssProperties.length) {
+            out.push('\n### CSS variables\n');
+            out.push('Set them on the element, a class or any ancestor. `token` = the `--c2-theme--*` token the base theme maps the variable to.\n');
+            out.push(renderCssGroups(api.cssProperties.map((p) => ('part' in p ? p : withParsedName(p)))));
+        }
+    }
+    if (include.has('composition')) {
+        const { internal, slotted, usedBy } = component.composition;
+        if (internal.length || slotted.length || usedBy.length) {
+            out.push('\n## Composition\n');
+            if (internal.length)
+                out.push(`- Renders internally: ${internal.map((t) => `\`${t}\``).join(', ')} (their variables can be set on this element)`);
+            if (slotted.length)
+                out.push(`- Expects slotted: ${slotted.map((t) => `\`${t}\``).join(', ')}`);
+            if (usedBy.length)
+                out.push(`- Used by: ${usedBy.map((t) => `\`${t}\``).join(', ')}`);
+        }
+    }
+    if (include.has('presets') && component.presets?.items.length) {
+        out.push('\n## Presets\n');
+        out.push(component.presets.items.map((p) => `- **${p.name}**${p.description ? ` — ${p.description}` : ''} (${Object.keys(p.css).length} variables)`).join('\n'));
+        out.push('\nUse `get_presets` for the values, `generate_variant` with `preset` to turn one into code.');
+    }
+    out.push(`\nExamples: \`get_examples\` with \`tag: "${primary.tag}"\` (${component.examples.length} available${component.hasGallery ? ', including gallery variants' : ''}).`);
+    return out.filter((l) => l !== undefined).join('\n');
+}
+function withParsedName(p) {
+    const match = /^--(c2-[a-z0-9-]+?)(?:__(.+?))?--(-?[a-z-]+)$/.exec(p.name);
+    return {
+        name: p.name,
+        type: typeof p.type === 'string' ? p.type : (p.type?.text ?? ''),
+        default: p.default,
+        part: match?.[2]?.split('__')[0] ?? '',
+        state: match?.[2]?.split('__').slice(1).join('/') || undefined,
+        property: match?.[3] ?? p.name,
+        description: p.description,
+    };
+}
+export function renderCssGroups(properties) {
+    const out = [];
+    for (const group of groupCssProperties(properties)) {
+        out.push(`#### ${group.part || 'root'}`);
+        for (const { state, properties: props } of group.states) {
+            if (state)
+                out.push(`*${state}*`);
+            out.push(props
+                .map((p) => `- \`${p.name}\`${p.default ? ` = \`${p.default}\`` : ''}${p.type ? ` (${p.type})` : ''}${p.token ? ` → \`${p.token}\`` : ''}${p.description ? ` — ${p.description}` : ''}`)
+                .join('\n'));
+        }
+    }
+    return out.join('\n');
+}
+export function renderExamples(component, examples, total, offset) {
+    const out = [`# ${component.title} examples (${offset + 1}–${offset + examples.length} of ${total})`, ''];
+    for (const ex of examples) {
+        out.push(`#### ${ex.label}${ex.kind === 'gallery' ? ` (gallery${ex.section ? ` · ${ex.section}` : ''}${ex.isDefault ? ' · default without component overrides' : ''})` : ex.kind === 'usage' ? ' (usage)' : ''}`);
+        if (ex.tags?.length)
+            out.push(`Components: ${ex.tags.map((tag) => `\`${tag}\``).join(', ')}`);
+        if (ex.description)
+            out.push(`Demonstrates: ${ex.description}`);
+        if (ex.useWhen)
+            out.push(`Use when: ${ex.useWhen}`);
+        if (ex.accessibility)
+            out.push(`Accessibility: ${ex.accessibility}`);
+        out.push('```html');
+        out.push(ex.html.length > 4000 ? `${ex.html.slice(0, 4000)}\n<!-- … truncated -->` : ex.html);
+        out.push('```');
+        if (ex.css) {
+            out.push('```css');
+            out.push(ex.css);
+            out.push('```');
+        }
+        out.push('');
+    }
+    if (offset + examples.length < total)
+        out.push(`More: call again with \`offset: ${offset + examples.length}\`.`);
+    return out.join('\n');
+}
+export function renderPresets(component, names) {
+    if (!component.presets)
+        return `${component.title} has no curated presets. Use \`get_examples\` (gallery variants) instead.`;
+    const items = names ? component.presets.items.filter((p) => p.name.toLowerCase().includes(names.toLowerCase())) : component.presets.items;
+    const out = [`# ${component.title} presets`, '', 'Base markup:', '```html', component.presets.html, '```', ''];
+    for (const preset of items) {
+        out.push(`## ${preset.name}${preset.description ? ` — ${preset.description}` : ''}`);
+        out.push('```css');
+        out.push(Object.entries(preset.css)
+            .map(([k, v]) => `${k}: ${v};`)
+            .join('\n'));
+        out.push('```');
+        if (preset.attributes && Object.keys(preset.attributes).length)
+            out.push(`Attributes: ${Object.entries(preset.attributes)
+                .map(([k, v]) => `\`${k}${v ? `="${v}"` : ''}\``)
+                .join(', ')}`);
+        out.push('');
+    }
+    return out.join('\n');
+}
+export function renderTheme(theme, registry, component) {
+    const out = [];
+    if (component) {
+        out.push(`# Theme mapping for ${component.title}`, '');
+        const rows = [];
+        for (const element of component.elements)
+            for (const p of element.cssProperties)
+                if (p.token)
+                    rows.push([code(p.name), code(p.token), code(p.default)]);
+        out.push(rows.length ? table(['Component variable', 'Token', 'Default'], rows) : 'No variable of this component is mapped to a token; set its variables directly.');
+        out.push('', 'Variables without a token keep the component default; set them on a class for a variant.');
+        return out.join('\n');
+    }
+    out.push('# @c2n/theme', '');
+    out.push(`\`${theme.install.npm}\` then \`${theme.install.imports[0]}\` once at the app root (or \`${theme.install.imports[2]}\` alone and bridge your own tokens).`);
+    out.push('', `Dark mode: ${theme.darkMode}`, '');
+    out.push('## Tokens', '');
+    out.push(table(['Token', 'Light', 'Dark', 'Used by', 'Description'], theme.tokens.map((t) => [code(t.name), t.light === null ? '*unset*' : code(t.light), t.dark ? code(t.dark) : 'same', String(t.usedBy), t.description])));
+    out.push('', '## Map your own tokens', '', '```css', ':root {', '  --c2-theme--color-primary: var(--brand-600);', '  --c2-theme--color-surface: var(--surface);', '  --c2-theme--color-on-surface: var(--text);', '  --c2-theme--color-outline: var(--border);', '  --c2-theme--radius-md: var(--radius);', '  --c2-theme--font-family: var(--font-sans);', '}', '```');
+    out.push('', `Component variables always win over the base theme; \`get_theme\` with a \`tag\` lists one component's mapping. ${Object.keys(registry.components).length} components covered.`);
+    return out.join('\n');
+}
+export function elementApiNames(element) {
+    return { css: element.cssProperties.map((p) => p.name), attributes: element.attributes.map((a) => a.name) };
+}

package/dist/search.d.ts

@@ -0,0 +1,8 @@
+/** Tokenised scoring over component names, descriptions, attributes, slots, example labels and icon names. */
+import type { ComponentEntry, Registry } from './registry-types.ts';
+export interface SearchHit {
+    component: ComponentEntry;
+    score: number;
+    matches: string[];
+}
+export declare function searchComponents(registry: Registry, query: string, limit?: number): SearchHit[];

package/dist/search.js

@@ -0,0 +1,52 @@
+function tokens(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1);
+}
+export function searchComponents(registry, query, limit = 10) {
+    const terms = tokens(query);
+    if (terms.length === 0)
+        return [];
+    const hits = [];
+    for (const component of Object.values(registry.components)) {
+        let score = 0;
+        const matches = new Set();
+        const fields = [
+            ['title', component.title, 6],
+            ['id', component.id, 6],
+            ['tag', component.elements.map((e) => e.tag).join(' '), 6],
+            ['description', `${component.description} ${component.intro ?? ''}`, 3],
+            ['category', component.category, 2],
+        ];
+        for (const element of component.elements) {
+            for (const a of element.attributes)
+                fields.push([`attr:${a.name}`, `${a.name} ${a.description ?? ''}`, 2]);
+            for (const s of element.slots)
+                fields.push([`slot:${s.name || 'default'}`, `${s.name} ${s.description ?? ''}`, 2]);
+            for (const e of element.events)
+                fields.push([`event:${e.name}`, `${e.name} ${e.description ?? ''}`, 2]);
+        }
+        for (const ex of component.examples)
+            if (ex.kind !== 'preview')
+                fields.push([`example:${ex.label}`, `${ex.label} ${ex.section ?? ''} ${ex.description ?? ''} ${ex.useWhen ?? ''} ${ex.accessibility ?? ''}`, 1]);
+        for (const icon of component.icons ?? [])
+            fields.push([`icon:${icon}`, icon, 3]);
+        for (const [label, text, weight] of fields) {
+            const haystack = tokens(text);
+            for (const term of terms) {
+                if (haystack.some((h) => h === term)) {
+                    score += weight * 2;
+                    matches.add(label);
+                }
+                else if (haystack.some((h) => h.includes(term) || term.includes(h))) {
+                    score += weight;
+                    matches.add(label);
+                }
+            }
+        }
+        if (score > 0)
+            hits.push({ component, score, matches: [...matches].slice(0, 6) });
+    }
+    return hits.sort((a, b) => b.score - a.score || a.component.title.localeCompare(b.component.title)).slice(0, limit);
+}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+/** The c2n MCP server: tools and resources over the bundled registry. */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Registry } from './registry-types.ts';
+export declare function createServer(registry?: Registry): McpServer;

package/dist/server.js

@@ -0,0 +1,276 @@
+/** The c2n MCP server: tools and resources over the bundled registry. */
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { installedPackage } from "./installed.js";
+import { generateCode } from "./lib/generate-code.js";
+import { loadRegistry, resolveElement, suggest } from "./registry.js";
+import { MAX_CHARS, elementApiNames, renderComponent, renderComponentList, renderExamples, renderPresets, renderTheme, truncate } from "./render.js";
+import { searchComponents } from "./search.js";
+const GUIDE_TOPICS = ['workflow', 'theming', 'variant-components', 'frameworks'];
+const readOnly = { readOnlyHint: true, openWorldHint: false };
+function text(value) {
+    return { content: [{ type: 'text', text: truncate(value) }] };
+}
+function json(value) {
+    return { content: [{ type: 'text', text: truncate(JSON.stringify(value, null, 2), MAX_CHARS * 4) }] };
+}
+function notFound(registry, tag) {
+    const candidates = [...Object.keys(registry.tagIndex), ...Object.keys(registry.components)];
+    const hints = suggest(candidates, tag);
+    return {
+        ...text(`Unknown component "${tag}".${hints.length ? ` Did you mean ${hints.map((h) => `\`${h}\``).join(', ')}?` : ''} Use \`list_components\` or \`search_components\`.`),
+        isError: true,
+    };
+}
+export function createServer(registry = loadRegistry()) {
+    const server = new McpServer({ name: 'c2n', version: registry.c2nVersion }, {
+        instructions: [
+            'c2n web components (Lit custom elements, tag prefix c2-, npm scope @c2n).',
+            'Start with list_components or search_components, then get_component for the API and get_examples for markup.',
+            'Call get_theme before writing CSS: apps set ~35 --c2-theme--* tokens once; prefer per-component variables on a class or element, and use only documented ::part() hooks when variables cannot express the change.',
+            'When a look repeats, call generate_variant (css | html | lit) instead of repeating inline styles.',
+            'get_workflow_guide explains the application workflow, theming, variant components and framework notes.',
+        ].join(' '),
+    });
+    const formatSchema = z.enum(['markdown', 'json']).default('markdown').describe('Output format');
+    const tagSchema = z
+        .string()
+        .min(1)
+        .describe('Component tag, id or package: `c2-button`, `button`, `@c2n/button`, `c2-tab`, or a concrete icon tag such as `c2-feather-arrow-right`');
+    server.registerTool('list_components', {
+        title: 'List components',
+        description: 'Lists every c2n component (tag, package, category, one-line description, installed version in the current project).',
+        inputSchema: {
+            category: z
+                .enum(registry.categories)
+                .optional()
+                .describe('Only this category'),
+            keyword: z.string().optional().describe('Substring filter on tag, title or description'),
+            installedOnly: z.boolean().optional().describe('Only packages installed in the current project'),
+            format: formatSchema,
+        },
+        annotations: readOnly,
+    }, ({ category, keyword, installedOnly, format }) => {
+        const needle = keyword?.toLowerCase();
+        const components = Object.values(registry.components).filter((c) => (!category || c.category === category) &&
+            (!needle || `${c.id} ${c.title} ${c.description} ${c.elements.map((e) => e.tag).join(' ')}`.toLowerCase().includes(needle)) &&
+            (!installedOnly || installedPackage(c.package)));
+        if (format === 'json')
+            return json(components.map((c) => ({
+                id: c.id,
+                tags: c.elements.map((e) => e.tag),
+                tagPattern: c.tagPattern,
+                package: c.package,
+                category: c.category,
+                description: c.description,
+                installed: installedPackage(c.package)?.version ?? null,
+            })));
+        return text(renderComponentList(components, installedPackage));
+    });
+    server.registerTool('get_component', {
+        title: 'Get component API',
+        description: 'Full API of one component: install/import lines, attributes, slots, events, native CSS parts, CSS variables grouped by semantic target and state (with the theme token each follows), composition and preset names. Examples are served by get_examples.',
+        inputSchema: {
+            tag: tagSchema,
+            include: z
+                .array(z.enum(['attributes', 'slots', 'events', 'parts', 'css', 'composition', 'presets']))
+                .optional()
+                .describe('Sections to include (default: all)'),
+            format: formatSchema,
+        },
+        annotations: readOnly,
+    }, ({ tag, include, format }) => {
+        const resolved = resolveElement(registry, tag);
+        if (!resolved)
+            return notFound(registry, tag);
+        const installed = installedPackage(resolved.component.package);
+        if (format === 'json')
+            return json({
+                ...resolved.component,
+                examples: undefined,
+                installed: installed?.version ?? null,
+                resolved: { tag: resolved.tag, modulePath: resolved.modulePath, className: resolved.className },
+            });
+        return text(renderComponent(resolved.component, {
+            include: new Set(include ?? ['attributes', 'slots', 'events', 'parts', 'css', 'composition', 'presets']),
+            installed,
+            concrete: { tag: resolved.tag, modulePath: resolved.modulePath, className: resolved.className },
+        }));
+    });
+    server.registerTool('search_components', {
+        title: 'Search components',
+        description: 'Free-text search across component names, descriptions, attributes, slots, events, example labels and icon names. Use it to find the component for a UI need ("dropdown", "dialog", "avatar with status", "arrow icon").',
+        inputSchema: { query: z.string().min(2).describe('What you are looking for'), limit: z.number().int().min(1).max(25).default(10) },
+        annotations: readOnly,
+    }, ({ query, limit }) => {
+        const hits = searchComponents(registry, query, limit);
+        if (hits.length === 0)
+            return text(`No component matches "${query}". Try \`list_components\`.`);
+        return text(`${hits.length} result(s) for "${query}"\n\n` +
+            hits
+                .map((h) => `- **${h.component.title}** ${h.component.tagPattern ? `\`${h.component.tagPattern}\`` : h.component.elements.map((e) => `\`${e.tag}\``).join(', ')} (${h.component.package}) — ${h.component.description}\n  matched: ${h.matches.join(', ')}`)
+                .join('\n'));
+    });
+    server.registerTool('get_examples', {
+        title: 'Get examples',
+        description: 'Markup examples of a component: usage rows from the docs, styled gallery variants (with intent, use-when and accessibility metadata when curated) and the landing preview.',
+        inputSchema: {
+            tag: tagSchema,
+            kind: z.enum(['usage', 'gallery', 'preview']).optional().describe('Only this kind'),
+            label: z.string().optional().describe('Substring filter on the example label'),
+            section: z.string().optional().describe('Gallery section filter (e.g. "Variants", "Sizes")'),
+            query: z.string().optional().describe('Search label, section, description, use case, accessibility note and component tags'),
+            limit: z.number().int().min(1).max(20).default(8),
+            offset: z.number().int().min(0).default(0),
+            format: formatSchema,
+        },
+        annotations: readOnly,
+    }, ({ tag, kind, label, section, query, limit, offset, format }) => {
+        const resolved = resolveElement(registry, tag);
+        if (!resolved)
+            return notFound(registry, tag);
+        const needle = query?.toLowerCase();
+        const all = resolved.component.examples.filter((e) => {
+            const searchable = `${e.label} ${e.section ?? ''} ${e.description ?? ''} ${e.useWhen ?? ''} ${e.accessibility ?? ''} ${(e.tags ?? []).join(' ')}`.toLowerCase();
+            return ((!kind || e.kind === kind) &&
+                (!label || e.label.toLowerCase().includes(label.toLowerCase())) &&
+                (!section || (e.section ?? '').toLowerCase().includes(section.toLowerCase())) &&
+                (!needle || searchable.includes(needle)));
+        });
+        const page = all.slice(offset, offset + limit);
+        if (format === 'json')
+            return json({ total: all.length, offset, examples: page });
+        return text(all.length ? renderExamples(resolved.component, page, all.length, offset) : `No examples match for ${resolved.tag}.`);
+    });
+    server.registerTool('get_presets', {
+        title: 'Get presets',
+        description: 'Curated presets of a component ("inspiration" looks): base markup plus each preset as CSS variable values and attributes.',
+        inputSchema: { tag: tagSchema, name: z.string().optional().describe('Substring filter on the preset name'), format: formatSchema },
+        annotations: readOnly,
+    }, ({ tag, name, format }) => {
+        const resolved = resolveElement(registry, tag);
+        if (!resolved)
+            return notFound(registry, tag);
+        if (format === 'json')
+            return json(resolved.component.presets ?? null);
+        return text(renderPresets(resolved.component, name));
+    });
+    server.registerTool('get_theme', {
+        title: 'Get theme tokens',
+        description: "The @c2n/theme design tokens (--c2-theme--*) with light/dark defaults, how to install and map your own tokens, and dark mode. With `tag`: which of that component's variables follow which token.",
+        inputSchema: { tag: tagSchema.optional(), format: formatSchema },
+        annotations: readOnly,
+    }, ({ tag, format }) => {
+        const resolved = tag ? resolveElement(registry, tag) : undefined;
+        if (tag && !resolved)
+            return notFound(registry, tag);
+        if (format === 'json')
+            return json(resolved
+                ? {
+                    tag: resolved.tag,
+                    mapping: Object.fromEntries(resolved.component.elements.flatMap((e) => e.cssProperties.filter((p) => p.token).map((p) => [p.name, p.token]))),
+                }
+                : registry.theme);
+        return text(renderTheme(registry.theme, registry, resolved?.component));
+    });
+    server.registerTool('generate_variant', {
+        title: 'Generate a variant component',
+        description: 'Turns CSS variable / attribute overrides of a component into copy-paste code: a CSS class, HTML + <style>, a Lit subclass registered under your own tag, or JSON. Validates variable and attribute names against the component API. Start from a preset with `preset`.',
+        inputSchema: {
+            tag: tagSchema,
+            name: z
+                .string()
+                .regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)+$/, 'kebab-case with at least one hyphen, e.g. app-danger-button')
+                .describe('Class / tag name of the variant (kebab-case, must contain a hyphen, not c2-*)'),
+            css: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Component CSS variables to fix, e.g. {"--c2-button__container--background-color": "var(--c2-theme--color-error)"}'),
+            attributes: z.record(z.string(), z.string()).optional().describe('Attributes to fix, e.g. {"running": "true"}'),
+            preset: z.string().optional().describe('Name of a curated preset to start from (its values are merged under `css`)'),
+            html: z.string().optional().describe('Base markup; defaults to the preset markup or `<tag>Label</tag>`'),
+            format: z.enum(['css', 'html', 'lit', 'json', 'all']).default('all'),
+        },
+        annotations: readOnly,
+    }, ({ tag, name, css, attributes, preset, html, format }) => {
+        const resolved = resolveElement(registry, tag);
+        if (!resolved)
+            return notFound(registry, tag);
+        if (name.startsWith('c2-'))
+            return { ...text('Variant names must not start with `c2-`; use your own prefix (app-, site-, my-).'), isError: true };
+        const presetItem = preset ? resolved.component.presets?.items.find((p) => p.name.toLowerCase() === preset.toLowerCase()) : undefined;
+        if (preset && !presetItem)
+            return {
+                ...text(`Unknown preset "${preset}" for ${resolved.tag}. Available: ${(resolved.component.presets?.items ?? []).map((p) => p.name).join(', ') || 'none'}.`),
+                isError: true,
+            };
+        const changes = { css: { ...(presetItem?.css ?? {}), ...(css ?? {}) }, attributes: { ...(presetItem?.attributes ?? {}), ...(attributes ?? {}) } };
+        const api = elementApiNames(resolved.element);
+        const warnings = [];
+        for (const variable of Object.keys(changes.css)) {
+            if (!api.css.includes(variable) && !variable.startsWith('--c2-theme--')) {
+                const hint = suggest(api.css, variable, 2);
+                warnings.push(`Unknown variable \`${variable}\`${hint.length ? ` (did you mean ${hint.map((h) => `\`${h}\``).join(', ')}?)` : ''}`);
+            }
+        }
+        for (const attribute of Object.keys(changes.attributes)) {
+            if (!api.attributes.includes(attribute) && !attribute.startsWith('data-') && !attribute.startsWith('aria-'))
+                warnings.push(`Unknown attribute \`${attribute}\` (attributes: ${api.attributes.join(', ') || 'none'})`);
+        }
+        const baseHtml = html ?? resolved.component.presets?.html ?? `<${resolved.tag}>Label</${resolved.tag}>`;
+        const input = { tag: resolved.tag, html: baseHtml, changes, name, className: resolved.className, modulePath: resolved.modulePath };
+        const formats = format === 'all' ? ['css', 'html', 'lit'] : [format];
+        const out = [];
+        if (warnings.length)
+            out.push(`> ${warnings.join('\n> ')}\n`);
+        for (const f of formats) {
+            out.push(`## ${f === 'lit' ? 'Lit subclass' : f === 'css' ? 'CSS class variant' : f === 'html' ? 'HTML + style' : 'JSON preset'}`);
+            out.push(`\`\`\`${f === 'lit' ? 'ts' : f}`);
+            out.push(generateCode(f, input));
+            out.push('```');
+        }
+        return text(out.join('\n'));
+    });
+    server.registerTool('get_workflow_guide', {
+        title: 'Get workflow guide',
+        description: 'The c2n application workflow guides: `workflow` (theme once, use tags, name what repeats), `theming`, `variant-components`, `frameworks` (plain HTML, Lit, Astro, React, Vue, SSR).',
+        inputSchema: { topic: z.enum(GUIDE_TOPICS).default('workflow') },
+        annotations: readOnly,
+    }, ({ topic }) => text(registry.guides[topic]));
+    server.registerResource('components', 'c2n://components', { title: 'c2n components', description: 'All components: id, tags, package, category, description', mimeType: 'application/json' }, (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'application/json',
+                text: JSON.stringify(Object.values(registry.components).map((c) => ({
+                    id: c.id,
+                    tags: c.elements.map((e) => e.tag),
+                    tagPattern: c.tagPattern,
+                    package: c.package,
+                    category: c.category,
+                    description: c.description,
+                })), null, 2),
+            },
+        ],
+    }));
+    server.registerResource('component', new ResourceTemplate('c2n://components/{tag}', {
+        list: () => ({ resources: Object.keys(registry.tagIndex).map((tag) => ({ uri: `c2n://components/${tag}`, name: tag, mimeType: 'application/json' })) }),
+    }), { title: 'c2n component', description: 'Full registry entry of one component (API, composition, presets, examples)', mimeType: 'application/json' }, (uri, { tag }) => {
+        const resolved = resolveElement(registry, String(tag));
+        if (!resolved)
+            throw new Error(`Unknown component ${String(tag)}`);
+        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(resolved.component, null, 2) }] };
+    });
+    server.registerResource('theme', 'c2n://theme', { title: '@c2n/theme tokens', description: 'Design tokens and the component variable → token mapping', mimeType: 'application/json' }, (uri) => ({
+        contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(registry.theme, null, 2) }],
+    }));
+    server.registerResource('guide', new ResourceTemplate('c2n://guide/{topic}', {
+        list: () => ({ resources: GUIDE_TOPICS.map((topic) => ({ uri: `c2n://guide/${topic}`, name: topic, mimeType: 'text/markdown' })) }),
+    }), { title: 'c2n guide', description: 'Application workflow guides', mimeType: 'text/markdown' }, (uri, { topic }) => {
+        const guide = registry.guides[String(topic)];
+        if (!guide)
+            throw new Error(`Unknown guide ${String(topic)}`);
+        return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text: guide }] };
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@c2n/mcp",
+  "version": "0.0.7",
+  "description": "MCP server exposing the c2n web components (API, examples, presets, theme tokens, variant generation) to AI agents",
+  "type": "module",
+  "bin": {
+    "c2n-mcp": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./registry.json": "./data/registry.json"
+  },
+  "files": [
+    "dist",
+    "data"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model context protocol",
+    "web components",
+    "lit",
+    "c2n"
+  ],
+  "license": "MIT",
+  "author": "code2nguyen@gmail.com",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/code2nguyen/web-components.git"
+  },
+  "scripts": {
+    "build": "wireit",
+    "build:registry": "wireit",
+    "build:tsc": "wireit",
+    "predev": "npm run build:registry",
+    "start": "node dist/cli.js",
+    "dev": "node src/cli.ts",
+    "preinspect": "npm run build:registry",
+    "inspect": "npx -y @modelcontextprotocol/inspector node src/cli.ts",
+    "presmoke": "npm run build",
+    "prepack": "npm run build",
+    "smoke": "node scripts/smoke.ts"
+  },
+  "wireit": {
+    "build:registry": {
+      "dependencies": [
+        "../../..:build"
+      ],
+      "command": "node scripts/build-registry.ts",
+      "files": [
+        "scripts/build-registry.ts",
+        "src/registry-types.ts",
+        "src/lib/css-var-name.ts",
+        "../../components/*/custom-elements.json",
+        "../../icons/*/custom-elements.json",
+        "../../../open-packages/*/custom-elements.json",
+        "../../../apps/ui/src/content/**/*.mdx",
+        "../../../apps/ui/src/data/component-presets.ts",
+        "../../../apps/ui/src/data/component-previews.ts",
+        "../theme/dist/tokens.json",
+        "../skill/skills/c2n-components/references/*.md",
+        "!../skill/skills/c2n-components/references/component-catalog.md",
+        "../../../lerna.json",
+        "../../../package.json"
+      ],
+      "output": [
+        "data/registry.json"
+      ]
+    },
+    "build:tsc": {
+      "command": "tsc -p tsconfig.json",
+      "files": [
+        "src/**/*.ts",
+        "tsconfig.json"
+      ],
+      "output": [
+        "dist/**"
+      ]
+    },
+    "build": {
+      "dependencies": [
+        "build:registry",
+        "build:tsc"
+      ]
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@c2n/config": "*",
+    "custom-elements-manifest": "2.1.0"
+  },
+  "gitHead": "c8db398a27f7cd417d665fdf5da455fee2d4e910"
+}