@besaitech/ng-design-system-mcp 0.0.5

package/dist/doc-index.schema.js

@@ -0,0 +1,143 @@
+/**
+ * The doc-index schema — the single source of truth for the shape of `docs.json`.
+ *
+ * Imported by BOTH the build-time generator (`scripts/`) and the runtime MCP
+ * server (`packages/mcp-server/`). The server re-validates the bundled artifact
+ * with this schema at startup, so the two can never disagree on shape.
+ *
+ * Uses zod v4 (already a workspace dependency).
+ */
+import { z } from 'zod';
+/** How a signal input's raw value is coerced by Angular. */
+export const TransformKind = z.enum([
+    'booleanAttribute',
+    'numberAttribute',
+    'toIconPx',
+]);
+export const InputSchema = z.object({
+    /** Public name (the alias when one is set, e.g. `sdsCell`). */
+    name: z.string(),
+    /** Resolved public type, e.g. `SdsButtonVariant`, `boolean`, `Date | null`. */
+    type: z.string(),
+    /** Default literal as written in source, or null for required/computed defaults. */
+    default: z.string().nullable(),
+    required: z.boolean(),
+    /** Coercion applied via `transform:` (widens the accepted type), or null. */
+    transform: TransformKind.nullable(),
+    /** Set when the public input name differs from the class property name. */
+    alias: z.string().nullable(),
+    /** Doc-comment on the input property, if any. */
+    jsdoc: z.string().nullable(),
+});
+export const OutputSchema = z.object({
+    name: z.string(),
+    /** Event payload type. */
+    type: z.string(),
+    /** True when synthesized from a `model()` two-way binding (`<name>Change`). */
+    fromModel: z.boolean(),
+});
+export const ExportedTypeSchema = z.object({
+    name: z.string(),
+    kind: z.enum(['union', 'interface', 'type', 'const']),
+    /** The declaration body / right-hand side, trimmed for display. */
+    body: z.string(),
+});
+export const ExampleSchema = z.object({
+    sectionTitle: z.string(),
+    sectionDescription: z.string().nullable(),
+    /** The curated, copyable snippet (the `C`-map value) — the source of truth. */
+    code: z.string(),
+    /** The live projected markup from the showcase `<app-demo>`, if captured. */
+    runnableExample: z.string().nullable(),
+    stack: z.boolean(),
+    dark: z.boolean(),
+});
+export const ComponentGroup = z.enum([
+    'primitive',
+    'form',
+    'layout',
+    'data',
+]);
+export const ComponentSchema = z.object({
+    className: z.string(),
+    selector: z.string(),
+    kind: z.enum(['component', 'directive']),
+    group: ComponentGroup,
+    /** Class name(s) a consumer must import, comma-joined for compound widgets. */
+    importName: z.string(),
+    /** Curated FR description from the showcase `<app-doc-page description>`. */
+    description: z.string().nullable(),
+    /** Shorter FR one-liner from the overview catalogue. */
+    overviewDescription: z.string().nullable(),
+    /** Class-level doc-comment text. */
+    jsdoc: z.string().nullable(),
+    /** Class-level `@example` snippet, if present. */
+    example: z.string().nullable(),
+    /** Implements ControlValueAccessor (its value is bound via ngModel/formControl, NOT [value]). */
+    cva: z.boolean(),
+    usesNgModel: z.boolean(),
+    inputs: InputSchema.array(),
+    outputs: OutputSchema.array(),
+    exportedTypes: ExportedTypeSchema.array(),
+    /** Named content-projection slots, e.g. `['[sdsIconLeading]','[sdsIconTrailing]']`. */
+    projectionSlots: z.string().array(),
+    /** `host: {}` bindings (class/attr/event), for documenting host behaviour. */
+    hostBindings: z.record(z.string(), z.string()),
+    examples: ExampleSchema.array(),
+});
+export const ServiceSchema = z.object({
+    className: z.string(),
+    providedIn: z.enum(['root', 'component']),
+    /** Public signals/methods/types the store exposes. */
+    exports: z.string().array(),
+    jsdoc: z.string().nullable(),
+});
+export const TokenSchema = z.object({
+    /** The `@theme` token name, e.g. `color-brand-600`. */
+    token: z.string(),
+    family: z.enum([
+        'brand',
+        'accent',
+        'ink',
+        'surface',
+        'radius',
+        'status',
+        'font',
+        'layout',
+    ]),
+    /** Example Tailwind utility, e.g. `bg-brand-600`. */
+    tailwindUtility: z.string().nullable(),
+    /** CSS variable reference, e.g. `var(--color-brand-600)`. */
+    cssVar: z.string(),
+    semanticNote: z.string().nullable(),
+});
+export const InstallSchema = z.object({
+    npmrc: z.string(),
+    installCommand: z.string(),
+    tailwindImport: z.string(),
+    sourceDirective: z.string(),
+    themeBlock: z.string(),
+    peerDeps: z.string().array(),
+    standaloneNote: z.string(),
+});
+export const DocIndexSchema = z.object({
+    /** Bumped when the shape below changes (independent of library version). */
+    schemaVersion: z.string(),
+    /** Read from projects/saitech-design-system/package.json — the library version these docs describe. */
+    libraryVersion: z.string(),
+    packageName: z.literal('@besaitech/ng-design-system'),
+    /** Bare specifier used inside this monorepo (tsconfig path alias). */
+    devImport: z.literal('saitech-design-system'),
+    generatedAt: z.string(),
+    componentCount: z.number(),
+    components: ComponentSchema.array(),
+    directives: ComponentSchema.array(),
+    services: ServiceSchema.array(),
+    icons: z.object({
+        names: z.string().array(),
+        /** Registry entries that deviate from the inner-SVG convention (e.g. `hand`). */
+        outliers: z.string().array(),
+    }),
+    tokens: TokenSchema.array(),
+    install: InstallSchema,
+});

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * saitech-design-system MCP server entry point.
+ *
+ * Default: load the bundled, version-stamped data/docs.json and serve over stdio
+ * (zero-config for Claude Code / Cursor / Windsurf, fully offline).
+ *
+ * Flags:
+ *   --source <repoRoot>   Contributor mode: regenerate the index from a working
+ *                         tree (runs scripts/generate-doc-index.ts if present)
+ *                         and serve that, so library edits show up build-free.
+ *   --data <path>         Serve a specific docs.json instead of the bundled one.
+ *   --http                Reserved for a future shared HTTP instance (not yet
+ *                         operated; falls back to stdio with a notice).
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildServer } from './server.js';
+import { loadIndex } from './load-index.js';
+function parseArgs(argv) {
+    const args = { http: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--source')
+            args.source = argv[++i];
+        else if (a === '--data')
+            args.data = argv[++i];
+        else if (a === '--http')
+            args.http = true;
+    }
+    return args;
+}
+function resolveDataPath(args) {
+    if (args.data)
+        return resolve(args.data);
+    if (args.source) {
+        const repo = resolve(args.source);
+        const generator = resolve(repo, 'scripts/generate-doc-index.ts');
+        const data = resolve(repo, 'packages/mcp-server/data/docs.json');
+        if (existsSync(generator)) {
+            try {
+                // Send generator output to our stderr so it never corrupts the stdio JSON-RPC stream.
+                execFileSync(process.execPath, [generator], { stdio: ['ignore', 2, 2] });
+            }
+            catch (err) {
+                console.error(`[saitech-design-system-mcp] --source regeneration failed; using existing index. ${String(err)}`);
+            }
+        }
+        if (existsSync(data))
+            return data;
+        console.error(`[saitech-design-system-mcp] --source index not found at ${data}; falling back to bundled.`);
+    }
+    return undefined; // bundled default
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.http) {
+        console.error('[saitech-design-system-mcp] --http is not operated yet; serving over stdio.');
+    }
+    const loaded = loadIndex(resolveDataPath(args));
+    const server = buildServer(loaded);
+    console.error(`[saitech-design-system-mcp] serving ${loaded.index.packageName}@${loaded.index.libraryVersion} ` +
+        `(${loaded.index.componentCount} components) over stdio`);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('[saitech-design-system-mcp] fatal:', err);
+    process.exit(1);
+});

