@ng-solid/mcp 22.0.0

package/lib/prompts.js

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+const INVARIANTS = `Non-negotiable ng-solid invariants:
+1. Single entrypoint: every import comes from "@ng-solid/design-system" (or "@ng-solid/icons" for provideIcons/icon symbols). There are no secondary entrypoints.
+2. Standalone components MUST declare every ng-solid class they use in their own \`imports: [...]\` array -- a component like <ns-button> silently fails to render otherwise. Call get_component_import (or get_component) for the exact class name before writing markup.
+3. Templates use ONLY ns-* BEM classes (ns-block__element--modifier). Never use a Tailwind utility class (flex, gap-2, text-sm, ...) directly in markup -- Tailwind is composed in component SCSS via @apply, never in templates.
+4. Never invent an input value. Closed unions (variant, size, placement, ...) only accept the values returned by get_component_api -- e.g. ns-button's \`variant\` accepts exactly primary/secondary/tertiary/success/danger, nothing else.
+5. Component SCSS reads only \`--ns-component-*\` custom properties, starts with \`@reference '../theme/tailwind.css'\`, and never uses raw hex/rgb()/px/rem/ms literals or \`@use\`/\`@import\`.
+6. \`provideNsTheme(...)\` is called exactly once, in the app's root providers (\`appConfig.providers\`) -- never per-component or per-route.
+7. Before finishing, run validate_component_usage on the markup you wrote and validate_style_contract on any new template/SCSS -- both are cheap and catch exactly the mistakes above.`;
+export function registerPrompts(server) {
+    server.registerPrompt('build_ns_ui', {
+        title: 'Build a UI with ng-solid',
+        description: 'Scaffolds a plan for building a piece of UI using ng-solid components, front-loaded with the invariants that most often get skipped.',
+        argsSchema: {
+            request: z
+                .string()
+                .describe('What to build, e.g. "a settings page with a theme switch and a save button".')
+        }
+    }, ({ request }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Build the following UI using the ng-solid (Arvisfy) design system: ${request}
+
+${INVARIANTS}
+
+Workflow:
+1. Call suggest_component or search_components for each UI need to find the right ng-solid component(s) -- do not guess a selector.
+2. For each component you plan to use, call get_component_api to get its real inputs/outputs/models/values, and get_component_import for its exact import.
+3. Write the standalone component: declare every used ng-solid class in \`imports: [...]\`, bind only documented inputs with only documented values.
+4. Validate the markup with validate_component_usage before presenting it as done.`
+                }
+            }
+        ]
+    }));
+    server.registerPrompt('review_ns_usage', {
+        title: 'Review ng-solid usage',
+        description: 'Reviews a piece of Angular code that uses ng-solid components for API misuse and style-contract violations.',
+        argsSchema: {
+            code: z
+                .string()
+                .describe('The component template and/or TypeScript source to review.')
+        }
+    }, ({ code }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Review this ng-solid usage for correctness:
+
+\`\`\`
+${code}
+\`\`\`
+
+${INVARIANTS}
+
+For every ng-solid selector you find in the markup:
+1. Call get_component to confirm the selector is real and public (not an internal subcomponent).
+2. Call validate_component_usage with the surrounding template (and the file's \`imports: [...]\` array, if visible) to catch unknown inputs/outputs/models, invalid enum values, invented BEM classes, and a missing import.
+3. Call validate_style_contract on any inline template/SCSS for Tailwind-in-markup or raw-value violations.
+Report every finding with the exact fix, not just the failure.`
+                }
+            }
+        ]
+    }));
+    server.registerPrompt('choose_ns_component', {
+        title: 'Choose an ng-solid component',
+        description: 'Helps pick the right ng-solid component(s) for a UI need, disambiguating close options.',
+        argsSchema: {
+            need: z
+                .string()
+                .describe('The UI need, e.g. "let the user pick a date range" or "show a non-blocking success message".')
+        }
+    }, ({ need }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Which ng-solid component(s) best fit this need: "${need}"?
+
+Call suggest_component with this need, then get_component_api on the top 1-2 candidates to compare their real inputs/outputs before recommending one. If the need involves showing something transiently (a toast, a confirmation), check list_services / get_service first -- several ng-solid surfaces (toast, modal, drawer) are opened imperatively via a service, not placed in markup directly. Explain why the chosen component fits, including its import trio.`
+                }
+            }
+        ]
+    }));
+    server.registerPrompt('build_ns_form', {
+        title: 'Build a reactive form with ng-solid',
+        description: 'Scaffolds a reactive form using ng-solid form controls, respecting the shared ControlValueAccessor contract.',
+        argsSchema: {
+            fields: z
+                .string()
+                .describe('The fields the form needs, e.g. "email, password, accept-terms switch".')
+        }
+    }, ({ fields }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Build a reactive form with these fields: ${fields}
+
+${INVARIANTS}
+
+Form-specific rules:
+- Call list_form_controls to see every ng-solid control that implements ControlValueAccessor, then get_form_control_contract for each one you use -- most of their API (label, disabled, ariaLabel, ...) is INHERITED from a shared base class and won't show up if you only look at the component's own source.
+- Bind with \`formControlName\` inside a \`[formGroup]\`, or \`[(value)]\`/\`[(disabled)]\` model bindings for standalone usage -- never invent a plain \`[value]\` input on a control that models value as \`model()\`.
+- Wrap label/control/error groups with \`[nsField]\` where the design system expects it (check get_component_api's \`a11y\` section for aria-describedby wiring).
+- Finish by calling validate_component_usage on the assembled template.`
+                }
+            }
+        ]
+    }));
+    server.registerPrompt('theme_ns_app', {
+        title: 'Theme an ng-solid app',
+        description: 'Guides setting up or customizing the Arvisfy theme for an application.',
+        argsSchema: {
+            brand: z
+                .string()
+                .optional()
+                .describe('Optional brand description or target colors to reflect in the theme.')
+        }
+    }, ({ brand }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Set up ng-solid theming${brand ? ` for this brand: ${brand}` : ''}.
+
+Rules:
+- \`provideNsTheme({ preset: Arvisfy, colorScheme: 'system' })\` (or 'light'/'dark') is called exactly once, in the app's root providers -- get_provider("provideNsTheme") has the exact signature.
+- To customize, use \`defineNsPreset(Arvisfy, { ... })\` -- never copy/fork the Arvisfy preset object. Overrides follow the same 3-tier shape: \`primitive\` (raw values only), \`semantic.common\`/\`semantic.colorScheme.{light,dark}\` (reference \`{primitive.path}\`), \`components\` (reference \`{semantic.path}\`).
+- Before proposing an override tree, call validate_theme_preset with \`mode: "overrides"\` on it -- it enforces the same rules \`defineNsPreset\` enforces at runtime (safe primitive values, resolvable references, both-color-scheme coverage) so a bad override fails fast instead of rendering a broken value.
+- Use get_component_tokens / list_theme_tokens / resolve_token to find the exact token(s) that control the part of the UI you're changing, and get_token_drift to sanity-check you're not touching a token component SCSS doesn't actually read.`
+                }
+            }
+        ]
+    }));
+    server.registerPrompt('migrate_to_ns', {
+        title: 'Migrate to ng-solid',
+        description: 'Guides migrating UI code from another component library to ng-solid.',
+        argsSchema: {
+            library: z
+                .string()
+                .optional()
+                .describe('The library being migrated from, e.g. "Angular Material" or "PrimeNG".')
+        }
+    }, ({ library }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Migrate this UI${library ? ` from ${library}` : ''} to the ng-solid (Arvisfy) design system.
+
+${INVARIANTS}
+
+Workflow:
+1. For each source component, call search_all or suggest_component to find its closest ng-solid equivalent -- do not assume prop names carry over (e.g. ng-solid variants are a closed 5-value union, colors/themes are not free-form).
+2. Call get_component_api on the target to see its real inputs/outputs/models before rewriting bindings, and get_form_control_contract for anything used inside a form.
+3. Replace the source library's module imports and providers with the ng-solid equivalents (get_component_import, get_provider) -- remove the old library's module/theme providers entirely, don't leave both wired up.
+4. Re-theme with get_provider("provideNsTheme") / theme_ns_app instead of porting the source library's theme config.
+5. Validate every rewritten template with validate_component_usage and validate_style_contract.`
+                }
+            }
+        ]
+    }));
+}
+//# sourceMappingURL=prompts.js.map

package/lib/resources.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerResources(server: McpServer): void;

package/lib/resources.js

@@ -0,0 +1,328 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { loadIcons, loadSnapshot } from './data.js';
+import { importTrio, renderComponentMarkdown, resolveComponent } from './tools.components.js';
+import { renderGuideMarkdown, resolveGuide } from './tools.guides.js';
+function variable(value) {
+    return Array.isArray(value) ? (value[0] ?? '') : value;
+}
+function json(value) {
+    return JSON.stringify(value, null, 2);
+}
+/**
+ * Resolves a skill's raw `SKILL.md` on disk, mirroring `data.ts`'s `resolveSnapshotPath`
+ * fallback chain (published layout vs. dev-with-tsx layout), but returning `null` instead of
+ * throwing -- skills are a Fase 5 deliverable and may not exist on disk yet.
+ */
+function resolveSkillFile(relativePath) {
+    const candidates = [
+        fileURLToPath(new URL(`../${relativePath}`, import.meta.url)),
+        fileURLToPath(new URL(`../../${relativePath}`, import.meta.url))
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function registerResources(server) {
+    server.registerResource('ns-component', new ResourceTemplate('ns://component/{selector}', {
+        list: async () => ({
+            resources: loadSnapshot()
+                .components.filter((c) => c.visibility === 'public')
+                .map((c) => ({
+                uri: `ns://component/${c.selector}`,
+                name: c.selector,
+                title: c.className,
+                description: c.summary,
+                mimeType: 'application/json'
+            }))
+        }),
+        complete: {
+            selector: (value) => loadSnapshot()
+                .components.map((c) => c.selector)
+                .filter((selector) => selector.startsWith(value))
+        }
+    }), {
+        title: 'ng-solid component doc',
+        description: 'Full ComponentDoc as JSON, including the import trio.',
+        mimeType: 'application/json'
+    }, async (uri, variables) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, variable(variables.selector));
+        if (!resolution.component) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: json({
+                            error: resolution.error,
+                            suggestions: resolution.suggestions
+                        })
+                    }
+                ]
+            };
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: json({
+                        ...importTrio(resolution.component),
+                        component: resolution.component
+                    })
+                }
+            ]
+        };
+    });
+    server.registerResource('ns-component-markdown', new ResourceTemplate('ns://component/{selector}/markdown', {
+        list: async () => ({
+            resources: loadSnapshot()
+                .components.filter((c) => c.visibility === 'public')
+                .map((c) => ({
+                uri: `ns://component/${c.selector}/markdown`,
+                name: c.selector,
+                title: `${c.className} (Markdown)`,
+                mimeType: 'text/markdown'
+            }))
+        }),
+        complete: {
+            selector: (value) => loadSnapshot()
+                .components.map((c) => c.selector)
+                .filter((selector) => selector.startsWith(value))
+        }
+    }), {
+        title: 'ng-solid component doc (Markdown)',
+        description: 'Human-readable component documentation.',
+        mimeType: 'text/markdown'
+    }, async (uri, variables) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, variable(variables.selector));
+        const text = resolution.component
+            ? renderComponentMarkdown(snapshot, resolution.component)
+            : `No component matches "${variable(variables.selector)}". Suggestions: ${(resolution.suggestions ?? []).join(', ')}`;
+        return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text }] };
+    });
+    server.registerResource('ns-guide', new ResourceTemplate('ns://guide/{slug}', {
+        list: async () => ({
+            resources: loadSnapshot().guides.map((g) => ({
+                uri: `ns://guide/${g.name}`,
+                name: g.name,
+                title: g.title,
+                description: g.description,
+                mimeType: 'text/markdown'
+            }))
+        }),
+        complete: {
+            slug: (value) => loadSnapshot()
+                .guides.map((g) => g.name)
+                .filter((name) => name.startsWith(value))
+        }
+    }), {
+        title: 'ng-solid guide',
+        description: 'Guide content generated from packages/mcp/skills/*/SKILL.md.',
+        mimeType: 'text/markdown'
+    }, async (uri, variables) => {
+        const snapshot = loadSnapshot();
+        if (snapshot.guides.length === 0) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: 'text/markdown',
+                        text: 'No guides in this snapshot yet.'
+                    }
+                ]
+            };
+        }
+        const resolution = resolveGuide(snapshot.guides, variable(variables.slug));
+        const text = resolution.guide
+            ? renderGuideMarkdown(resolution.guide)
+            : `No guide matches "${variable(variables.slug)}". Suggestions: ${(resolution.suggestions ?? []).join(', ')}`;
+        return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text }] };
+    });
+    server.registerResource('ns-skill', new ResourceTemplate('ns://skill/{slug}', {
+        list: async () => ({
+            resources: loadSnapshot().guides.map((g) => ({
+                uri: `ns://skill/${g.name}`,
+                name: g.name,
+                title: `${g.title} (raw SKILL.md)`,
+                mimeType: 'text/markdown'
+            }))
+        }),
+        complete: {
+            slug: (value) => loadSnapshot()
+                .guides.map((g) => g.name)
+                .filter((name) => name.startsWith(value))
+        }
+    }), {
+        title: 'Raw skill file',
+        description: 'The raw, front-matter-included SKILL.md a consumer would copy via `install-skills`.',
+        mimeType: 'text/markdown'
+    }, async (uri, variables) => {
+        const snapshot = loadSnapshot();
+        const slug = variable(variables.slug);
+        const guide = snapshot.guides.find((g) => g.name === slug);
+        const relativePath = guide?.skillPath ?? `skills/${slug}/SKILL.md`;
+        const filePath = resolveSkillFile(relativePath);
+        const text = filePath
+            ? readFileSync(filePath, 'utf8')
+            : `No SKILL.md found for "${slug}" (tried ${relativePath}). Skills ship in Fase 5.`;
+        return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text }] };
+    });
+    server.registerResource('ns-tokens-tier', new ResourceTemplate('ns://tokens/{tier}', {
+        list: async () => ({
+            resources: ['primitive', 'semantic', 'component'].map((tier) => ({
+                uri: `ns://tokens/${tier}`,
+                name: tier,
+                title: `${tier} tokens`,
+                mimeType: 'application/json'
+            }))
+        }),
+        complete: {
+            tier: (value) => ['primitive', 'semantic', 'component'].filter((tier) => tier.startsWith(value))
+        }
+    }), {
+        title: 'Theme tokens by tier',
+        description: 'Flattened tokens for one tier of the Arvisfy 3-tier preset.',
+        mimeType: 'application/json'
+    }, async (uri, variables) => {
+        const snapshot = loadSnapshot();
+        const tier = variable(variables.tier);
+        if (!snapshot.theme) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: json({ error: 'theme is missing from the snapshot.' })
+                    }
+                ]
+            };
+        }
+        const payload = tier === 'primitive'
+            ? snapshot.theme.tiers.primitive
+            : tier === 'semantic'
+                ? snapshot.theme.tiers.semantic
+                : tier === 'component'
+                    ? snapshot.theme.tiers.component
+                    : {
+                        error: `Unknown tier "${tier}". Expected primitive, semantic or component.`
+                    };
+        return {
+            contents: [
+                { uri: uri.href, mimeType: 'application/json', text: json(payload) }
+            ]
+        };
+    });
+    server.registerResource('ns-tokens-component-group', new ResourceTemplate('ns://tokens/component/{group}', {
+        list: async () => ({
+            resources: (loadSnapshot().theme?.componentGroups ?? []).map((group) => ({
+                uri: `ns://tokens/component/${group}`,
+                name: group,
+                title: `${group} tokens`,
+                mimeType: 'application/json'
+            }))
+        }),
+        complete: {
+            group: (value) => (loadSnapshot().theme?.componentGroups ?? []).filter((group) => group.startsWith(value))
+        }
+    }), {
+        title: 'Theme tokens by component group',
+        description: 'Component-tier tokens scoped to one group, e.g. "button".',
+        mimeType: 'application/json'
+    }, async (uri, variables) => {
+        const snapshot = loadSnapshot();
+        const group = variable(variables.group);
+        if (!snapshot.theme) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: json({ error: 'theme is missing from the snapshot.' })
+                    }
+                ]
+            };
+        }
+        const tokens = snapshot.theme.tiers.component.filter((t) => t.path === group || t.path.startsWith(`${group}.`));
+        return {
+            contents: [
+                { uri: uri.href, mimeType: 'application/json', text: json(tokens) }
+            ]
+        };
+    });
+    server.registerResource('ns-preset-arvisfy', 'ns://preset/arvisfy', {
+        title: 'The Arvisfy preset',
+        description: 'The full 3-tier Arvisfy theme preset, drift report and validation rules.',
+        mimeType: 'application/json'
+    }, async (uri) => {
+        const snapshot = loadSnapshot();
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: json(snapshot.theme ?? { error: 'theme is missing from the snapshot.' })
+                }
+            ]
+        };
+    });
+    server.registerResource('ns-icons-catalog', 'ns://icons/catalog', {
+        title: 'Icon catalog',
+        description: 'The full 1790-icon Lucide catalog (name <-> symbol <-> keywords, no SVG bodies).',
+        mimeType: 'application/json'
+    }, async (uri) => {
+        const icons = loadIcons();
+        return {
+            contents: [
+                { uri: uri.href, mimeType: 'application/json', text: json(icons) }
+            ]
+        };
+    });
+    server.registerResource('ns-style-contract', 'ns://contract/style', {
+        title: 'Style contract',
+        description: 'The style-architecture rules enforced by `pnpm quality:styles`.',
+        mimeType: 'application/json'
+    }, async (uri) => {
+        const snapshot = loadSnapshot();
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: json(snapshot.styleContract ?? {
+                        error: 'styleContract is missing from the snapshot.'
+                    })
+                }
+            ]
+        };
+    });
+    server.registerResource('ns-snapshot-stats', 'ns://snapshot/stats', {
+        title: 'Snapshot stats',
+        description: 'Component/service/token/icon counts and generation metadata for this snapshot.',
+        mimeType: 'application/json'
+    }, async (uri) => {
+        const snapshot = loadSnapshot();
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: json({
+                        schemaVersion: snapshot.schemaVersion,
+                        version: snapshot.version,
+                        generatedAt: snapshot.generatedAt,
+                        framework: snapshot.framework,
+                        packages: snapshot.packages,
+                        stats: snapshot.stats
+                    })
+                }
+            ]
+        };
+    });
+}
+//# sourceMappingURL=resources.js.map

