@webspire/mcp 0.2.0 → 0.5.0

package/dist/index.js

@@ -11,7 +11,7 @@ const registryOptions = {
 };
 const server = new McpServer({
     name: 'webspire',
-    version: '0.2.0',
+    version: '0.5.0',
 });
 registerTools(server, registryOptions);
 registerResources(server, registryOptions);

package/dist/registration.js

@@ -58,6 +58,39 @@ function formatSnippetFull(s) {
         .filter((line) => line !== '')
         .join('\n');
 }
+function formatTemplateBrief(t) {
+    return [
+        `**${t.title}** (${t.id})`,
+        `  ${t.summary}`,
+        `  Category: ${t.category} | Style: ${t.style}`,
+        t.tags.length > 0 ? `  Tags: ${t.tags.join(', ')}` : '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+function formatTemplateFull(t) {
+    return [
+        `# ${t.title}`,
+        '',
+        t.description ?? t.summary,
+        '',
+        '## Identity',
+        `ID: ${t.id}`,
+        `Category: ${t.category}`,
+        `Style: ${t.style}`,
+        '',
+        t.tags.length > 0 ? `## Tags\n${t.tags.join(', ')}` : '',
+        t.sections.length > 0 ? `## Sections\n${t.sections.join(', ')}` : '',
+        t.patterns.length > 0 ? `## Uses Patterns\n${t.patterns.join(', ')}` : '',
+        '',
+        '## HTML',
+        '```html',
+        t.html,
+        '```',
+    ]
+        .filter((line) => line !== '')
+        .join('\n');
+}
 function formatPatternBrief(p) {
     return [
         `**${p.title}** (${p.id})`,
@@ -324,7 +357,7 @@ export function registerToolsWithProvider(server, getRegistry) {
             ],
         };
     });