package/dist/load-index.js

@@ -0,0 +1,109 @@
+/**
+ * Loads + zod-validates the bundled `data/docs.json` and builds the in-memory
+ * lookup structures the tools query. No AST or network at runtime: the heavy
+ * extraction already happened at build time.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { DocIndexSchema } from './doc-index.schema.js';
+/** Path to the bundled artifact, relative to the compiled dist/ directory. */
+function defaultDataPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, '../data/docs.json');
+}
+export function loadIndex(dataPath = defaultDataPath()) {
+    const raw = JSON.parse(readFileSync(dataPath, 'utf8'));
+    const index = DocIndexSchema.parse(raw);
+    const all = [...index.components, ...index.directives];
+    const byClass = new Map();
+    const bySelector = new Map();
+    for (const c of all) {
+        byClass.set(c.className.toLowerCase(), c);
+        bySelector.set(c.selector.toLowerCase(), c);
+    }
+    return {
+        index,
+        byClass,
+        bySelector,
+        all,
+        iconSet: new Set(index.icons.names),
+    };
+}
+/** Resolve a component by class name (`SdsButton`), selector (`sds-button`), or bare (`button`). */
+export function resolveComponent(loaded, query) {
+    const q = query.trim().toLowerCase();
+    return (loaded.bySelector.get(q) ??
+        loaded.byClass.get(q) ??
+        loaded.bySelector.get(`sds-${q}`) ??
+        loaded.byClass.get(`sds${q.replace(/-/g, '')}`) ??
+        loaded.all.find((c) => c.selector.includes(q) || c.className.toLowerCase().includes(q)) ??
+        null);
+}
+/** The published import line for a component. */
+export function importLine(loaded, c) {
+    return `import { ${c.importName} } from '${loaded.index.packageName}';`;
+}
+export function searchIndex(loaded, query, limit = 8) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const hits = [];
+    for (const c of loaded.all) {
+        let best = null;
+        const consider = (field, value, weight) => {
+            if (!value)
+                return;
+            const idx = value.toLowerCase().indexOf(q);
+            if (idx === -1)
+                return;
+            // exact field equality scores highest, then prefix, then substring.
+            const score = weight + (value.toLowerCase() === q ? 100 : idx === 0 ? 40 : 20) - Math.min(idx, 19);
+            if (!best || score > best.score) {
+                best = { field, snippet: value.slice(0, 140), score };
+            }
+        };
+        consider('className', c.className, 60);
+        consider('selector', c.selector, 60);
+        consider('description', c.description, 30);
+        consider('overviewDescription', c.overviewDescription, 30);
+        for (const i of c.inputs)
+            consider(`input:${i.name}`, i.name, 25);
+        for (const t of c.exportedTypes)
+            consider(`type:${t.name}`, t.name, 20);
+        for (const e of c.examples)
+            consider(`example:${e.sectionTitle}`, e.sectionTitle, 15);
+        if (best) {
+            const b = best;
+            hits.push({ className: c.className, selector: c.selector, matchedField: b.field, snippet: b.snippet, score: b.score });
+        }
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, limit);
+}
+function editDistance(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 0; 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] =
+                a[i - 1] === b[j - 1]
+                    ? dp[i - 1][j - 1]
+                    : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[a.length][b.length];
+}
+/** Closest registered icon names for a (possibly mistyped) query. */
+export function suggestIcons(loaded, query, limit = 5) {
+    const q = query.trim().toLowerCase();
+    return [...loaded.iconSet]
+        .map((name) => ({
+        name,
+        d: name.includes(q) || q.includes(name) ? 0 : editDistance(q, name),
+    }))
+        .sort((a, b) => a.d - b.d)
+        .slice(0, limit)
+        .map((x) => x.name);
+}