package/lib/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createNsSolidMcpServer(): McpServer;
+export declare function runNsSolidMcpServer(): Promise<void>;

package/lib/server.js

@@ -0,0 +1,31 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadSnapshot } from './data.js';
+import { registerPrompts } from './prompts.js';
+import { registerResources } from './resources.js';
+import { registerTools } from './tools.js';
+export function createNsSolidMcpServer() {
+    const snapshot = loadSnapshot();
+    const server = new McpServer({
+        name: 'ng-solid',
+        version: snapshot.version,
+        title: 'ng-solid Arvisfy design system'
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {}
+        }
+    });
+    registerTools(server);
+    registerResources(server);
+    registerPrompts(server);
+    return server;
+}
+export async function runNsSolidMcpServer() {
+    const server = createNsSolidMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('ng-solid MCP server running on stdio');
+}
+//# sourceMappingURL=server.js.map

package/lib/style-contract.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure port of `tools/scripts/check-design-system-styles.mjs`.
+ *
+ * The original script walks the filesystem and calls `process.exit`. This module extracts
+ * the same rules into a pure function an MCP tool can run against a snippet an agent pastes,
+ * without touching disk. The three canonical regexes (BEM class shape, banned Tailwind
+ * utilities, raw CSS values) are NOT re-declared here -- they are read from
+ * `snapshot.styleContract` (`design-system.json`) so this module can never drift from the
+ * regexes the real `pnpm quality:styles` gate enforces.
+ */
+import type { StyleContractDoc } from './types.js';
+export type StyleContractKind = 'template' | 'scss' | 'component-ts';
+export interface StyleContractViolation {
+    ruleId: string;
+    severity: 'error' | 'warning';
+    message: string;
+    snippet: string;
+    line?: number;
+}
+export interface StyleContractResult {
+    valid: boolean;
+    violations: StyleContractViolation[];
+}
+/** Parses a stringified `RegExp` literal (e.g. `"/^ns-.../"` or `"/.../i"`) back into a RegExp. */
+export declare function parseRegexLiteral(literal: string): RegExp;
+/**
+ * Validates a code snippet against the ng-solid style-architecture contract.
+ *
+ * @param code the raw source text to validate (a template, a component SCSS file, or a
+ *   component `.ts` source)
+ * @param kind which contract rules apply -- `'template'` runs the BEM/Tailwind-utility checks,
+ *   `'scss'` runs the `@reference`/`@use`/raw-value checks, `'component-ts'` runs the
+ *   inline-`styles:` check plus the template checks (component `.ts` files can carry an inline
+ *   template)
+ * @param contract `snapshot.styleContract` -- the canonical rule/pattern set, never duplicated here
+ */
+export declare function validateStyleContract(code: string, kind: StyleContractKind, contract: StyleContractDoc): StyleContractResult;