@ng-solid/mcp 22.0.0

package/lib/tools.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Registers the full ng-solid MCP tool catalog (~32 tools), grouped by concern:
+ *  - discovery, API, forms, services/providers, style validation -> tools.components.ts
+ *  - the Arvisfy token pipeline + theme-preset validation           -> tools.tokens.ts
+ *  - the Lucide icon catalog                                        -> tools.icons.ts
+ *  - guides + server metadata                                       -> tools.guides.ts
+ */
+export declare function registerTools(server: McpServer): void;

package/lib/tools.guides.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Guides and server metadata. `list_guides`/`get_guide` read `snapshot.guides`, generated by
+ * Fase 5's `extract-guides.mjs` from each skill's `SKILL.md`. That array is empty
+ * until Fase 5 lands -- both tools degrade to an explicit "no guides yet" note rather than
+ * erroring, since an empty catalog is a valid (if temporary) snapshot state.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { GuideDoc } from './types.js';
+export declare function resolveGuide(guides: GuideDoc[], input: string): {
+    guide: GuideDoc | null;
+    error?: string;
+    suggestions?: string[];
+};
+export declare function renderGuideMarkdown(guide: GuideDoc): string;
+export declare function registerGuideTools(server: McpServer): void;

package/lib/tools.guides.js

@@ -0,0 +1,103 @@
+/**
+ * Guides and server metadata. `list_guides`/`get_guide` read `snapshot.guides`, generated by
+ * Fase 5's `extract-guides.mjs` from each skill's `SKILL.md`. That array is empty
+ * until Fase 5 lands -- both tools degrade to an explicit "no guides yet" note rather than
+ * erroring, since an empty catalog is a valid (if temporary) snapshot state.
+ */
+import { z } from 'zod';
+import { jsonResult, loadIcons, loadSnapshot } from './data.js';
+import { jsonError, levenshtein } from './tools.components.js';
+export function resolveGuide(guides, input) {
+    const lower = input.trim().toLowerCase();
+    const exact = guides.find((g) => g.name.toLowerCase() === lower);
+    if (exact)
+        return { guide: exact };
+    const partial = guides.find((g) => g.name.toLowerCase().includes(lower));
+    if (partial)
+        return { guide: partial };
+    const scored = guides
+        .map((g) => ({ g, score: levenshtein(lower, g.name.toLowerCase()) }))
+        .sort((a, b) => a.score - b.score)
+        .slice(0, 5)
+        .map(({ g }) => g.name);
+    return {
+        guide: null,
+        error: `No guide named "${input}".`,
+        suggestions: scored
+    };
+}
+export function renderGuideMarkdown(guide) {
+    const lines = [
+        `# ${guide.title}`,
+        '',
+        guide.description,
+        ...guide.sections.flatMap((s) => ['', `## ${s.title}`, '', s.content])
+    ];
+    return lines.join('\n');
+}
+export function registerGuideTools(server) {
+    server.registerTool('list_guides', {
+        title: 'List guides',
+        description: 'Lists the ng-solid usage guides (install, theming, forms, icons, style contract, components) generated from the distributable skills.',
+        inputSchema: {}
+    }, async () => {
+        const snapshot = loadSnapshot();
+        if (snapshot.guides.length === 0) {
+            return jsonResult({
+                count: 0,
+                guides: [],
+                note: 'No guides in this snapshot yet -- Fase 5 populates snapshot.guides from packages/mcp/skills/*/SKILL.md.'
+            });
+        }
+        return jsonResult({
+            count: snapshot.guides.length,
+            guides: snapshot.guides.map((g) => ({
+                name: g.name,
+                title: g.title,
+                description: g.description
+            }))
+        });
+    });
+    server.registerTool('get_guide', {
+        title: 'Get a guide',
+        description: 'Returns the full Markdown body of one usage guide by name.',
+        inputSchema: {
+            guide: z.string().describe('Guide name, e.g. "ns-solid-forms".')
+        }
+    }, async ({ guide }) => {
+        const snapshot = loadSnapshot();
+        if (snapshot.guides.length === 0) {
+            return jsonError({
+                error: 'No guides in this snapshot yet -- Fase 5 populates snapshot.guides.'
+            });
+        }
+        const resolution = resolveGuide(snapshot.guides, guide);
+        if (!resolution.guide)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        return jsonResult({
+            name: resolution.guide.name,
+            title: resolution.guide.title,
+            markdown: renderGuideMarkdown(resolution.guide)
+        });
+    });
+    server.registerTool('get_version_info', {
+        title: 'Get ng-solid version info',
+        description: 'Returns the snapshot version and the design-system/icons package versions it was generated from.',
+        inputSchema: {}
+    }, async () => {
+        const snapshot = loadSnapshot();
+        const icons = loadIcons();
+        return jsonResult({
+            schemaVersion: snapshot.schemaVersion,
+            snapshotVersion: snapshot.version,
+            generatedAt: snapshot.generatedAt,
+            packages: snapshot.packages,
+            iconsVersion: icons.version,
+            stats: snapshot.stats
+        });
+    });
+}
+//# sourceMappingURL=tools.guides.js.map