package/dist/prompts.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+function userMessage(text) {
+    return { messages: [{ role: 'user', content: { type: 'text', text } }] };
+}
+export function registerPrompts(server, loaded) {
+    const pkg = loaded.index.packageName;
+    server.registerPrompt('sds_generate_component_usage', {
+        title: 'Generate saitech-design-system component usage',
+        description: 'Produce a correct, validated Angular 20 snippet that uses an saitech-design-system component.',
+        argsSchema: {
+            component: z.string().describe('Component class name, selector, or bare name (e.g. SdsButton).'),
+            intent: z.string().optional().describe('What the snippet should do, e.g. "a save button with a leading icon".'),
+        },
+    }, ({ component, intent }) => userMessage(`Generate an Angular 20 (standalone, signals) snippet that uses the saitech-design-system component "${component}"` +
+        (intent ? ` to: ${intent}.` : '.') +
+        `\n\nSteps:\n` +
+        `1. Call sds_get_component with name="${component}" to get its inputs, outputs, enum types, projection slots and whether it is a ControlValueAccessor.\n` +
+        `2. Call sds_get_examples with name="${component}" for a copyable starting point.\n` +
+        `3. Emit a self-contained component: import { ... } from '${pkg}', add it to the standalone component's imports array, and use only valid selectors, input names and enum values. For any <sds-icon name="…">, only use names you confirmed with sds_validate_icon.\n` +
+        `4. Finally, call sds_validate_usage on your generated template and fix every error it reports.`));
+    server.registerPrompt('sds_scaffold_form', {
+        title: 'Scaffold an saitech-design-system reactive form',
+        description: 'Wire saitech-design-system form controls with Angular reactive forms, respecting their ControlValueAccessor contract.',
+        argsSchema: {
+            fields: z.string().describe('Comma-separated fields, e.g. "name:input, birthDate:date-picker, role:select".'),
+        },
+    }, ({ fields }) => userMessage(`Scaffold an Angular 20 reactive form using saitech-design-system form controls for these fields: ${fields}.\n\n` +
+        `Rules:\n` +
+        `- Use ReactiveFormsModule + a FormGroup; bind each control with formControlName.\n` +
+        `- saitech-design-system form controls (SdsInput, SdsTextarea, SdsSelect, SdsMultiSelect, SdsDatePicker, SdsCheckbox, SdsToggleSwitch, SdsPhoneInput) implement ControlValueAccessor — their value flows through the form control, NEVER via a [value] binding.\n` +
+        `- Call sds_get_component for each control to get correct inputs (label, hint, error, size, options, etc.) and import them from '${pkg}'.\n` +
+        `- Validate the final template with sds_validate_usage.`));
+    server.registerPrompt('sds_build_data_table', {
+        title: 'Build an saitech-design-system data table',
+        description: 'Assemble SdsTable with columns, custom cell templates, selection and pagination.',
+        argsSchema: {
+            columns: z.string().describe('Comma-separated columns, e.g. "name, service, status".'),
+            features: z.string().optional().describe('Optional features, e.g. "selection, pagination, custom status cell".'),
+        },
+    }, ({ columns, features }) => userMessage(`Build an SdsTable for columns: ${columns}.` +
+        (features ? ` Features: ${features}.` : '') +
+        `\n\nSteps:\n` +
+        `1. Call sds_get_component for SdsTable (note its inputs like [value], [columns], selectionMode, and its two-way [(selection)] model) and for SdsTableCell (the structural directive, public input alias "sdsCell") and SdsPaginator if pagination is requested.\n` +
+        `2. Call sds_get_examples for sds-table to see the column-definition and <ng-template sdsCell> patterns.\n` +
+        `3. Import the needed classes from '${pkg}'. Use <ng-template sdsCell="field"> for custom cells.\n` +
+        `4. Validate the final template with sds_validate_usage.`));
+}

