@c2n/mcp 0.0.7

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/** stdio entry point: `npx -y @c2n/mcp` or `node dist/cli.js`. */
+import { readFileSync } from 'node:fs';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from "./server.js";
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+    console.log('c2n-mcp — c2n web-component documentation and generation tools over stdio\n\nUsage: c2n-mcp [--help] [--version]');
+    process.exit(0);
+}
+if (args.includes('--version') || args.includes('-v')) {
+    const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    console.log(packageJson.version);
+    process.exit(0);
+}
+const server = createServer();
+await server.connect(new StdioServerTransport());

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createServer } from './server.ts';
+export { loadRegistry, resolveElement } from './registry.ts';
+export { generateCode } from './lib/generate-code.ts';
+export type * from './registry-types.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createServer } from "./server.js";
+export { loadRegistry, resolveElement } from "./registry.js";
+export { generateCode } from "./lib/generate-code.js";

package/dist/installed.d.ts

@@ -0,0 +1,8 @@
+import type { ElementEntry } from './registry-types.ts';
+export interface InstalledInfo {
+    version: string;
+    /** Elements from the installed `custom-elements.json`, keyed by tag, when the package ships one. */
+    elements?: Map<string, Pick<ElementEntry, 'attributes' | 'slots' | 'events' | 'cssParts' | 'cssProperties'>>;
+}
+export declare function projectRoot(): string;
+export declare function installedPackage(name: string): InstalledInfo | null;

package/dist/installed.js

@@ -0,0 +1,55 @@
+/**
+ * Detects which `@c2n/*` packages the current project has installed (resolved from `C2N_PROJECT_ROOT` or the cwd,
+ * which is the project directory when an MCP client spawns the server) and reads their manifests so the API served
+ * for an installed component matches the installed version.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+const TTL = 10_000;
+let cache;
+export function projectRoot() {
+    return process.env.C2N_PROJECT_ROOT ?? process.cwd();
+}
+export function installedPackage(name) {
+    const root = projectRoot();
+    if (!cache || cache.root !== root || Date.now() - cache.at > TTL)
+        cache = { at: Date.now(), root, packages: new Map() };
+    if (cache.packages.has(name))
+        return cache.packages.get(name) ?? null;
+    let info;
+    try {
+        const req = createRequire(join(root, 'noop.js'));
+        const pkgJsonPath = req.resolve(`${name}/package.json`);
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+        info = { version: pkg.version };
+        if (pkg.customElements) {
+            try {
+                const manifest = JSON.parse(readFileSync(join(pkgJsonPath, '..', pkg.customElements), 'utf8'));
+                const elements = new Map();
+                for (const mod of manifest.modules ?? []) {
+                    for (const decl of mod.declarations ?? []) {
+                        if (!decl.tagName)
+                            continue;
+                        elements.set(decl.tagName, {
+                            attributes: (decl.attributes ?? []),
+                            slots: (decl.slots ?? []),
+                            events: (decl.events ?? []),
+                            cssParts: (decl.cssParts ?? []),
+                            cssProperties: (decl.cssProperties ?? []).filter((p) => p.name),
+                        });
+                    }
+                }
+                info.elements = elements;
+            }
+            catch {
+                /* manifest unreadable: keep the bundled API */
+            }
+        }
+    }
+    catch {
+        info = null;
+    }
+    cache.packages.set(name, info);
+    return info;
+}

package/dist/lib/css-var-name.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Parses a c2 CSS variable name with the grammar `--<prefix>[__<part>[__<state>]]--<property>`.
+ * Ported from `apps/ui/src/utils/manifest-utils.ts` (`normalizeCssDeclaration`) and the theme generator.
+ */
+export interface ParsedCssVarName {
+    prefix: string;
+    parts: string[];
+    states: string[];
+    property: string;
+}
+export declare function parseCssVarName(name: string): ParsedCssVarName | undefined;