-    server.tool('get_pattern', 'Get full pattern data including HTML (and optional CSS/JS) for a specific pattern.', {
+    server.tool('get_pattern', 'Get full pattern data including HTML (and optional CSS/JS) for a specific pattern. Patterns use --ws-* design tokens via component classes — import webspire-tokens.css + webspire-components.css to enable.', {
         id: z.string().describe('Pattern ID, e.g. "hero/base", "hero/with-image"'),
     }, async ({ id }) => {
         const registry = await getRegistry();
@@ -341,7 +374,229 @@ export function registerToolsWithProvider(server, getRegistry) {
             };
         }
         return {
-            content: [{ type: 'text', text: formatPatternFull(pattern) }],
+            content: [
+                {
+                    type: 'text',
+                    text: `${formatPatternFull(pattern)}\n\n---\n**Setup:** Import \`webspire-tokens.css\` and \`webspire-components.css\` to enable token support.\nOverride \`--ws-color-primary\` etc. to match your brand. Docs: https://webspire.de/tokens`,
+                },
+            ],
+        };
+    });
+    server.tool('list_templates', 'List all available page templates grouped by category', {}, async () => {
+        const registry = await getRegistry();
+        const templates = registry.templates ?? [];
+        const counts = {};
+        for (const t of templates) {
+            counts[t.category] = (counts[t.category] ?? 0) + 1;
+        }
+        const result = Object.entries(counts)
+            .sort(([, a], [, b]) => b - a)
+            .map(([cat, count]) => `${cat}: ${count} template${count > 1 ? 's' : ''}`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${templates.length} templates across ${Object.keys(counts).length} categories:\n\n${result}`,
+                },
+            ],
+        };
+    });
+    server.tool('search_templates', 'Search Webspire page templates by keyword, category, or style.', {
+        query: z.string().describe('Search query, e.g. "saas landing", "portfolio dark", "shop"'),
+        category: z.string().optional().describe('Filter by category, e.g. saas-landing, agency, shop'),
+        style: z.string().optional().describe('Filter by style, e.g. modern, bold, minimal, corporate'),
+    }, async ({ query, category, style }) => {
+        const registry = await getRegistry();
+        let templates = registry.templates ?? [];
+        if (category)
+            templates = templates.filter((t) => t.category === category);
+        if (style)
+            templates = templates.filter((t) => t.style === style);
+        const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+        const results = templates
+            .map((t) => {
+            const haystack = [t.title, t.summary, t.description ?? '', t.category, t.style, ...t.tags, ...t.sections]
+                .join(' ')
+                .toLowerCase();
+            const score = terms.reduce((acc, term) => acc + (haystack.includes(term) ? 1 : 0), 0);
+            return { template: t, score };
+        })
+            .filter((row) => row.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 10)
+            .map((row) => row.template);
+        if (results.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No templates found matching your query.' }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${results.length} template${results.length > 1 ? 's' : ''}:\n\n${results.map(formatTemplateBrief).join('\n\n')}`,
+                },
+            ],
+        };
+    });
+    server.tool('get_template', 'Get full template HTML for a specific page template. Returns standalone HTML ready to use.', {
+        id: z.string().describe('Template ID, e.g. "saas-landing/modern", "shop/catalog"'),
+    }, async ({ id }) => {
+        const registry = await getRegistry();
+        const template = (registry.templates ?? []).find((t) => t.id === id);
+        if (!template) {
+            const available = (registry.templates ?? []).map((t) => t.id).join(', ');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Template "${id}" not found. Available templates: ${available}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: formatTemplateFull(template) }],
+        };
+    });
+    server.tool('recommend_token_mapping', 'Analyze project design tokens and recommend how to map them to Webspire --ws-* tokens. Provide your existing CSS custom properties or Tailwind theme colors.', {
+        project_tokens: z
+            .string()
+            .describe('Your project\'s design tokens or CSS custom properties, e.g. "--color-brand-500: #2563eb; --color-bg: #fafafa" or "primary: blue-600, background: white"'),
+        framework: z
+            .enum(['tailwind', 'custom', 'bootstrap', 'chakra', 'shadcn'])
+            .optional()
+            .describe('CSS framework used in your project'),
+    }, async ({ project_tokens, framework }) => {
+        const lines = project_tokens.split(/[;\n,]+/).map((s) => s.trim()).filter(Boolean);
+        const mappings = [];
+        const TOKEN_HINTS = [
+            { patterns: [/brand|primary|main|accent-color/i], wsToken: '--ws-color-primary', description: 'Primary/brand color' },
+            { patterns: [/brand.*hover|primary.*hover|primary.*dark/i], wsToken: '--ws-color-primary-hover', description: 'Primary hover state' },
+            { patterns: [/brand.*light|primary.*light|primary.*50|brand.*50/i], wsToken: '--ws-color-primary-soft', description: 'Primary soft background' },
+            { patterns: [/secondary|accent(?!-color)/i], wsToken: '--ws-color-accent', description: 'Secondary/accent color' },
+            { patterns: [/^bg$|background(?!.*secondary)|surface(?!.*alt)/i], wsToken: '--ws-color-surface', description: 'Page background' },
+            { patterns: [/bg.*secondary|bg.*subtle|bg.*muted|surface.*alt|bg.*light/i], wsToken: '--ws-color-surface-alt', description: 'Subtle background' },
+            { patterns: [/^text$|text.*primary|foreground(?!.*muted)/i], wsToken: '--ws-color-text', description: 'Primary text color' },
+            { patterns: [/text.*secondary|text.*soft|text.*muted|muted.*foreground/i], wsToken: '--ws-color-text-muted', description: 'Muted text color' },
+            { patterns: [/border(?!.*strong)|divider/i], wsToken: '--ws-color-border', description: 'Default border' },
+            { patterns: [/success|green|positive/i], wsToken: '--ws-color-success', description: 'Success color' },
+            { patterns: [/warning|amber|yellow|caution/i], wsToken: '--ws-color-warning', description: 'Warning color' },
+            { patterns: [/danger|error|red|destructive/i], wsToken: '--ws-color-danger', description: 'Danger/error color' },
+            { patterns: [/radius|rounded|corner/i], wsToken: '--ws-radius-md', description: 'Border radius' },
+        ];
+        for (const line of lines) {
+            const [rawName] = line.split(':').map((s) => s.trim());
+            const name = rawName.replace(/^--color-|^--/, '');
+            for (const hint of TOKEN_HINTS) {
+                if (hint.patterns.some((p) => p.test(name))) {
+                    const varRef = rawName.startsWith('--') ? `var(${rawName})` : rawName;
+                    mappings.push(`  ${hint.wsToken}: ${varRef};  /* ${hint.description} ← ${rawName} */`);
+                    break;
+                }
+            }
+        }
+        const frameworkNote = framework
+            ? `\nFramework detected: ${framework}. ${framework === 'tailwind'
+                ? 'Use @theme to register --ws-* tokens, or override in your main CSS.'
+                : framework === 'shadcn'
+                    ? 'Map shadcn/ui --* variables to --ws-* in your globals.css.'
+                    : 'Override --ws-* tokens in your global stylesheet.'}\n`
+            : '';
+        const css = mappings.length > 0
+            ? `:root {\n${mappings.join('\n')}\n}`
+            : '/* No matching tokens detected. Provide CSS custom properties like:\n   --color-brand: #2563eb; --color-bg: #ffffff */';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `# Recommended Token Mapping\n${frameworkNote}\n\`\`\`css\n${css}\n\`\`\`\n\nPaste this into your project's CSS, then import webspire-tokens.css.\nAdjust values as needed — these are suggestions based on naming conventions.\n\nFull token reference: https://webspire.de/tokens`,
+                },
+            ],
+        };
+    });
+    server.tool('setup_tokens', 'Get the WebSpire token CSS files to write into your project. Returns the content of webspire-tokens.css (alias tokens + dark mode) and webspire-components.css (per-component tokens). Write these files to your project and import them in your main CSS.', {
+        components: z
+            .array(z.string())
+            .optional()
+            .describe('Only include component tokens for these families (e.g. ["hero", "cta", "pricing"]). If omitted, all component tokens are included.'),
+    }, async ({ components }) => {
+        const registry = await getRegistry();
+        // Read bundled CSS files
+        const { readFile } = await import('node:fs/promises');
+        const { dirname, resolve } = await import('node:path');
+        const { fileURLToPath } = await import('node:url');
+        const thisDir = dirname(fileURLToPath(import.meta.url));
+        let tokensCss;
+        let componentsCss;
+        try {
+            tokensCss = await readFile(resolve(thisDir, '..', 'css', 'webspire-tokens.css'), 'utf-8');
+            componentsCss = await readFile(resolve(thisDir, '..', 'css', 'webspire-components.css'), 'utf-8');
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Token CSS files not found in package. Update @webspire/mcp to the latest version.',
+                    },
+                ],
+            };
+        }
+        // Filter component tokens if specific families requested
+        if (components && components.length > 0) {
+            const filtered = ['/* Webspire Component Tokens (filtered) */'];
+            const sections = componentsCss.split(/(?=^\.ws-)/m);
+            for (const section of sections) {
+                const classMatch = section.match(/^\.ws-([a-z0-9-]+)/);
+                if (classMatch && components.includes(classMatch[1])) {
+                    filtered.push(section.trim());
+                }
+            }
+            componentsCss = filtered.join('\n\n');
+        }
+        const families = components ? components.join(', ') : 'all';
+        const patternCount = registry.patterns?.length ?? 0;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: [
+                        `# WebSpire Token Setup (${families} families, ${patternCount} patterns)`,
+                        '',
+                        '## 1. Write `webspire-tokens.css` to your project',
+                        '',
+                        '```css',
+                        tokensCss,
+                        '```',
+                        '',
+                        '## 2. Write `webspire-components.css` to your project',
+                        '',
+                        '```css',
+                        componentsCss,
+                        '```',
+                        '',
+                        '## 3. Import in your main CSS',
+                        '',
+                        '```css',
+                        '@import "./webspire-tokens.css";',
+                        '@import "./webspire-components.css";',
+                        '```',
+                        '',
+                        '## 4. Override to match your brand',
+                        '',
+                        '```css',
+                        ':root {',
+                        '  --ws-color-primary: #your-brand-color;',
+                        '  --ws-color-primary-hover: #your-brand-darker;',
+                        '}',
+                        '```',
+                        '',
+                        'Docs: https://webspire.de/tokens',
+                    ].join('\n'),
+                },
+            ],
         };
     });
 }
