@webspire/mcp 0.5.0 → 0.6.0

package/README.md

@@ -1,15 +1,13 @@
 # @webspire/mcp
 
-MCP server for [Webspire](https://webspire.de) — AI-native discovery of CSS snippets, UI patterns, and page templates.
+MCP server for [Webspire](https://webspire.de) — AI-native discovery of CSS snippets, UI patterns, and page templates with a 3-layer design token system.
 
-**49 CSS snippets** + **212 UI patterns** + **18 page templates** — all Tailwind v4, dark mode, accessible.
+**49 CSS snippets** + **212 UI patterns** + **18 page templates** — all Tailwind v4, token-based, dark mode, accessible.
 
 ## Quick Start
 
 ### Claude Code / Claude Desktop
 
-Add to your MCP settings (`~/.claude/settings.json` or Claude Desktop config):
-
 ```json
 {
   "mcpServers": {
@@ -21,71 +19,88 @@ Add to your MCP settings (`~/.claude/settings.json` or Claude Desktop config):
 }
 ```
 
-### Custom Registry
-
-```json
-{
-  "mcpServers": {
-    "webspire": {
-      "command": "npx",
-      "args": ["-y", "@webspire/mcp", "--registry-url", "https://your-domain.com/registry.json"]
-    }
-  }
-}
-```
-
-## Available Tools
+## Available Tools (12)
 
 | Tool | Description |
 |------|-------------|
 | `list_categories` | List all snippet categories with counts |
 | `search_snippets` | Search snippets by keyword, use case, or CSS technique |
 | `get_snippet` | Get full CSS source, metadata, and usage example |
-| `recommend_snippet` | Describe a UI problem, get best matching snippets with reasoning |
+| `recommend_snippet` | Describe a UI problem, get best matching snippets |
 | `list_pattern_families` | List all 55 pattern families with counts |
 | `search_patterns` | Search 212 UI patterns by intent, family, or tier |
-| `get_pattern` | Get full pattern HTML/CSS/JS with slots, props, and metadata |
+| `get_pattern` | Get full pattern HTML with component token references |
+| `list_templates` | List all page templates by category |
+| `search_templates` | Search templates by keyword, category, or style |
+| `get_template` | Get full standalone HTML for a page template |
+| `setup_tokens` | Get token CSS files to write into your project (no CDN needed) |
+| `recommend_token_mapping` | Analyze your project tokens and suggest --ws-* mapping |
+
+## 3-Layer Token Architecture
+
+Patterns use semantic CSS custom properties via a 3-layer system:
+
+```
+Host Tokens (your project) → WebSpire Alias Tokens → Component Tokens → Markup
+```
+
+### Setup via MCP
+
+```
+> setup_tokens()
+// Returns webspire-tokens.css + webspire-components.css
+// AI agent writes them into your project
+
+> setup_tokens({ components: ["hero", "cta", "pricing"] })
+// Only includes tokens for the families you use
+```
+
+### Pattern Markup
+
+```html
+<section class="ws-cta bg-[var(--ws-cta-bg)] py-20">
+  <h2 class="text-[var(--ws-cta-text)] text-3xl font-bold">Title</h2>
+  <a class="bg-[var(--ws-cta-action-bg)] text-[var(--ws-cta-action-text)]
+     hover:bg-[var(--ws-cta-action-bg-hover)] rounded-lg px-5 py-3">
+    Get started
+  </a>
+</section>
+```
+
+### Customize
+
+```css
+:root {
+  --ws-color-primary: #your-brand-color;
+  --ws-color-primary-hover: #your-brand-darker;
+}
+```
 
 ## Available Resources
 
 | URI | Description |
 |-----|-------------|
-| `webspire://categories` | All snippet categories with counts (JSON) |
-| `webspire://category/{name}` | Snippets in a category (JSON) |
-| `webspire://snippet/{id}` | Full snippet data including CSS (JSON) |
-| `webspire://patterns` | All 212 patterns with brief metadata (JSON) |
-| `webspire://pattern/{id}` | Full pattern data including HTML source (JSON) |
+| `webspire://categories` | Snippet categories with counts |
+| `webspire://category/{name}` | Snippets in a category |
+| `webspire://snippet/{id}` | Full snippet data including CSS |
+| `webspire://patterns` | All patterns with brief metadata |
+| `webspire://pattern/{id}` | Full pattern data including HTML |
+| `webspire://templates` | All templates with brief metadata |
+| `webspire://template/{id}` | Full template data including HTML |
 
 ## Content
 
 ### CSS Snippets (49)
 
-Effects that Tailwind v4 can't do natively:
-
-- **glass** (5) — Frosted, subtle, bold, colored, dark glassmorphism
-- **animations** (7) — Fade, slide, scale, blur, stagger, pulse, infinite scroll
-- **easing** (1) — Spring, bounce, snap easing tokens
-- **scroll** (8) — Parallax, reveal, progress bar, snap, sticky header
-- **decorative** (11) — Aurora, gradient mesh, neon glow, noise, orbs, shimmer
-- **interactions** (11) — Hover lift, ripple, flip card, tilt, magnetic, focus ring
-- **text** (6) — Fluid size, gradient text, typewriter, truncate, balance
+Effects that Tailwind v4 can't do natively: glass, animations, easing, scroll, decorative, interactions, text.
 
 ### UI Patterns (212)
 
-Full Tailwind HTML sections across 55 families:
-
-accordion, auth, avatar, badge, banner, bento, blog, breadcrumb, callout, cards, checkout, code-preview, comments, comparison, contact, cookie-consent, cta, dashboard, description-list, divider, empty-state, error, faq, features, file-tree, footer, forms, gallery, hero, kbd, link-card, logo-cloud, modal, navbar, newsletter, onboarding, pagination, popup, pricing, product-card, property-table, quote, related-articles, see-also, sidebar, social-proof, stats, steps, tabs, team, testimonials, and more.
+55 families across Page Sections and Content Elements — all using `--ws-*` component tokens.
 
 ### Page Templates (18)
 
-Complete page layouts: company, portfolio, saas-landing, shop — ready to scaffold.
-
-## Search Features
-
-- **Synonym expansion**: "blur" also matches glass/frosted snippets
-- **Stemming**: "animations" matches "animated", "animate"
-- **Multi-field scoring**: Weighted matches across title, description, use cases, tags, classes, IDs
-- **Filters**: Category, tags, dark mode support, responsive support, reduced motion
+Complete standalone pages: SaaS, agency, portfolio, shop, company — with Tailwind CDN.
 
 ## Programmatic Usage
 
@@ -95,12 +110,8 @@ import { loadRegistry, searchSnippets } from '@webspire/mcp/registry';
 const registry = await loadRegistry();
 const results = searchSnippets(registry, {
   query: 'glass card hover',
-  category: 'glass',
   darkMode: true,
-  limit: 5,
 });
 ```
 
-## License
-
-MIT
+Docs: https://webspire.de/tokens

package/data/registry.json

@@ -1,6 +1,6 @@
 {
   "version": "1.2.0",
-  "generated": "2026-03-21T12:51:58.469Z",
+  "generated": "2026-03-21T13:07:14.156Z",
   "snippets": [
     {
       "id": "animations/blur-in",

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.5.0',
+    version: pkg.version,
 });
 registerTools(server, registryOptions);
 registerResources(server, registryOptions);

package/dist/registration.js

@@ -404,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 ?? [];
@@ -416,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);
@@ -469,22 +483,77 @@ export function registerToolsWithProvider(server, getRegistry) {
             .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 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' },
+            {
+                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());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webspire/mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server for Webspire — AI-native discovery of CSS snippets, UI patterns, and page templates",
   "type": "module",
   "exports": {