package/dist/lib/css-var-name.js

@@ -0,0 +1,38 @@
+const STATES = new Set([
+    'hover',
+    'active',
+    'focus',
+    'selected',
+    'disabled',
+    'open',
+    'error',
+    'read-only',
+    'unselected',
+    'copied',
+    'highlighted',
+    'over',
+    'online',
+    'away',
+    'busy',
+    'offline',
+    'expanded',
+    'running',
+    'checked',
+    'invalid',
+]);
+const NAME_PATTERN = /^--(c2-[a-z0-9-]+?)(?:__(.+?))?--(-?[a-z-]+)$/;
+export function parseCssVarName(name) {
+    const match = NAME_PATTERN.exec(name);
+    if (!match)
+        return undefined;
+    const [, prefix, blocks = '', property] = match;
+    const parts = [];
+    const states = [];
+    for (const block of blocks.split('__').filter(Boolean)) {
+        if (STATES.has(block))
+            states.push(block);
+        else
+            parts.push(block);
+    }
+    return { prefix, parts, states, property };
+}

package/dist/lib/generate-code.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Variant code generation, ported from `apps/ui/src/utils/playground.ts` (`generateCode`). The Lit output takes the
+ * base class and module from the registry instead of deriving them from the tag, which is wrong for `c2-tab`
+ * (`@c2n/tabs/tab.js`) and the icon elements.
+ */
+export type CodeFormat = 'html' | 'css' | 'lit' | 'json';
+export interface VariantChanges {
+    css: Record<string, string>;
+    attributes?: Record<string, string>;
+}
+export interface CodeInput {
+    tag: string;
+    /** Base markup the variant is applied to. */
+    html: string;
+    changes: VariantChanges;
+    /** Name of the generated class / custom element, e.g. `brand-checkbox`. */
+    name: string;
+    /** Exported class of the base element, e.g. `Button`. */
+    className: string;
+    /** Module exporting that class, e.g. `@c2n/button`. */
+    modulePath: string;
+}
+export declare function toPascalCase(value: string): string;
+/** Rewrites the opening tag of the root element: adds a class and applies attribute changes. */
+export declare function rewriteRootTag(html: string, tag: string, className: string, attributes?: Record<string, string>): string;
+export declare function generateCode(format: CodeFormat, input: CodeInput): string;

package/dist/lib/generate-code.js