@@ -468,4 +723,52 @@ export function registerResourcesWithProvider(server, getRegistry) {
             ],
         };
     });
+    server.resource('templates', 'webspire://templates', { description: 'List all page templates', mimeType: 'application/json' }, async () => {
+        const registry = await getRegistry();
+        const templates = (registry.templates ?? []).map((t) => ({
+            id: t.id,
+            title: t.title,
+            summary: t.summary,
+            category: t.category,
+            style: t.style,
+        }));
+        return {
+            contents: [
+                {
+                    uri: 'webspire://templates',
+                    mimeType: 'application/json',
+                    text: JSON.stringify(templates, null, 2),
+                },
+            ],
+        };
+    });
+    server.resource('template', 'webspire://template/{id}', {
+        description: 'Get full template data including HTML source',
+        mimeType: 'application/json',
+    }, async (uri) => {
+        const parts = uri.pathname.replace('//', '').split('/');
+        const id = parts.slice(1).join('/');
+        const registry = await getRegistry();
+        const template = (registry.templates ?? []).find((t) => t.id === id);
+        if (!template) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: 'text/plain',
+                        text: `Template "${id}" not found`,
+                    },
+                ],
+            };
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(template, null, 2),
+                },
+            ],
+        };
+    });
 }

package/dist/types.d.ts