package/lib/tools.icons.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Icon-catalog tools. The catalog is `name` (kebab-case, matches Lucide upstream) <-> `symbol`
+ * (camelCase, the export `provideIcons([...])` actually needs) plus search keywords, with SVG
+ * bodies deliberately stripped from the snapshot (see Fase 3 -- 468 KB -> ~90 KB).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerIconTools(server: McpServer): void;

package/lib/tools.icons.js

@@ -0,0 +1,106 @@
+/**
+ * Icon-catalog tools. The catalog is `name` (kebab-case, matches Lucide upstream) <-> `symbol`
+ * (camelCase, the export `provideIcons([...])` actually needs) plus search keywords, with SVG
+ * bodies deliberately stripped from the snapshot (see Fase 3 -- 468 KB -> ~90 KB).
+ */
+import { z } from 'zod';
+import { jsonResult, loadIcons } from './data.js';
+import { jsonError, levenshtein } from './tools.components.js';
+function resolveIcon(icons, input) {
+    const lower = input.trim().toLowerCase();
+    const byName = icons.find((i) => i.name.toLowerCase() === lower);
+    if (byName)
+        return { icon: byName };
+    const bySymbol = icons.find((i) => i.symbol?.toLowerCase() === lower);
+    if (bySymbol)
+        return { icon: bySymbol };
+    const scored = icons
+        .map((i) => ({
+        i,
+        score: Math.min(levenshtein(lower, i.name.toLowerCase()), levenshtein(lower, (i.symbol ?? '').toLowerCase()))
+    }))
+        .sort((a, b) => a.score - b.score)
+        .slice(0, 5)
+        .map(({ i }) => i.name);
+    return {
+        icon: null,
+        error: `No icon named or symbolized "${input}".`,
+        suggestions: scored
+    };
+}
+export function registerIconTools(server) {
+    server.registerTool('search_icons', {
+        title: 'Search the icon catalog',
+        description: 'Searches the 1790-icon Lucide catalog by name or keyword. Each result carries the camelCase `symbol` needed by `provideIcons([...])` alongside the kebab-case `name`.',
+        inputSchema: {
+            query: z.string(),
+            limit: z.number().int().positive().max(100).optional()
+        }
+    }, async ({ query, limit }) => {
+        const icons = loadIcons();
+        const q = query.trim().toLowerCase();
+        const matches = icons.icons
+            .filter((i) => i.name.includes(q) || i.keywords.some((k) => k.includes(q)))
+            .slice(0, limit ?? 20);
+        return jsonResult({ query, count: matches.length, icons: matches });
+    });
+    server.registerTool('get_icon', {
+        title: 'Get one icon',
+        description: 'Resolves a single icon by its kebab-case name or camelCase symbol and returns both forms plus a ready-to-use `<ns-icon>` snippet.',
+        inputSchema: { icon: z.string() }
+    }, async ({ icon }) => {
+        const icons = loadIcons();
+        const resolution = resolveIcon(icons.icons, icon);
+        if (!resolution.icon)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        const found = resolution.icon;
+        return jsonResult({
+            ...found,
+            usage: {
+                provide: found.symbol ? `provideIcons([${found.symbol}])` : null,
+                template: `<ns-icon name="${found.name}"></ns-icon>`
+            }
+        });
+    });
+    server.registerTool('get_icons_setup', {
+        title: 'Get icon setup boilerplate',
+        description: "Returns the ng-solid icon component's own API plus the `provideIcons`/`provideIconsPatch` boilerplate. Pass `icons` (names or symbols) to get a ready import/provide snippet for exactly those icons instead of the generic template.",
+        inputSchema: {
+            icons: z
+                .array(z.string())
+                .optional()
+                .describe('Icon names or symbols to include in the generated snippet.')
+        }
+    }, async ({ icons: requested }) => {
+        const icons = loadIcons();
+        if (!requested || requested.length === 0) {
+            return jsonResult({
+                component: icons.component,
+                setup: {
+                    importStatement: "import { provideIcons } from '@ng-solid/icons';",
+                    example: 'provideIcons([aArrowDown, calendar]) // pass EnvironmentProviders to `appConfig.providers`',
+                    perRoute: 'providers: [provideIconsPatch([add])] // scoped to a lazily-loaded Route instead of bootstrap'
+                }
+            });
+        }
+        const resolved = requested.map((name) => resolveIcon(icons.icons, name));
+        const missing = resolved.filter((r) => !r.icon);
+        if (missing.length > 0) {
+            return jsonError({
+                error: `Unknown icon(s): ${requested.filter((_, idx) => !resolved[idx].icon).join(', ')}`,
+                suggestions: missing.flatMap((m) => m.suggestions ?? [])
+            });
+        }
+        const symbols = resolved
+            .map((r) => r.icon?.symbol)
+            .filter((s) => Boolean(s));
+        return jsonResult({
+            importStatement: `import { ${symbols.join(', ')} } from '@ng-solid/icons';`,
+            provideStatement: `provideIcons([${symbols.join(', ')}])`
+        });
+    });
+}
+//# sourceMappingURL=tools.icons.js.map