@@ -0,0 +1,72 @@
+export function toPascalCase(value) {
+    return value
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join('');
+}
+function cssDeclarations(css, indent = '  ') {
+    return Object.entries(css)
+        .map(([name, value]) => `${indent}${name}: ${value};`)
+        .join('\n');
+}
+/** Rewrites the opening tag of the root element: adds a class and applies attribute changes. */
+export function rewriteRootTag(html, tag, className, attributes = {}) {
+    const open = new RegExp(`<${tag}(\\s[^>]*)?>`, 'i');
+    return html.replace(open, (_match, attrs = '') => {
+        let rest = attrs;
+        for (const [name, value] of Object.entries(attributes)) {
+            rest = rest.replace(new RegExp(`\\s${name}(=("[^"]*"|'[^']*'|[^\\s>]+))?`, 'i'), '');
+            if (value === 'true' || value === '')
+                rest += ` ${name}`;
+            else if (value !== 'false')
+                rest += ` ${name}="${value}"`;
+        }
+        if (/\sclass=/.test(rest)) {
+            rest = rest.replace(/\sclass=(["'])([^"']*)\1/, (_m, quote, classes) => ` class=${quote}${classes.trim()} ${className}${quote}`);
+        }
+        else {
+            rest = ` class="${className}"` + rest;
+        }
+        return `<${tag}${rest}>`;
+    });
+}
+export function generateCode(format, input) {
+    const { tag, html, changes, name, className: baseClass, modulePath } = input;
+    const hasCss = Object.keys(changes.css).length > 0;
+    switch (format) {
+        case 'css':
+            return hasCss ? `.${name} {\n${cssDeclarations(changes.css)}\n}` : `/* No CSS variable changes. */`;
+        case 'html': {
+            const markup = rewriteRootTag(html.trim(), tag, name, changes.attributes);
+            return hasCss ? `${markup}\n\n<style>\n  .${name} {\n${cssDeclarations(changes.css, '    ')}\n  }\n</style>` : markup;
+        }
+        case 'lit': {
+            const className = toPascalCase(name);
+            const attributeLines = Object.entries(changes.attributes ?? {})
+                .map(([attr, value]) => `    this.setAttribute('${attr}', '${value === 'true' ? '' : value}')`)
+                .join('\n');
+            return [
+                `import { css } from 'lit'`,
+                `import { ${baseClass} } from '${modulePath}'`,
+                ``,
+                `/** ${tag} with your theme baked in. Register once, then use <${name}> anywhere. */`,
+                `export class ${className} extends ${baseClass} {`,
+                `  static override styles = [`,
+                `    ${baseClass}.styles,`,
+                `    css\``,
+                `      :host {`,
+                hasCss ? cssDeclarations(changes.css, '        ') : `        /* your overrides */`,
+                `      }`,
+                `    \`,`,
+                `  ]`,
+                ...(attributeLines ? [``, `  override connectedCallback() {`, `    super.connectedCallback()`, attributeLines, `  }`] : []),
+                `}`,
+                ``,
+                `if (!customElements.get('${name}')) customElements.define('${name}', ${className})`,
+            ].join('\n');
+        }
+        case 'json':
+            return JSON.stringify({ tag, ...changes }, null, 2);
+    }
+}

package/dist/lib/group-css.d.ts

@@ -0,0 +1,10 @@
+/** Groups flat CSS variables by part, then by state, for compact rendering. */
+import type { CssProperty } from '../registry-types.ts';
+export interface CssGroup {
+    part: string;
+    states: {
+        state: string;
+        properties: CssProperty[];
+    }[];
+}
+export declare function groupCssProperties(properties: CssProperty[]): CssGroup[];

package/dist/lib/group-css.js

@@ -0,0 +1,13 @@
+export function groupCssProperties(properties) {
+    const groups = new Map();
+    for (const property of properties) {
+        const byState = groups.get(property.part) ?? new Map();
+        const state = property.state ?? '';
+        byState.set(state, [...(byState.get(state) ?? []), property]);
+        groups.set(property.part, byState);
+    }
+    return [...groups.entries()].map(([part, byState]) => ({
+        part,
+        states: [...byState.entries()].map(([state, props]) => ({ state, properties: props })),
+    }));
+}

package/dist/registry-types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Shape of `data/registry.json`: everything the MCP server knows about the c2n components, generated by
+ * `scripts/build-registry.ts` from the component manifests, the docs site content and the theme package.
+ */
+export interface Registry {
+    schemaVersion: 1;
+    /** lerna.json version of the published packages. */
+    c2nVersion: string;
+    categories: string[];
+    /** Keyed by component id (the docs page id: `button`, `feather-icons`, `chatbot`). */
+    components: Record<string, ComponentEntry>;
+    /** Tag → component id (`c2-tab` → `tabs`). Icon tags resolve through `tagPattern`. */
+    tagIndex: Record<string, string>;
+    /** npm package → component id. */
+    packageIndex: Record<string, string>;
+    theme: ThemeEntry;
+    guides: Record<GuideTopic, string>;
+}
+export type GuideTopic = 'workflow' | 'theming' | 'variant-components' | 'frameworks';
+export interface ComponentEntry {
+    id: string;
+    package: string;
+    title: string;
+    description: string;
+    intro?: string;
+    category: string;
+    /** `stable` has a docs page; `undocumented` is published and built but has no page yet. */
+    status: 'stable' | 'undocumented';
+    docsUrl: string;
+    /** One entry per custom element in the package (`tabs` has `c2-tabs` and `c2-tab`). */
+    elements: ElementEntry[];
+    /** Icon sets: the tag pattern (`c2-feather-{name}`) and the icon names. */
+    tagPattern?: string;
+    icons?: string[];
+    composition: {
+        internal: string[];
+        slotted: string[];
+        usedBy: string[];
+    };
+    install: {
+        npm: string;
+        import: string;
+        importClass: string;
+    };
+    presets?: {
+        html: string;
+        items: Preset[];
+    };
+    examples: Example[];
+    hasGallery: boolean;
+}
+export interface ElementEntry {
+    tag: string;
+    className: string;
+    /** Import specifier of the module defining the element, e.g. `@c2n/tabs/tab.js`. */
+    modulePath: string;
+    description: string;
+    attributes: {
+        name: string;
+        type: string;
+        default?: string;
+        description?: string;
+    }[];
+    slots: {
+        name: string;
+        description?: string;
+    }[];
+    events: {
+        name: string;
+        type?: string;
+        description?: string;
+    }[];
+    cssParts: {
+        name: string;
+        description?: string;
+    }[];
+    cssProperties: CssProperty[];
+}
+export interface CssProperty {
+    name: string;
+    type: string;
+    default?: string;
+    /** Part segment(s) joined with `/`, `''` for the root. */
+    part: string;
+    state?: string;
+    property: string;
+    /** `--c2-theme--*` token the base theme maps this variable to, when any. */
+    token?: string;
+    description?: string;
+}
+export interface Example {
+    kind: 'usage' | 'gallery' | 'preview';
+    label: string;
+    section?: string;
+    /** What the example demonstrates. */
+    description?: string;
+    /** Situation in which this pattern is appropriate. */
+    useWhen?: string;
+    /** Accessibility behavior or responsibility worth preserving. */
+    accessibility?: string;
+    /** True only for a gallery baseline named Default with no c2n CSS-variable overrides. */
+    isDefault?: boolean;
+    /** c2 custom-element tags present in the example markup. */
+    tags?: string[];
+    html: string;
+    css?: string;
+}
+export interface Preset {
+    name: string;
+    description?: string;
+    css: Record<string, string>;
+    attributes?: Record<string, string>;
+}
+export interface ThemeToken {
+    name: string;
+    category: string;
+    light: string | null;
+    dark?: string;
+    description: string;
+    /** Number of component variables mapped to this token. */
+    usedBy: number;
+}
+export interface ThemeEntry {
+    package: string;
+    install: {
+        npm: string;
+        imports: string[];
+    };
+    tokens: ThemeToken[];
+    /** Component variable → token. */
+    mapping: Record<string, string>;
+    darkMode: string;
+}

package/dist/registry-types.js

@@ -0,0 +1 @@
+export {};

package/dist/registry.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentEntry, ElementEntry, Registry } from './registry-types.ts';
+export declare function loadRegistry(): Registry;
+export interface ResolvedElement {
+    component: ComponentEntry;
+    element: ElementEntry;
+    /** Concrete tag (`c2-feather-arrow-right`), even when the element entry carries a pattern. */
+    tag: string;
+    /** Concrete module (`@c2n/feather-icons/icons/arrow-right.js`). */
+    modulePath: string;
+    className: string;
+}
+/** Accepts `c2-button`, `button`, `@c2n/button`, `c2-tab` or a concrete icon tag such as `c2-feather-arrow-right`. */
+export declare function resolveElement(registry: Registry, input: string): ResolvedElement | undefined;
+/** Closest names for "did you mean" hints. */
+export declare function suggest(candidates: string[], input: string, max?: number): string[];

package/dist/registry.js

@@ -0,0 +1,63 @@
+/** Loads `data/registry.json` and resolves tags / packages / ids to components. */
+import { readFileSync } from 'node:fs';
+export function loadRegistry() {
+    const url = new URL('../data/registry.json', import.meta.url);
+    return JSON.parse(readFileSync(url, 'utf8'));
+}
+/** Accepts `c2-button`, `button`, `@c2n/button`, `c2-tab` or a concrete icon tag such as `c2-feather-arrow-right`. */
+export function resolveElement(registry, input) {
+    const query = input.trim().toLowerCase();
+    const byPackage = registry.packageIndex[query];
+    const byTag = registry.tagIndex[query];
+    const id = byPackage ?? byTag ?? (registry.components[query] ? query : registry.tagIndex[`c2-${query}`]);
+    if (id) {
+        const component = registry.components[id];
+        const element = component.elements.find((e) => e.tag === query) ?? component.elements[0];
+        if (component.tagPattern && element.tag.includes('{name}')) {
+            const name = component.icons?.[0] ?? 'name';
+            return concreteIcon(component, element, name);
+        }
+        return { component, element, tag: element.tag, modulePath: element.modulePath, className: element.className };
+    }
+    // Icon tags: match a pattern such as `c2-feather-{name}`.
+    for (const component of Object.values(registry.components)) {
+        if (!component.tagPattern)
+            continue;
+        const prefix = component.tagPattern.replace('{name}', '');
+        if (query.startsWith(prefix) && component.icons?.includes(query.slice(prefix.length))) {
+            return concreteIcon(component, component.elements[0], query.slice(prefix.length));
+        }
+    }
+    return undefined;
+}
+function concreteIcon(component, element, name) {
+    const pascal = name
+        .split('-')
+        .map((p) => p[0].toUpperCase() + p.slice(1))
+        .join('');
+    return {
+        component,
+        element,
+        tag: element.tag.replace('{name}', name),
+        modulePath: element.modulePath.replace('{name}', name),
+        className: element.className.replace('{Name}', pascal),
+    };
+}
+/** Closest names for "did you mean" hints. */
+export function suggest(candidates, input, max = 3) {
+    const needle = input.toLowerCase();
+    const scored = candidates
+        .map((c) => ({ c, score: c.toLowerCase().includes(needle) || needle.includes(c.toLowerCase()) ? 2 : distance(c.toLowerCase(), needle) <= 4 ? 1 : 0 }))
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score || a.c.localeCompare(b.c));
+    return scored.slice(0, max).map((s) => s.c);
+}
+function distance(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++)
+        for (let j = 1; j <= b.length; j++)
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    return dp[a.length][b.length];
+}

