@besaitech/ng-design-system-mcp 0.0.5

package/dist/server.js

@@ -0,0 +1,225 @@
+/**
+ * Builds the MCP server: registers the documentation tools, resources and
+ * prompts over the loaded doc-index. Every tool answers from in-memory lookups.
+ */
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { importLine, resolveComponent, searchIndex, suggestIcons, } from './load-index.js';
+import { validateUsage } from './validate-usage.js';
+import { registerPrompts } from './prompts.js';
+import { markdownSlug, renderComponentMarkdown, renderLlmsTxt } from './render.js';
+function json(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+function errorText(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+export function buildServer(loaded) {
+    const { index } = loaded;
+    const server = new McpServer({
+        name: 'saitech-design-system',
+        version: index.libraryVersion,
+    });
+    // --- Tools ----------------------------------------------------------------
+    server.registerTool('sds_list_components', {
+        title: 'List saitech-design-system components',
+        description: 'List the saitech-design-system design-system components (and directives/services). Start here to discover what is available before generating code.',
+        inputSchema: {
+            kind: z.enum(['component', 'directive', 'service']).optional().describe('Filter by kind (default: component).'),
+            group: z.enum(['primitive', 'form', 'layout', 'data']).optional().describe('Filter components by group.'),
+        },
+    }, async ({ kind, group }) => {
+        const k = kind ?? 'component';
+        if (k === 'service') {
+            return json(index.services);
+        }
+        const source = k === 'directive' ? index.directives : index.components;
+        const list = source
+            .filter((c) => (group ? c.group === group : true))
+            .map((c) => ({
+            className: c.className,
+            selector: c.selector,
+            group: c.group,
+            importName: c.importName,
+            hasExample: c.examples.length > 0,
+            description: c.overviewDescription ?? c.description ?? null,
+        }));
+        return json({ count: list.length, components: list });
+    });
+    server.registerTool('sds_get_component', {
+        title: 'Get saitech-design-system component API',
+        description: 'Full API for one component: inputs (with types, defaults, transforms, required, alias), outputs (including synthesized two-way `model()` change-outputs), exported types, content-projection slots, host bindings, the import line, and whether it is a ControlValueAccessor (bind value via ngModel/formControl, not [value]). The primary lookup before writing saitech-design-system markup.',
+        inputSchema: {
+            name: z
+                .string()
+                .describe('Component class name (SdsButton), selector (sds-button), or bare name (button).'),
+        },
+    }, async ({ name }) => {
+        const c = resolveComponent(loaded, name);
+        if (!c) {
+            const near = searchIndex(loaded, name, 5).map((h) => h.selector);
+            return errorText(`No saitech-design-system component matches "${name}". Closest: ${near.join(', ') || '(none)'}. ` +
+                `Use sds_list_components to see all.`);
+        }
+        return json({ ...c, importLine: importLine(loaded, c) });
+    });
+    server.registerTool('sds_get_examples', {
+        title: 'Get saitech-design-system usage examples',
+        description: 'Curated, copyable usage snippets for a component, grouped by their (French) section taxonomy. The `code` field is the canonical doc snippet to copy; `runnableExample` is the live demo markup.',
+        inputSchema: {
+            name: z.string().describe('Component class name, selector, or bare name.'),
+            section: z.string().optional().describe('Filter to sections whose title contains this text.'),
+        },
+    }, async ({ name, section }) => {
+        const c = resolveComponent(loaded, name);
+        if (!c)
+            return errorText(`No saitech-design-system component matches "${name}".`);
+        let examples = c.examples;
+        if (section) {
+            const s = section.toLowerCase();
+            examples = examples.filter((e) => e.sectionTitle.toLowerCase().includes(s));
+        }
+        if (examples.length === 0) {
+            return json({ selector: c.selector, examples: [], note: 'No curated examples for this component.' });
+        }
+        return json({ selector: c.selector, importLine: importLine(loaded, c), examples });
+    });
+    server.registerTool('sds_search', {
+        title: 'Search saitech-design-system docs',
+        description: 'Keyword search across component names, selectors, descriptions, input names, exported types and example section titles.',
+        inputSchema: {
+            query: z.string().describe('Search terms, e.g. "date", "selection", "icon button".'),
+            limit: z.number().int().min(1).max(30).optional().describe('Max results (default 8).'),
+        },
+    }, async ({ query, limit }) => {
+        return json({ query, results: searchIndex(loaded, query, limit ?? 8) });
+    });
+    server.registerTool('sds_validate_usage', {
+        title: 'Validate saitech-design-system markup',
+        description: 'Lint a candidate Angular snippet against the saitech-design-system API: unknown selectors, invalid input names, invalid enum values, missing required inputs, unregistered icon names, and binding [value] on a ControlValueAccessor control. Run this after generating saitech-design-system markup.',
+        inputSchema: {
+            code: z.string().describe('The Angular template / component snippet to check.'),
+        },
+    }, async ({ code }) => json(validateUsage(loaded, code)));
+    server.registerTool('sds_validate_icon', {
+        title: 'Validate an sds-icon name',
+        description: 'Check whether an icon name is registered in SDS_ICONS (an unregistered <sds-icon name> renders nothing). Returns near-miss suggestions when invalid.',
+        inputSchema: {
+            name: z.string().describe('Icon name, e.g. "search", "calendar".'),
+        },
+    }, async ({ name }) => {
+        const valid = loaded.iconSet.has(name);
+        return json({ name, valid, suggestions: valid ? [] : suggestIcons(loaded, name) });
+    });
+    server.registerTool('sds_get_token', {
+        title: 'Get saitech-design-system design tokens',
+        description: 'Look up design tokens (colors, radii, status, layout) with their Tailwind utility and CSS variable. Omit args to list all.',
+        inputSchema: {
+            name: z.string().optional().describe('Exact or partial token name, e.g. "brand-600".'),
+            family: z
+                .enum(['brand', 'accent', 'ink', 'surface', 'radius', 'status', 'font', 'layout'])
+                .optional()
+                .describe('Filter by token family.'),
+        },
+    }, async ({ name, family }) => {
+        let tokens = index.tokens;
+        if (family)
+            tokens = tokens.filter((t) => t.family === family);
+        if (name) {
+            const n = name.toLowerCase();
+            tokens = tokens.filter((t) => t.token.toLowerCase().includes(n));
+        }
+        return json({ count: tokens.length, tokens });
+    });
+    server.registerTool('sds_get_setup', {
+        title: 'Get saitech-design-system install & Tailwind setup',
+        description: 'The install + Tailwind v4 setup checklist (registry .npmrc, install command, @import/@source/@theme, peer deps, standalone usage). The #1 source of "components render unstyled" issues.',
+        inputSchema: {
+            context: z.enum(['consumer', 'contributor']).optional().describe('Audience (default: consumer).'),
+        },
+    }, async ({ context }) => {
+        return json({
+            packageName: index.packageName,
+            libraryVersion: index.libraryVersion,
+            devImport: index.devImport,
+            context: context ?? 'consumer',
+            ...index.install,
+        });
+    });
+    // --- Resources ------------------------------------------------------------
+    server.registerResource('docs', 'sds://docs.json', {
+        title: 'Full saitech-design-system doc index',
+        description: 'The entire generated documentation index as JSON.',
+        mimeType: 'application/json',
+    }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(index, null, 2) }],
+    }));
+    server.registerResource('meta', 'sds://meta', {
+        title: 'saitech-design-system doc index metadata',
+        description: 'Version + provenance of the doc index, so the agent can confirm which library version it is coding against.',
+        mimeType: 'application/json',
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'application/json',
+                text: JSON.stringify({
+                    packageName: index.packageName,
+                    libraryVersion: index.libraryVersion,
+                    schemaVersion: index.schemaVersion,
+                    generatedAt: index.generatedAt,
+                    componentCount: index.componentCount,
+                }, null, 2),
+            },
+        ],
+    }));
+    server.registerResource('component', new ResourceTemplate('sds://component/{name}', {
+        list: async () => ({
+            resources: loaded.all.map((c) => ({
+                uri: `sds://component/${c.selector}`,
+                name: c.className,
+                mimeType: 'application/json',
+            })),
+        }),
+    }), {
+        title: 'saitech-design-system component record',
+        description: 'A single component doc record addressable by selector or class name.',
+    }, async (uri, { name }) => {
+        const c = resolveComponent(loaded, Array.isArray(name) ? name[0] : name);
+        if (!c) {
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ error: `unknown component "${name}"` }) }] };
+        }
+        return {
+            contents: [
+                { uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ ...c, importLine: importLine(loaded, c) }, null, 2) },
+            ],
+        };
+    });
+    server.registerResource('llms', 'sds://llms.txt', {
+        title: 'saitech-design-system llms.txt',
+        description: 'Compact llms.txt index of the whole library for tools that ingest it directly.',
+        mimeType: 'text/markdown',
+    }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: 'text/markdown', text: renderLlmsTxt(index) }],
+    }));
+    server.registerResource('component-md', new ResourceTemplate('sds://components/{selector}.md', {
+        list: async () => ({
+            resources: loaded.all.map((c) => ({
+                uri: `sds://components/${markdownSlug(c.selector)}.md`,
+                name: `${c.className} (Markdown)`,
+                mimeType: 'text/markdown',
+            })),
+        }),
+    }), {
+        title: 'saitech-design-system component card (Markdown)',
+        description: 'A per-component Markdown reference card.',
+    }, async (uri, { selector }) => {
+        const sel = Array.isArray(selector) ? selector[0] : selector;
+        const c = resolveComponent(loaded, sel.replace(/\.md$/, ''));
+        const text = c ? renderComponentMarkdown(index, c) : `# Unknown component "${sel}"`;
+        return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text }] };
+    });
+    // --- Prompts --------------------------------------------------------------
+    registerPrompts(server, loaded);
+    return server;
+}

