@webspire/mcp 0.3.0 → 0.6.0

package/dist/index.js

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { registerResources, registerTools } from './handlers.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
 const args = process.argv.slice(2);
 const urlIdx = args.indexOf('--registry-url');
 const fileIdx = args.indexOf('--registry-file');
@@ -11,7 +16,7 @@ const registryOptions = {
 };
 const server = new McpServer({
     name: 'webspire',
-    version: '0.3.0',
+    version: pkg.version,
 });
 registerTools(server, registryOptions);
 registerResources(server, registryOptions);

package/dist/registration.js

@@ -357,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();
@@ -374,7 +374,12 @@ 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 () => {
@@ -399,8 +404,14 @@ export function registerToolsWithProvider(server, getRegistry) {
     });
     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'),
+        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 ?? [];
@@ -411,7 +422,15 @@ export function registerToolsWithProvider(server, getRegistry) {
         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]
+            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);
@@ -455,6 +474,200 @@ export function registerToolsWithProvider(server, getRegistry) {
             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'),
+                },
+            ],
+        };
+    });
 }
 export function registerResourcesWithProvider(server, getRegistry) {
     server.resource('categories', 'webspire://categories', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webspire/mcp",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "MCP server for Webspire — AI-native discovery of CSS snippets, UI patterns, and page templates",
   "type": "module",
   "exports": {
@@ -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.`,
-                },
-            ],
-        };
-    });
-}