package/dist/render.d.ts

@@ -0,0 +1,24 @@
+import type { InstalledInfo } from './installed.ts';
+import type { ComponentEntry, CssProperty, ElementEntry, Example, Registry, ThemeEntry } from './registry-types.ts';
+export declare const MAX_CHARS = 12000;
+export declare function truncate(text: string, max?: number): string;
+export declare function renderComponentList(components: ComponentEntry[], installed: (pkg: string) => InstalledInfo | null): string;
+export interface ComponentRenderOptions {
+    include: Set<'attributes' | 'slots' | 'events' | 'parts' | 'css' | 'composition' | 'presets'>;
+    installed: InstalledInfo | null;
+    /** Concrete tag / module when the request named an icon. */
+    concrete?: {
+        tag: string;
+        modulePath: string;
+        className: string;
+    };
+}
+export declare function renderComponent(component: ComponentEntry, options: ComponentRenderOptions): string;
+export declare function renderCssGroups(properties: CssProperty[]): string;
+export declare function renderExamples(component: ComponentEntry, examples: Example[], total: number, offset: number): string;
+export declare function renderPresets(component: ComponentEntry, names?: string): string;
+export declare function renderTheme(theme: ThemeEntry, registry: Registry, component?: ComponentEntry): string;
+export declare function elementApiNames(element: ElementEntry): {
+    css: string[];
+    attributes: string[];
+};