@webspire/mcp 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,92 @@
+# @webspire/mcp
+
+MCP server for [Webspire](https://webspire.de) CSS snippets — AI-native snippet discovery and matching.
+
+49 production-ready CSS snippets across 7 categories: glass, animations, easing, scroll, decorative, interactions, text.
+
+## Quick Start
+
+### Claude Code / Claude Desktop
+
+Add to your MCP settings (`~/.claude/settings.json` or Claude Desktop config):
+
+```json
+{
+  "mcpServers": {
+    "webspire": {
+      "command": "npx",
+      "args": ["-y", "@webspire/mcp"]
+    }
+  }
+}
+```
+
+### Custom Registry
+
+```json
+{
+  "mcpServers": {
+    "webspire": {
+      "command": "npx",
+      "args": ["-y", "@webspire/mcp", "--registry-url", "https://your-domain.com/registry.json"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_categories` | List all snippet categories with counts |
+| `search_snippets` | Search 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 |
+| `list_pattern_families` | List all UI pattern families |
+| `search_patterns` | Search UI patterns by intent |
+| `get_pattern` | Get full pattern HTML/CSS/JS |
+
+## Available Resources
+
+| URI | Description |
+|-----|-------------|
+| `webspire://categories` | All categories with counts (JSON) |
+| `webspire://category/{name}` | Snippets in a category (JSON) |
+| `webspire://snippet/{id}` | Full snippet data including CSS (JSON) |
+| `webspire://patterns` | All patterns (JSON) |
+| `webspire://pattern/{id}` | Full pattern data (JSON) |
+
+## Snippet Categories
+
+- **glass** — Frosted, subtle, bold, colored, dark glassmorphism effects
+- **animations** — Fade, slide, scale, blur, stagger, pulse, infinite scroll
+- **easing** — Spring, bounce, snap easing tokens
+- **scroll** — Parallax, reveal, progress bar, snap, sticky header
+- **decorative** — Aurora, gradient mesh, neon glow, noise, orbs, shimmer
+- **interactions** — Hover lift, ripple, flip card, tilt, magnetic, focus ring
+- **text** — Fluid size, gradient text, typewriter, truncate, balance
+
+## Search Features
+
+- **Synonym expansion**: "blur" also finds glass/frosted snippets
+- **Stemming**: "animations" matches "animated", "animate"
+- **Multi-field scoring**: Matches in title, description, use cases, tags, classes
+- **Filters**: Category, tags, dark mode support, responsive support
+
+## Programmatic Usage
+
+```typescript
+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

package/dist/index.js

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

package/dist/search.d.ts

@@ -8,5 +8,5 @@ export interface SnippetSearchOptions {
     limit?: number;
 }
 export declare function stem(word: string): string;
-export declare function scoreSnippet(snippet: SnippetEntry, stems: string[]): number;
+export declare function scoreSnippet(snippet: SnippetEntry, queryStems: string[], expandedTerms: string[]): number;
 export declare function searchSnippets(snippets: SnippetEntry[], options: SnippetSearchOptions): SnippetEntry[];

package/dist/search.js

@@ -1,17 +1,41 @@
 const STEM_SUFFIXES = [
-    'ions',
-    'ing',
     'tion',
-    'ness',
+    'sion',
+    'ions',
     'ment',
+    'ness',
     'able',
     'ible',
     'ous',
     'ive',
+    'ing',
     'ed',
     'es',
+    'ly',
     's',
 ];
+/** Common synonyms for CSS/UI terms — maps alternative words to canonical terms */
+const SYNONYMS = {
+    blur: ['glass', 'frosted', 'glassmorphism', 'backdrop'],
+    glass: ['blur', 'frosted', 'glassmorphism', 'transparent'],
+    fade: ['opacity', 'appear', 'entrance', 'reveal'],
+    slide: ['translate', 'move', 'enter', 'entrance'],
+    hover: ['mouse', 'interaction', 'lift', 'pointer'],
+    card: ['panel', 'surface', 'container', 'box'],
+    animation: ['animate', 'motion', 'transition', 'keyframe'],
+    glow: ['neon', 'light', 'shine', 'luminous'],
+    scroll: ['viewport', 'intersection', 'parallax', 'progress'],
+    text: ['font', 'typography', 'heading', 'title'],
+    gradient: ['color', 'blend', 'mesh', 'aurora'],
+    dark: ['darkmode', 'theme', 'scheme', 'night'],
+    button: ['btn', 'cta', 'action', 'click'],
+    responsive: ['mobile', 'fluid', 'adaptive', 'clamp'],
+    focus: ['keyboard', 'a11y', 'accessibility', 'ring'],
+    stagger: ['cascade', 'sequence', 'delay', 'children'],
+    reveal: ['show', 'appear', 'unhide', 'visible', 'fade'],
+    shimmer: ['skeleton', 'loading', 'placeholder', 'pulse'],
+    ripple: ['click', 'material', 'touch', 'feedback'],
+};
 export function stem(word) {
     for (const suffix of STEM_SUFFIXES) {
         if (word.length > suffix.length + 2 && word.endsWith(suffix)) {
@@ -20,29 +44,70 @@ export function stem(word) {
     }
     return word;
 }
-export function scoreSnippet(snippet, stems) {
+/** Expand query terms with synonyms for broader matching */
+function expandWithSynonyms(terms) {
+    const expanded = new Set(terms);
+    for (const term of terms) {
+        // Direct synonym lookup
+        if (SYNONYMS[term]) {
+            for (const syn of SYNONYMS[term]) {
+                expanded.add(syn);
+            }
+        }
+        // Reverse lookup: if term appears as a synonym value
+        for (const [key, values] of Object.entries(SYNONYMS)) {
+            if (values.includes(term)) {
+                expanded.add(key);
+            }
+        }
+    }
+    return [...expanded];
+}
+export function scoreSnippet(snippet, queryStems, expandedTerms) {
     let score = 0;
+    // Exact ID match — highest priority
+    const idLower = snippet.id.toLowerCase();
+    for (const term of queryStems) {
+        if (idLower.includes(term))
+            score += 5;
+    }
+    // solves field — primary intent match
     for (const solve of snippet.meta.solves) {
         const lower = solve.toLowerCase();
-        score += stems.filter((w) => lower.includes(w)).length * 3;
+        score += queryStems.filter((w) => lower.includes(w)).length * 4;
     }
+    // useCases — strong signal
     for (const useCase of snippet.meta.useCases) {
         const lower = useCase.toLowerCase();
-        score += stems.filter((w) => lower.includes(w)).length * 2;
+        score += queryStems.filter((w) => lower.includes(w)).length * 3;
     }
-    const desc = snippet.description.toLowerCase();
-    score += stems.filter((w) => desc.includes(w)).length;
+    // Title — important
     const title = snippet.title.toLowerCase();
-    score += stems.filter((w) => title.includes(w)).length * 2;
-    score += stems.filter((w) => snippet.tags.some((t) => t.includes(w))).length;
+    score += queryStems.filter((w) => title.includes(w)).length * 3;
+    // Description
+    const desc = snippet.description.toLowerCase();
+    score += queryStems.filter((w) => desc.includes(w)).length * 2;
+    // Tags
+    const tagStr = snippet.tags.join(' ').toLowerCase();
+    score += queryStems.filter((w) => tagStr.includes(w)).length * 2;
+    // Classes
     const classes = snippet.meta.classes.join(' ').toLowerCase();
-    score += stems.filter((w) => classes.includes(w)).length;
+    score += queryStems.filter((w) => classes.includes(w)).length;
+    // Synonym-expanded terms — lower weight to avoid noise
+    const synonymOnly = expandedTerms.filter((t) => !queryStems.includes(t));
+    if (synonymOnly.length > 0) {
+        const allText = [title, desc, tagStr, ...snippet.meta.useCases, ...snippet.meta.solves]
+            .join(' ')
+            .toLowerCase();
+        score += synonymOnly.filter((w) => allText.includes(w)).length;
+    }
     return score;
 }
 export function searchSnippets(snippets, options) {
     const { query, category, tags, darkMode, responsive, limit = 10 } = options;
     const words = query.toLowerCase().split(/\s+/).filter(Boolean);
     const stems = words.map(stem);
+    const expanded = expandWithSynonyms(words);
     if (stems.length === 0) {
         return [];
     }
@@ -58,7 +123,7 @@ export function searchSnippets(snippets, options) {
             return false;
         return true;
     })
-        .map((snippet) => ({ snippet, score: scoreSnippet(snippet, stems) }))
+        .map((snippet) => ({ snippet, score: scoreSnippet(snippet, stems, expanded) }))
         .filter(({ score }) => score > 0)
         .sort((a, b) => b.score - a.score);
     return scored.slice(0, limit).map(({ snippet }) => snippet);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webspire/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for Webspire CSS snippets — AI-native snippet discovery and matching",
   "type": "module",
   "exports": {
@@ -23,13 +23,13 @@
     "data"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "catalog:",
-    "zod": "catalog:"
+    "@modelcontextprotocol/sdk": "^1.13.0",
+    "zod": "^4.2.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "tsx": "catalog:",
-    "typescript": "catalog:"
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
   },
   "keywords": [
     "mcp",