package/dist/validate-usage.js

@@ -0,0 +1,162 @@
+import { suggestIcons } from './load-index.js';
+/** Attributes that are valid on any element and are not component inputs. */
+const GLOBAL_ATTRS = new Set([
+    'class', 'style', 'id', 'title', 'hidden', 'role', 'slot', 'tabindex', 'value',
+    'ngclass', 'ngstyle', 'ngmodel', 'formcontrol', 'formcontrolname', 'formgroupname',
+    'routerlink', 'routerlinkactive', 'routerlinkactiveoptions',
+]);
+function parseAttrs(blob) {
+    const attrs = [];
+    let rest = blob;
+    const push = (raw, name, form, value) => {
+        attrs.push({ raw, name, form, value });
+    };
+    // [(x)]="..."  two-way
+    rest = rest.replace(/\[\(([\w-]+)\)\]\s*=\s*"([^"]*)"/g, (_m, n, v) => {
+        push(`[(${n})]`, n, 'two-way', v);
+        return ' ';
+    });
+    // [x]="..."  property
+    rest = rest.replace(/\[([\w.-]+)\]\s*=\s*"([^"]*)"/g, (_m, n, v) => {
+        push(`[${n}]`, n, 'prop', v);
+        return ' ';
+    });
+    // (x)="..."  event
+    rest = rest.replace(/\(([\w-]+)\)\s*=\s*"([^"]*)"/g, (_m, n, v) => {
+        push(`(${n})`, n, 'event', v);
+        return ' ';
+    });
+    // x="..."  plain
+    rest = rest.replace(/([@*#]?[\w-]+)\s*=\s*"([^"]*)"/g, (_m, n, v) => {
+        push(n, n, 'plain', v);
+        return ' ';
+    });
+    // bare boolean attributes left over
+    for (const m of rest.matchAll(/(?:^|\s)([a-zA-Z][\w-]*)(?=\s|$)/g)) {
+        push(m[1], m[1], 'bool', null);
+    }
+    return attrs;
+}
+/** String-literal members of an input's enum type, if it is one. */
+function enumValues(component, inputType) {
+    // inline union: 'a' | 'b'
+    if (inputType.includes("'")) {
+        const vals = [...inputType.matchAll(/'([^']*)'/g)].map((m) => m[1]);
+        if (vals.length > 1)
+            return vals;
+    }
+    // named union exported alongside the component
+    const t = component.exportedTypes.find((e) => e.name === inputType.replace(/\s*\|\s*null$/, ''));
+    if (t && t.kind === 'union' && t.body.includes("'")) {
+        return [...t.body.matchAll(/'([^']*)'/g)].map((m) => m[1]);
+    }
+    return null;
+}
+function isIconInput(inputType) {
+    return inputType.replace(/\s/g, '').includes('SdsIconName');
+}
+function closest(name, candidates) {
+    const n = name.toLowerCase();
+    return candidates.find((c) => c.toLowerCase().includes(n) || n.includes(c.toLowerCase()));
+}
+export function validateUsage(loaded, code) {
+    const diagnostics = [];
+    const tagRe = /<(sds-[a-z0-9-]+)((?:\s+[^>]*?)?)\s*\/?>/g;
+    let m;
+    let sawTag = false;
+    while ((m = tagRe.exec(code)) !== null) {
+        sawTag = true;
+        const selector = m[1];
+        const blob = m[2] ?? '';
+        const component = loaded.bySelector.get(selector);
+        if (!component) {
+            diagnostics.push({
+                severity: 'error',
+                selector,
+                message: `Unknown selector <${selector}>.`,
+                suggestion: closest(selector.replace('sds-', ''), loaded.all.map((c) => c.selector)),
+            });
+            continue;
+        }
+        const inputByName = new Map(component.inputs.map((i) => [i.name.toLowerCase(), i]));
+        const outputNames = new Set(component.outputs.map((o) => o.name.toLowerCase()));
+        const attrs = parseAttrs(blob);
+        const present = new Set(attrs.map((a) => a.name.toLowerCase()));
+        for (const attr of attrs) {
+            const lname = attr.name.toLowerCase();
+            if (attr.form === 'event') {
+                // outputs / DOM events: only flag if it looks like an unknown component output
+                continue;
+            }
+            if (attr.name.startsWith('*') || attr.name.startsWith('#') || attr.name.startsWith('@'))
+                continue;
+            if (lname.startsWith('aria-') || lname.startsWith('data-'))
+                continue;
+            if (GLOBAL_ATTRS.has(lname)) {
+                // [value] bound on a CVA control is the classic mistake
+                if (lname === 'value' && component.cva && (attr.form === 'prop' || attr.form === 'two-way' || attr.form === 'plain')) {
+                    diagnostics.push({
+                        severity: 'warning',
+                        selector,
+                        input: 'value',
+                        message: `<${selector}> is a ControlValueAccessor: bind its value with [(ngModel)] or formControlName, not [value].`,
+                    });
+                }
+                continue;
+            }
+            const input = inputByName.get(lname);
+            if (!input) {
+                // not an input — maybe a model change-event already handled, otherwise unknown
+                if (!outputNames.has(lname)) {
+                    diagnostics.push({
+                        severity: 'warning',
+                        selector,
+                        input: attr.name,
+                        message: `Unknown input "${attr.name}" on <${selector}>.`,
+                        suggestion: closest(attr.name, component.inputs.map((i) => i.name)),
+                    });
+                }
+                continue;
+            }
+            // enum validation for plain string values
+            if (attr.form === 'plain' && attr.value !== null) {
+                const values = enumValues(component, input.type);
+                if (values && !values.includes(attr.value)) {
+                    diagnostics.push({
+                        severity: 'error',
+                        selector,
+                        input: input.name,
+                        message: `Invalid value "${attr.value}" for ${input.name} on <${selector}>. Allowed: ${values.map((v) => `'${v}'`).join(', ')}.`,
+                    });
+                }
+                if (isIconInput(input.type) && !loaded.iconSet.has(attr.value)) {
+                    diagnostics.push({
+                        severity: 'error',
+                        selector,
+                        input: input.name,
+                        message: `Icon "${attr.value}" is not registered (SDS_ICONS).`,
+                        suggestion: suggestIcons(loaded, attr.value, 3).join(', '),
+                    });
+                }
+            }
+        }
+        // missing required inputs
+        for (const input of component.inputs) {
+            if (input.required && !present.has(input.name.toLowerCase())) {
+                diagnostics.push({
+                    severity: 'error',
+                    selector,
+                    input: input.name,
+                    message: `Missing required input "${input.name}" on <${selector}>.`,
+                });
+            }
+        }
+    }
+    if (!sawTag) {
+        diagnostics.push({
+            severity: 'warning',
+            message: 'No <sds-*> elements found in the snippet — nothing to validate.',
+        });
+    }
+    return { ok: !diagnostics.some((d) => d.severity === 'error'), diagnostics };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@besaitech/ng-design-system-mcp",
+  "version": "0.0.5",
+  "description": "MCP server that exposes the @besaitech/ng-design-system Angular component library documentation (API, examples, tokens, icons, setup) to AI coding tools.",
+  "type": "module",
+  "bin": {
+    "saitech-design-system-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "data/docs.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "angular",
+    "design-system",
+    "saitech-design-system"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}