package/lib/tools.js

@@ -0,0 +1,18 @@
+import { registerComponentTools } from './tools.components.js';
+import { registerGuideTools } from './tools.guides.js';
+import { registerIconTools } from './tools.icons.js';
+import { registerTokenTools } from './tools.tokens.js';
+/**
+ * Registers the full ng-solid MCP tool catalog (~32 tools), grouped by concern:
+ *  - discovery, API, forms, services/providers, style validation -> tools.components.ts
+ *  - the Arvisfy token pipeline + theme-preset validation           -> tools.tokens.ts
+ *  - the Lucide icon catalog                                        -> tools.icons.ts
+ *  - guides + server metadata                                       -> tools.guides.ts
+ */
+export function registerTools(server) {
+    registerComponentTools(server);
+    registerTokenTools(server);
+    registerIconTools(server);
+    registerGuideTools(server);
+}
+//# sourceMappingURL=tools.js.map

package/lib/tools.tokens.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Theme/token tools: the Arvisfy 3-tier token pipeline (primitive -> semantic -> component),
+ * drift detection against component SCSS, and a pure-JS `validateNsPreset` port for
+ * `validate_theme_preset`.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTokenTools(server: McpServer): void;

package/lib/tools.tokens.js

@@ -0,0 +1,278 @@
+/**
+ * Theme/token tools: the Arvisfy 3-tier token pipeline (primitive -> semantic -> component),
+ * drift detection against component SCSS, and a pure-JS `validateNsPreset` port for
+ * `validate_theme_preset`.
+ */
+import { z } from 'zod';
+import { jsonResult, loadSnapshot } from './data.js';
+import { importTrio, jsonError, resolveComponent } from './tools.components.js';
+import { validatePreset } from './preset-validator.js';
+function findPrimitive(theme, path) {
+    return theme.tiers.primitive.find((t) => t.path === path);
+}
+function findSemantic(theme, path) {
+    return (theme.tiers.semantic.common.find((t) => t.path === path) ??
+        theme.tiers.semantic.light.find((t) => t.path === path) ??
+        theme.tiers.semantic.dark.find((t) => t.path === path));
+}
+function findComponentToken(theme, cssVariable) {
+    return theme.tiers.component.find((t) => t.cssVariable === cssVariable);
+}
+/** Walks a token reference chain (component -> semantic -> primitive) down to its literal. */
+function buildChain(theme, cssVariable) {
+    const componentToken = theme.tiers.component.find((t) => t.cssVariable === cssVariable);
+    if (componentToken) {
+        const chain = [
+            {
+                tier: 'component',
+                path: componentToken.path,
+                cssVariable: componentToken.cssVariable,
+                reference: componentToken.reference
+            }
+        ];
+        const semanticPath = /^\{semantic\.(.+)\}$/.exec(componentToken.reference)?.[1];
+        const semanticToken = semanticPath
+            ? findSemantic(theme, semanticPath)
+            : undefined;
+        if (semanticToken) {
+            chain.push({
+                tier: 'semantic',
+                path: semanticToken.path,
+                cssVariable: semanticToken.cssVariable,
+                reference: semanticToken.reference
+            });
+            const primitivePath = /^\{primitive\.(.+)\}$/.exec(semanticToken.reference)?.[1];
+            const primitiveToken = primitivePath
+                ? findPrimitive(theme, primitivePath)
+                : undefined;
+            if (primitiveToken) {
+                chain.push({
+                    tier: 'primitive',
+                    path: primitiveToken.path,
+                    cssVariable: primitiveToken.cssVariable,
+                    value: primitiveToken.value
+                });
+            }
+        }
+        chain.push({
+            tier: 'component',
+            path: `${componentToken.path} (resolved)`,
+            cssVariable: componentToken.cssVariable,
+            value: `light: ${componentToken.resolved.light ?? 'undefined'} / dark: ${componentToken.resolved.dark ?? 'undefined'}`
+        });
+        return chain;
+    }
+    const semanticEntry = theme.tiers.semantic.common.find((t) => t.cssVariable === cssVariable) ??
+        theme.tiers.semantic.light.find((t) => t.cssVariable === cssVariable) ??
+        theme.tiers.semantic.dark.find((t) => t.cssVariable === cssVariable);
+    if (semanticEntry) {
+        const chain = [
+            {
+                tier: 'semantic',
+                path: semanticEntry.path,
+                cssVariable: semanticEntry.cssVariable,
+                reference: semanticEntry.reference
+            }
+        ];
+        const primitivePath = /^\{primitive\.(.+)\}$/.exec(semanticEntry.reference)?.[1];
+        const primitiveToken = primitivePath
+            ? findPrimitive(theme, primitivePath)
+            : undefined;
+        if (primitiveToken) {
+            chain.push({
+                tier: 'primitive',
+                path: primitiveToken.path,
+                cssVariable: primitiveToken.cssVariable,
+                value: primitiveToken.value
+            });
+        }
+        return chain;
+    }
+    const primitiveEntry = theme.tiers.primitive.find((t) => t.cssVariable === cssVariable);
+    if (primitiveEntry) {
+        return [
+            {
+                tier: 'primitive',
+                path: primitiveEntry.path,
+                cssVariable: primitiveEntry.cssVariable,
+                value: primitiveEntry.value
+            }
+        ];
+    }
+    return null;
+}
+export function registerTokenTools(server) {
+    server.registerTool('get_component_tokens', {
+        title: "Get a component's style tokens",
+        description: 'Returns every `--ns-component-*` CSS custom property a component reads, resolved to its literal value for both light and dark color schemes -- lets an agent reason about contrast/theming without running Angular.',
+        inputSchema: { component: z.string() }
+    }, async ({ component }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, component);
+        if (!resolution.component)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        const doc = resolution.component;
+        if (!snapshot.theme)
+            return jsonError({ error: 'theme is missing from the snapshot.' });
+        const tokens = doc.tokens.map((cssVariable) => {
+            const entry = findComponentToken(snapshot.theme, cssVariable);
+            return (entry ?? {
+                cssVariable,
+                path: null,
+                reference: null,
+                resolved: { light: null, dark: null }
+            });
+        });
+        return jsonResult({
+            ...importTrio(doc),
+            tokenCount: tokens.length,
+            tokens
+        });
+    });
+    server.registerTool('list_theme_tokens', {
+        title: 'List theme tokens for a tier',
+        description: 'Lists flattened tokens for one tier of the Arvisfy 3-tier preset: `primitive` (raw values), `semantic` (references primitives, optionally filtered by color scheme), or `component` (references semantics, resolved for both schemes -- optionally filtered by group, e.g. "button").',
+        inputSchema: {
+            tier: z.enum(['primitive', 'semantic', 'component']),
+            colorScheme: z
+                .enum(['common', 'light', 'dark'])
+                .optional()
+                .describe('Only applies to tier: "semantic".'),
+            group: z
+                .string()
+                .optional()
+                .describe('Only applies to tier: "component" -- filters to tokens whose path starts with this group, e.g. "button".')
+        }
+    }, async ({ tier, colorScheme, group }) => {
+        const snapshot = loadSnapshot();
+        if (!snapshot.theme)
+            return jsonError({ error: 'theme is missing from the snapshot.' });
+        const theme = snapshot.theme;
+        if (tier === 'primitive') {
+            return jsonResult({
+                tier,
+                count: theme.tiers.primitive.length,
+                tokens: theme.tiers.primitive
+            });
+        }
+        if (tier === 'semantic') {
+            const scope = colorScheme ?? 'common';
+            const tokens = theme.tiers.semantic[scope];
+            return jsonResult({
+                tier,
+                colorScheme: scope,
+                count: tokens.length,
+                tokens
+            });
+        }
+        const tokens = group
+            ? theme.tiers.component.filter((t) => t.path === group || t.path.startsWith(`${group}.`))
+            : theme.tiers.component;
+        return jsonResult({
+            tier,
+            group: group ?? null,
+            count: tokens.length,
+            tokens,
+            componentGroups: theme.componentGroups
+        });
+    });
+    server.registerTool('resolve_token', {
+        title: 'Resolve a token to its literal value',
+        description: 'Walks a `--ns-*` CSS custom property down its full reference chain (component -> semantic -> primitive) to its literal CSS value, at any tier you start from.',
+        inputSchema: {
+            cssVariable: z
+                .string()
+                .describe('e.g. "--ns-component-button-background".')
+        }
+    }, async ({ cssVariable }) => {
+        const snapshot = loadSnapshot();
+        if (!snapshot.theme)
+            return jsonError({ error: 'theme is missing from the snapshot.' });
+        const chain = buildChain(snapshot.theme, cssVariable);
+        if (!chain) {
+            return jsonError({
+                error: `No token found for "${cssVariable}". CSS variables in this preset follow --ns-<tier>-<dot.path> (dots -> dashes).`
+            });
+        }
+        return jsonResult({ cssVariable, chain });
+    });
+    server.registerTool('get_token_scope', {
+        title: "Classify a CSS variable's scope",
+        description: 'Classifies a `--ns-*` CSS custom property by tier (primitive/semantic/component) and, for component tokens, its owning group -- helps decide whether a token is safe to override in a preset.',
+        inputSchema: { cssVariable: z.string() }
+    }, async ({ cssVariable }) => {
+        const snapshot = loadSnapshot();
+        if (!snapshot.theme)
+            return jsonError({ error: 'theme is missing from the snapshot.' });
+        const theme = snapshot.theme;
+        const component = theme.tiers.component.find((t) => t.cssVariable === cssVariable);
+        if (component) {
+            return jsonResult({
+                cssVariable,
+                tier: 'component',
+                group: component.path.split('.')[0],
+                path: component.path
+            });
+        }
+        const semantic = theme.tiers.semantic.common.find((t) => t.cssVariable === cssVariable) ??
+            theme.tiers.semantic.light.find((t) => t.cssVariable === cssVariable) ??
+            theme.tiers.semantic.dark.find((t) => t.cssVariable === cssVariable);
+        if (semantic) {
+            return jsonResult({
+                cssVariable,
+                tier: 'semantic',
+                path: semantic.path
+            });
+        }
+        const primitive = theme.tiers.primitive.find((t) => t.cssVariable === cssVariable);
+        if (primitive) {
+            return jsonResult({
+                cssVariable,
+                tier: 'primitive',
+                path: primitive.path
+            });
+        }
+        return jsonError({
+            error: `"${cssVariable}" is not defined by the Arvisfy preset.`
+        });
+    });
+    server.registerTool('validate_theme_preset', {
+        title: 'Validate a theme preset',
+        description: 'Angular-free port of `validateNsPreset`: validates a preset (or a `defineNsPreset` override tree) against the same rules the design-system enforces at load time -- preset name shape, safe primitive values, primitive/semantic reference resolution, and the "must resolve in both color schemes" rule. `mode: "overrides"` validates a partial override tree (only checks tiers actually present); `mode: "full"` (default) expects the complete 3-tier shape.',
+        inputSchema: {
+            preset: z
+                .string()
+                .describe('JSON-encoded preset object: { name, primitive, semantic: { common, colorScheme: { light, dark } }, components }. For mode "overrides", any subset of these keys.'),
+            mode: z.enum(['full', 'overrides']).optional()
+        }
+    }, async ({ preset, mode }) => {
+        const snapshot = loadSnapshot();
+        if (!snapshot.theme)
+            return jsonError({ error: 'theme is missing from the snapshot.' });
+        let parsed;
+        try {
+            parsed = JSON.parse(preset);
+        }
+        catch (err) {
+            return jsonError({
+                error: `preset is not valid JSON: ${err.message}`
+            });
+        }
+        const result = validatePreset(parsed, snapshot.theme.rules, mode ?? 'full');
+        return jsonResult(result);
+    });
+    server.registerTool('get_token_drift', {
+        title: 'Get token drift',
+        description: 'Cross-references the `--ns-component-*` variables referenced in component SCSS against the ones the Arvisfy preset actually defines. `undefinedInPreset` (SCSS reads a token the preset never sets) is a real bug -- the design-system would render a broken value. `unusedInScss` (the preset defines a token nothing reads) is dead-weight, not necessarily a bug.',
+        inputSchema: {}
+    }, async () => {
+        const snapshot = loadSnapshot();
+        if (!snapshot.theme)
+            return jsonError({ error: 'theme is missing from the snapshot.' });
+        return jsonResult(snapshot.theme.drift);
+    });
+}
+//# sourceMappingURL=tools.tokens.js.map