@webspire/mcp 0.9.0 → 0.11.0

package/dist/registration.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { loadFonts, searchSnippets } from './registry.js';
-import { CONTENT_NEED_KEYS, CONTENT_NEED_LABEL, composePage, DOMAIN_KEYS, DOMAIN_LABEL, normalizeContentNeed, recommendFonts, searchCanvasEffects, searchPatterns, TONE_KEYS, TONE_LABEL, UX_GOAL_KEYS, UX_GOAL_LABEL, } from './search.js';
+import { CONTENT_NEED_KEYS, CONTENT_NEED_LABEL, composePage, DOMAIN_KEYS, DOMAIN_LABEL, normalizeContentNeed, recommendFonts, searchCanvasEffects, searchMotionRecipes, searchPatterns, TONE_KEYS, TONE_LABEL, UX_GOAL_KEYS, UX_GOAL_LABEL, } from './search.js';
 function formatSnippetBrief(s) {
     return [
         `**${s.title}** (${s.id})`,
@@ -785,6 +785,133 @@ export function registerToolsWithProvider(server, getRegistry) {
             content: [{ type: 'text', text }],
         };
     });
+    // --- Motion Recipe Tools ---
+    function formatMotionBrief(r) {
+        return [
+            `**${r.title}** (${r.id})`,
+            `  ${r.summary}`,
+            `  Family: ${r.family} | Technology: ${r.technology} | Triggers: ${r.triggers.join(', ')}`,
+            r.tags.length > 0 ? `  Tags: ${r.tags.join(', ')}` : '',
+        ]
+            .filter(Boolean)
+            .join('\n');
+    }
+    function formatMotionFull(r) {
+        const deps = r.dependencies
+            .map((d) => `  ${d.name} v${d.version} — ${d.cdn}`)
+            .join('\n');
+        return [
+            `# ${r.title}`,
+            '',
+            r.description ?? r.summary,
+            '',
+            '## Identity',
+            `ID: ${r.id}`,
+            `Family: ${r.family}`,
+            `Technology: ${r.technology}`,
+            `Triggers: ${r.triggers.join(', ')}`,
+            '',
+            r.tags.length > 0 ? `## Tags\n${r.tags.join(', ')}` : '',
+            deps ? `## Dependencies\n${deps}` : '',
+            '',
+            '## HTML',
+            '```html',
+            r.html,
+            '```',
+        ]
+            .filter((l) => l !== undefined)
+            .join('\n');
+    }
+    server.tool('list_motion_recipes', 'List all available Motion Recipes grouped by family (reveal, scroll, transition, micro, layout).', {}, async () => {
+        const registry = await getRegistry();
+        const recipes = registry.motionRecipes ?? [];
+        const counts = {};
+        for (const r of recipes) {
+            counts[r.family] = (counts[r.family] ?? 0) + 1;
+        }
+        const result = Object.entries(counts)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([fam, count]) => `${fam}: ${count} recipe${count > 1 ? 's' : ''}`)
+            .join('\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${recipes.length} motion recipes across ${Object.keys(counts).length} families:\n\n${result}`,
+                },
+            ],
+        };
+    });
+    server.tool('search_motion_recipes', 'Search Webspire Motion Recipes by keyword, family, technology, or trigger. Returns matching recipes with descriptions.', {
+        query: z
+            .string()
+            .describe('Search query, e.g. "scroll reveal", "fade up", "stagger", "clip-path"'),
+        family: z
+            .string()
+            .optional()
+            .describe('Filter by family: reveal, scroll, transition, micro, layout'),
+        technology: z
+            .string()
+            .optional()
+            .describe('Filter by technology: gsap, motion-one, both'),
+        trigger: z
+            .string()
+            .optional()
+            .describe('Filter by trigger: scroll, hover, load, click'),
+    }, async ({ query, family, technology, trigger }) => {
+        const registry = await getRegistry();
+        const recipes = registry.motionRecipes ?? [];
+        if (recipes.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No motion recipes available in registry.',
+                    },
+                ],
+            };
+        }
+        const results = searchMotionRecipes(recipes, { query, family, technology, trigger });
+        if (results.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No motion recipes found matching your query.',
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${results.length} motion recipe${results.length > 1 ? 's' : ''}:\n\n${results.map(formatMotionBrief).join('\n\n')}\n\nUse \`get_motion_recipe(id)\` for full HTML source.`,
+                },
+            ],
+        };
+    });
+    server.tool('get_motion_recipe', 'Get full HTML source and dependency info for a specific Motion Recipe. Returns a self-contained HTML file.', {
+        id: z.string().describe('Recipe ID, e.g. "reveal/fade-up", "reveal/clip-reveal"'),
+    }, async ({ id }) => {
+        const registry = await getRegistry();
+        const recipes = registry.motionRecipes ?? [];
+        const recipe = recipes.find((r) => r.id === id);
+        if (!recipe) {
+            const available = recipes.map((r) => r.id).join(', ');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Motion recipe "${id}" not found. Available: ${available}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: formatMotionFull(recipe) }],
+        };
+    });
     // --- Canvas Effect Tools ---
     server.tool('search_canvas_effects', 'Search Webspire Canvas effects by keyword, category, or capability. Returns matching effects with their descriptions.', {
         query: z

package/dist/registry.d.ts

@@ -7,9 +7,15 @@ export interface RegistryOptions {
 }
 /**
  * Load the registry with fallback chain:
- * 1. Explicit --registry-file path
- * 2. Bundled data/registry.json (shipped with npm package)
- * 3. Remote fetch from --registry-url or default URL
+ * 1. Explicit --registry-file path (dev / CI override)
+ * 2. In-memory cache (5-min TTL, cleared when MCP process restarts)
+ * 3. Remote fetch from webspire.de — if newer than disk cache, writes to disk
+ * 4. Disk cache (~/.cache/webspire/registry.json) — persists across restarts,
+ *    always holds the last successfully fetched remote version
+ * 5. Bundled data/registry.json — frozen at npm publish time, last resort
+ *
+ * The date comparison (registry.generated) ensures the disk cache is only
+ * overwritten when the remote actually has newer content.
  */
 export declare function loadRegistry(options?: RegistryOptions): Promise<Registry>;
 /**

package/dist/registry.js

@@ -1,19 +1,16 @@
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { searchSnippets as searchEntries } from './search.js';
 const DEFAULT_REGISTRY_URL = 'https://webspire.de/registry.json';
 const CACHE_TTL_MS = 5 * 60 * 1000;
-let cache = null;
-/**
- * Resolve the path to the bundled registry.json shipped with this package.
- * Works both from src/ (development) and dist/ (published).
- */
+const DISK_CACHE_PATH = resolve(homedir(), '.cache', 'webspire', 'registry.json');
+let memCache = null;
 function getBundledRegistryPath() {
     try {
         const thisDir = dirname(fileURLToPath(import.meta.url));
-        // From dist/ → ../data/registry.json, from src/ → ../data/registry.json
         const candidate = resolve(thisDir, '..', 'data', 'registry.json');
         return existsSync(candidate) ? candidate : undefined;
     }
@@ -21,11 +18,39 @@ function getBundledRegistryPath() {
         return undefined;
     }
 }
+async function readDiskCache() {
+    try {
+        const raw = await readFile(DISK_CACHE_PATH, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeDiskCache(registry) {
+    try {
+        await mkdir(dirname(DISK_CACHE_PATH), { recursive: true });
+        await writeFile(DISK_CACHE_PATH, JSON.stringify(registry), 'utf-8');
+    }
+    catch {
+        // Best-effort — disk write failures are non-fatal
+    }
+}
+/** Returns true if registry a was generated after registry b. */
+function isNewer(a, b) {
+    return new Date(a.generated ?? 0).getTime() > new Date(b.generated ?? 0).getTime();
+}
 /**
  * Load the registry with fallback chain:
- * 1. Explicit --registry-file path
- * 2. Bundled data/registry.json (shipped with npm package)
- * 3. Remote fetch from --registry-url or default URL
+ * 1. Explicit --registry-file path (dev / CI override)
+ * 2. In-memory cache (5-min TTL, cleared when MCP process restarts)
+ * 3. Remote fetch from webspire.de — if newer than disk cache, writes to disk
+ * 4. Disk cache (~/.cache/webspire/registry.json) — persists across restarts,
+ *    always holds the last successfully fetched remote version
+ * 5. Bundled data/registry.json — frozen at npm publish time, last resort
+ *
+ * The date comparison (registry.generated) ensures the disk cache is only
+ * overwritten when the remote actually has newer content.
  */
 export async function loadRegistry(options) {
     // 1. Explicit file path
@@ -33,24 +58,42 @@ export async function loadRegistry(options) {
         const raw = await readFile(options.filePath, 'utf-8');
         return JSON.parse(raw);
     }
-    // 2. Bundled registry (no cache needed — file is local and fast)
+    // 2. In-memory cache (avoids re-fetching within the same session)
+    if (memCache && Date.now() - memCache.loadedAt < CACHE_TTL_MS) {
+        return memCache.registry;
+    }
+    // 3. Remote fetch — compare with disk cache, write if newer
+    try {
+        const url = options?.url ?? DEFAULT_REGISTRY_URL;
+        const response = await fetch(url);
+        if (response.ok) {
+            const remote = (await response.json());
+            memCache = { registry: remote, loadedAt: Date.now() };
+            // Write to disk only when remote is actually newer than what's cached
+            const disk = await readDiskCache();
+            if (!disk || isNewer(remote, disk)) {
+                await writeDiskCache(remote);
+            }
+            return remote;
+        }
+    }
+    catch {
+        // Network unavailable — fall through to disk cache
+    }
+    // 4. Disk cache — last successfully fetched version, survives process restarts
+    const disk = await readDiskCache();
+    if (disk) {
+        memCache = { registry: disk, loadedAt: Date.now() };
+        return disk;
+    }
+    // 5. Bundled registry — frozen at npm publish time
     const bundledPath = getBundledRegistryPath();
-    if (bundledPath && !options?.url) {
+    if (bundledPath) {
         const raw = await readFile(bundledPath, 'utf-8');
         return JSON.parse(raw);
     }
-    // 3. Remote fetch with TTL cache
-    if (cache && Date.now() - cache.loadedAt < CACHE_TTL_MS) {
-        return cache.registry;
-    }
-    const url = options?.url ?? DEFAULT_REGISTRY_URL;
-    const response = await fetch(url);
-    if (!response.ok) {
-        throw new Error(`Failed to fetch registry from ${url}: ${response.statusText}`);
-    }
-    const registry = (await response.json());
-    cache = { registry, loadedAt: Date.now() };
-    return registry;
+    throw new Error('Registry unavailable: network unreachable and no local cache found. ' +
+        'Try reinstalling @webspire/mcp or check your internet connection.');
 }
 /**
  * Load the bundled fonts.json shipped with this package.

package/dist/search.d.ts

@@ -1,4 +1,4 @@
-import type { CanvasEffectEntry, FontRecommendation, FontsData, PatternEntry, SnippetEntry } from './types.js';
+import type { CanvasEffectEntry, FontRecommendation, FontsData, MotionRecipeEntry, PatternEntry, SnippetEntry } from './types.js';
 export interface SnippetSearchOptions {
     query: string;
     category?: string;
@@ -61,3 +61,11 @@ export interface CanvasSearchOptions {
     limit?: number;
 }
 export declare function searchCanvasEffects(effects: CanvasEffectEntry[], options: CanvasSearchOptions): CanvasEffectEntry[];
+export interface MotionSearchOptions {
+    query: string;
+    family?: string;
+    technology?: string;
+    trigger?: string;
+    limit?: number;
+}
+export declare function searchMotionRecipes(recipes: MotionRecipeEntry[], options: MotionSearchOptions): MotionRecipeEntry[];

package/dist/search.js

@@ -999,3 +999,48 @@ export function searchCanvasEffects(effects, options) {
         .sort((a, b) => b.score - a.score);
     return scored.slice(0, limit).map(({ effect }) => effect);
 }
+export function searchMotionRecipes(recipes, options) {
+    const { query, family, technology, trigger, limit = 10 } = options;
+    const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const stems = words.map(stem);
+    const expanded = expandWithSynonyms(words);
+    if (stems.length === 0 && !family && !technology && !trigger)
+        return recipes.slice(0, limit);
+    const filtered = recipes.filter((r) => {
+        if (family && r.family !== family)
+            return false;
+        if (technology && r.technology !== technology)
+            return false;
+        if (trigger && !r.triggers.includes(trigger))
+            return false;
+        return true;
+    });
+    if (stems.length === 0)
+        return filtered.slice(0, limit);
+    const scored = filtered
+        .map((recipe) => {
+        let score = 0;
+        const idLower = recipe.id.toLowerCase();
+        for (const term of stems) {
+            if (idLower.includes(term))
+                score += 5;
+        }
+        const title = recipe.title.toLowerCase();
+        score += stems.filter((w) => title.includes(w)).length * 3;
+        const summary = recipe.summary.toLowerCase();
+        score += stems.filter((w) => summary.includes(w)).length * 2;
+        const tagStr = recipe.tags.join(' ').toLowerCase();
+        score += stems.filter((w) => tagStr.includes(w)).length * 2;
+        const tech = recipe.technology.toLowerCase();
+        score += stems.filter((w) => tech.includes(w)).length * 2;
+        const synonymOnly = expanded.filter((t) => !stems.includes(t));
+        if (synonymOnly.length > 0) {
+            const allText = [title, summary, tagStr].join(' ').toLowerCase();
+            score += synonymOnly.filter((w) => allText.includes(w)).length;
+        }
+        return { recipe, score };
+    })
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit).map(({ recipe }) => recipe);
+}

package/dist/types.d.ts

@@ -226,6 +226,28 @@ export interface CanvasEffectEntry {
     solves: string[];
     js: string;
 }
+export interface MotionRecipeEntry {
+    id: string;
+    title: string;
+    summary: string;
+    description?: string;
+    family: 'reveal' | 'scroll' | 'transition' | 'micro' | 'layout';
+    variant: string;
+    technology: 'gsap' | 'motion-one' | 'both';
+    triggers: Array<'scroll' | 'hover' | 'load' | 'click'>;
+    tags: string[];
+    dependencies: Array<{
+        name: string;
+        cdn: string;
+        version: string;
+    }>;
+    governance: {
+        status: 'draft' | 'review' | 'published' | 'deprecated';
+        quality: 'experimental' | 'stable' | 'flagship';
+        updatedAt: string;
+    };
+    html: string;
+}
 export interface Registry {
     version: string;
     generated: string;
@@ -233,6 +255,7 @@ export interface Registry {
     patterns?: PatternEntry[];
     templates?: TemplateEntry[];
     canvasEffects?: CanvasEffectEntry[];
+    motionRecipes?: MotionRecipeEntry[];
     fonts?: FontsData;
     mountCanvas?: string;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@webspire/mcp",
-  "version": "0.9.0",
-  "description": "MCP server for Webspire — AI-native discovery of CSS snippets, UI patterns, canvas effects, page templates, and font recommendations",
+  "version": "0.11.0",
+  "description": "MCP server for Webspire — AI-native discovery of CSS snippets, UI patterns, canvas effects, page templates, motion recipes, and font recommendations",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",