@@ -106,9 +106,44 @@ export interface PatternEntry {
     css: string | null;
     js: string | null;
 }
+export interface TemplateEntry {
+    id: string;
+    title: string;
+    summary: string;
+    description?: string;
+    category: string;
+    style: string;
+    tags: string[];
+    patterns: string[];
+    sections: string[];
+    features: {
+        responsive: boolean;
+        darkMode: boolean;
+        animations: boolean;
+        formHandling: boolean;
+    };
+    files: {
+        html: string;
+        preview: string;
+    };
+    install: {
+        copyPasteReady: boolean;
+        tailwindCdn: boolean;
+        vanillaJs: boolean;
+        notes: string[];
+    };
+    governance: {
+        status: 'draft' | 'review' | 'published' | 'deprecated';
+        quality: 'experimental' | 'stable' | 'flagship';
+        owner: string;
+        updatedAt: string;
+    };
+    html: string;
+}
 export interface Registry {
     version: string;
     generated: string;
     snippets: SnippetEntry[];
     patterns?: PatternEntry[];
+    templates?: TemplateEntry[];
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@webspire/mcp",
-  "version": "0.2.0",
-  "description": "MCP server for Webspire CSS snippets — AI-native snippet discovery and matching",
+  "version": "0.5.0",
+  "description": "MCP server for Webspire — AI-native discovery of CSS snippets, UI patterns, and page templates",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
@@ -20,7 +20,8 @@
   },
   "files": [
     "dist",
-    "data"
+    "data",
+    "css"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.0",

package/dist/tools.d.ts

@@ -1,3 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type RegistryOptions } from './registry.js';
-export declare function registerTools(server: McpServer, registryOptions?: RegistryOptions): void;

package/dist/tools.js