package/dist/render.js

@@ -0,0 +1,102 @@
+/** Escape `|` so union types don't break Markdown table cells. */
+function cell(text) {
+    return text.replace(/\|/g, '\\|');
+}
+function inputRow(i) {
+    const flags = [
+        i.required ? 'required' : '',
+        i.transform ? `transform: ${i.transform}` : '',
+        i.alias ? `alias: ${i.alias}` : '',
+    ]
+        .filter(Boolean)
+        .join('; ');
+    const notes = [i.jsdoc ?? '', flags].filter(Boolean).join(' — ');
+    return `| \`${cell(i.name)}\` | \`${cell(i.type)}\` | ${i.default === null ? '—' : `\`${cell(i.default)}\``} | ${cell(notes || '')} |`;
+}
+export function renderComponentMarkdown(index, c) {
+    const out = [];
+    out.push(`# ${c.className} \`<${c.selector}>\``);
+    out.push('');
+    if (c.description)
+        out.push(c.description, '');
+    out.push('```ts', `import { ${c.importName} } from '${index.packageName}';`, '```', '');
+    if (c.cva) {
+        out.push('> ControlValueAccessor: bind the value with `[(ngModel)]` or `formControlName`, never `[value]`.', '');
+    }
+    if (c.inputs.length) {
+        out.push('## Inputs', '', '| name | type | default | notes |', '| --- | --- | --- | --- |');
+        for (const i of c.inputs)
+            out.push(inputRow(i));
+        out.push('');
+    }
+    if (c.outputs.length) {
+        out.push('## Outputs', '', '| name | payload | source |', '| --- | --- | --- |');
+        for (const o of c.outputs)
+            out.push(`| \`${cell(o.name)}\` | \`${cell(o.type)}\` | ${o.fromModel ? 'model two-way' : 'output'} |`);
+        out.push('');
+    }
+    if (c.projectionSlots.length) {
+        out.push('## Content projection', '', c.projectionSlots.map((s) => `- \`${s}\``).join('\n'), '');
+    }
+    if (c.exportedTypes.length) {
+        out.push('## Exported types', '');
+        for (const t of c.exportedTypes)
+            out.push(`- \`${t.name}\` (${t.kind}): \`${t.body}\``);
+        out.push('');
+    }
+    if (c.examples.length) {
+        out.push('## Examples', '');
+        for (const e of c.examples) {
+            out.push(`### ${e.sectionTitle}`);
+            if (e.sectionDescription)
+                out.push('', e.sectionDescription);
+            out.push('', '```html', e.code, '```', '');
+        }
+    }
+    return out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+export function renderLlmsTxt(index) {
+    const out = [];
+    out.push(`# saitech-design-system (${index.packageName}) v${index.libraryVersion}`);
+    out.push('');
+    out.push('> Angular 20 standalone component library (StaffKit / Cliniques universitaires Saitech), ' +
+        'styled with Tailwind CSS v4. Components are `Sds*` classes with `sds-*` selectors. ' +
+        'Generated from source; do not hand-edit.');
+    out.push('');
+    out.push('## Setup');
+    out.push(`- Install: \`${index.install.installCommand}\` (private GitLab registry — see .npmrc below)`);
+    out.push(`- Import: \`import { SdsButton } from '${index.packageName}';\``);
+    out.push('- Tailwind v4 is required in the consuming app: `@import "tailwindcss";`, the `@source` directive for the package, and the full `@theme` token block — otherwise components render unstyled.');
+    out.push('');
+    const groups = ['primitive', 'form', 'layout', 'data'];
+    out.push('## Components');
+    for (const g of groups) {
+        const items = index.components.filter((c) => c.group === g);
+        if (!items.length)
+            continue;
+        out.push('', `### ${g}`);
+        for (const c of items) {
+            const desc = c.overviewDescription ?? c.description ?? '';
+            out.push(`- [${c.className}](components/${c.selector}.md) \`<${c.selector}>\`${desc ? ` — ${desc}` : ''}`);
+        }
+    }
+    out.push('');
+    if (index.directives.length) {
+        out.push('## Directives');
+        for (const d of index.directives)
+            out.push(`- [${d.className}](components/${d.selector.replace(/[^a-z0-9-]/gi, '-')}.md) \`${d.selector}\``);
+        out.push('');
+    }
+    out.push('## Design tokens');
+    out.push('Defined in `@theme {}` (Tailwind utilities + CSS variables). Families: ' +
+        [...new Set(index.tokens.map((t) => t.family))].join(', ') + '.');
+    out.push('');
+    out.push('## Icons');
+    out.push(`\`<sds-icon name="…">\` — ${index.icons.names.length} registered names: ` + index.icons.names.join(', ') + '.');
+    out.push('');
+    return out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+/** Filesystem-safe markdown filename for a selector (directives have `[...]`). */
+export function markdownSlug(selector) {
+    return selector.replace(/[^a-z0-9-]/gi, '-');
+}