@@ -1,151 +0,0 @@
-import { z } from 'zod';
-import { loadRegistry, searchSnippets, suggestSnippets, } from './registry.js';
-function formatSnippetBrief(s) {
-    return [
-        `**${s.title}** (${s.id})`,
-        `  ${s.description}`,
-        `  Category: ${s.category} | Tags: ${s.tags.join(', ')}`,
-        s.meta.useCases.length > 0
-            ? `  Use cases: ${s.meta.useCases.slice(0, 2).join('; ')}`
-            : '',
-    ]
-        .filter(Boolean)
-        .join('\n');
-}
-function formatSnippetFull(s) {
-    const props = s.meta.customProperties
-        .map((p) => `  ${p}: ${s.meta.defaultValues[p] ?? 'unset'}`)
-        .join('\n');
-    return [
-        `# ${s.title}`,
-        '',
-        s.description,
-        '',
-        '## Usage',
-        '```html',
-        s.meta.usageExample,
-        '```',
-        '',
-        '## CSS',
-        '```css',
-        s.css,
-        '```',
-        '',
-        s.meta.customProperties.length > 0 ? `## Custom Properties\n${props}` : '',
-        s.meta.classes.length > 0
-            ? `## Classes\n${s.meta.classes.join(', ')}`
-            : '',
-        s.meta.accessibility.length > 0
-            ? `## Accessibility\nRespects: ${s.meta.accessibility.join(', ')}`
-            : '',
-        '',
-        `Browser support: ${s.meta.browser}`,
-        `Size: ${s.meta.lines} lines, ${s.meta.bytes} bytes`,
-    ]
-        .filter((line) => line !== '')
-        .join('\n');
-}
-export function registerTools(server, registryOptions) {
-    server.tool('list_categories', 'List all available snippet categories with snippet counts', {}, async () => {
-        const registry = await loadRegistry(registryOptions);
-        const counts = {};
-        for (const snippet of registry.snippets) {
-            counts[snippet.category] = (counts[snippet.category] ?? 0) + 1;
-        }
-        const result = Object.entries(counts)
-            .sort(([, a], [, b]) => b - a)
-            .map(([cat, count]) => `${cat}: ${count} snippet${count > 1 ? 's' : ''}`)
-            .join('\n');
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `${registry.snippets.length} snippets across ${Object.keys(counts).length} categories:\n\n${result}`,
-                },
-            ],
-        };
-    });
-    server.tool('search_snippets', 'Search Webspire CSS snippets by keyword, problem description, or use case. Returns matching snippets with their descriptions and IDs.', {
-        query: z
-            .string()
-            .describe('Search query: problem description, use case, or CSS technique (e.g. "glass card", "fade animation", "blur entrance")'),
-        category: z
-            .string()
-            .optional()
-            .describe('Filter by category: glass, animations, easing, scroll, decorative, interactions, text'),
-        tags: z.array(z.string()).optional().describe('Filter by tags'),
-    }, async ({ query, category, tags }) => {
-        const registry = await loadRegistry(registryOptions);
-        const results = searchSnippets(registry, query, category, tags);
-        if (results.length === 0) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: 'No snippets found matching your query. Try broader keywords or check available categories with list_categories.',
-                    },
-                ],
-            };
-        }
-        const text = results.map(formatSnippetBrief).join('\n\n');
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Found ${results.length} snippet${results.length > 1 ? 's' : ''}:\n\n${text}`,
-                },
-            ],
-        };
-    });
-    server.tool('get_snippet', 'Get full CSS source, metadata, usage example, and custom properties for a specific snippet. Use this after finding a snippet via search_snippets or suggest_snippet.', {
-        id: z
-            .string()
-            .describe('Snippet ID, e.g. "glass/frosted", "animations/fade-in", "easing/tokens"'),
-    }, async ({ id }) => {
-        const registry = await loadRegistry(registryOptions);
-        const snippet = registry.snippets.find((s) => s.id === id);
-        if (!snippet) {
-            const available = registry.snippets.map((s) => s.id).join(', ');
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Snippet "${id}" not found. Available snippets: ${available}`,
-                    },
-                ],
-            };
-        }
-        return {
-            content: [{ type: 'text', text: formatSnippetFull(snippet) }],
-        };
-    });
-    server.tool('suggest_snippet', 'Describe a UI problem or desired effect in plain language and get the best matching Webspire snippets. The AI matches your description against each snippet\'s use cases and problem statements.', {
-        problem: z
-            .string()
-            .describe('Describe the UI problem or effect you need (e.g. "I need a blurred card overlay on my hero section", "my list items should animate in one by one")'),
-    }, async ({ problem }) => {
-        const registry = await loadRegistry(registryOptions);
-        const results = suggestSnippets(registry, problem);
-        if (results.length === 0) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: 'No matching snippet found for your description. Try rephrasing or use search_snippets with specific keywords.',
-                    },
-                ],
-            };
-        }
-        const text = results
-            .map((s, i) => `${i + 1}. ${formatSnippetBrief(s)}\n   Usage: \`${s.meta.usageExample}\``)
-            .join('\n\n');
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Top ${results.length} suggestion${results.length > 1 ? 's' : ''} for "${problem}":\n\n${text}\n\nUse get_snippet(id) for full CSS and details.`,
-                },
-            ],
-        };
-    });
-}