@webspire/mcp 0.9.0 → 0.11.0

package/README.md

@@ -1,19 +1,6 @@
 # @webspire/mcp
 
-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.
-
-Includes CSS snippets, UI patterns, and page templates — all Tailwind v4, token-based, dark mode, accessible.
-
-## Stability Model
-
-Webspire is intentionally iterative.
-
-- Not every pattern or snippet is optimal yet.
-- Registry contents, taxonomy, scoring, and composition output may change over time.
-- The only guaranteed answer is the snapshot you receive when you make the request.
-- This is by design: the registry is supposed to keep improving instead of acting like a fixed framework API.
-
-The important invariant is different: MCP should provide context, discovery, and composition help, while the resulting code remains something you can own directly in your project. The goal is not to introduce a runtime dependency.
+MCP server for [Webspire](https://webspire.de) — AI-native discovery of CSS snippets, UI patterns, canvas effects, page templates, motion recipes, and font recommendations. All Tailwind v4, token-based, dark mode, accessible.
 
 ## Quick Start
 
@@ -32,25 +19,98 @@ The important invariant is different: MCP should provide context, discovery, and
 
 ## Available Tools
 
+### Snippets (CSS Effects)
+
 | 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 |
+
+### Patterns (UI Components)
+
+| Tool | Description |
+|------|-------------|
 | `list_pattern_families` | List pattern families with counts |
-| `search_patterns` | Search UI patterns by intent, family, or tier |
-| `compose_page` | Compose a full page structure and recommend matching snippets |
+| `search_patterns` | Search UI patterns by intent, domain, tone, or ux goal |
 | `get_pattern` | Get full pattern HTML with component token references |
+| `compose_page` | Compose a full page: patterns + snippets + font recommendations |
+
+### Templates (Full Pages)
+
+| Tool | Description |
+|------|-------------|
 | `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) |
+
+### Canvas Effects (Dynamic Visuals)
+
+| Tool | Description |
+|------|-------------|
+| `search_canvas_effects` | Search canvas effects by keyword, category, or interactivity |
+| `get_canvas_effect` | Get full JS source, mountCanvas runtime, and embed HTML |
+
+### Motion Recipes (Animation Patterns)
+
+| Tool | Description |
+|------|-------------|
+| `list_motion_recipes` | List all motion recipes grouped by family |
+| `search_motion_recipes` | Search recipes by keyword, family, technology, or trigger |
+| `get_motion_recipe` | Get full self-contained HTML for a motion recipe |
+
+### Fonts (Semantic Recommendations)
+
+| Tool | Description |
+|------|-------------|
+| `recommend_fonts` | Get heading/body/mono font stack for a domain + tone combination |
+
+### Tokens (Design System)
+
+| Tool | Description |
+|------|-------------|
+| `setup_tokens` | Get token CSS files to write into your project |
 | `recommend_token_mapping` | Analyze your project tokens and suggest --ws-* mapping |
 
-## 3-Layer Token Architecture
+## Content
+
+### CSS Snippets (144)
+
+Effects that Tailwind v4 can't do natively across 12 categories: glass, animations, easing, scroll, decorative, interactions, text, lighting, depth, masks, surfaces, atmosphere.
 
-Patterns use semantic CSS custom properties via a 3-layer system:
+### UI Patterns (519+)
+
+Page sections and content elements across 170+ families — hero, navbar, pricing, features, dashboard, e-commerce, AI, developer tools, and more. All using `--ws-*` component tokens.
+
+### Canvas Effects (3)
+
+Dynamic JavaScript visuals using the `mountCanvas` runtime: particle fields, proximity dots, gradient orbs. Copy-paste ready with HiDPI support, ResizeObserver, and prefers-reduced-motion.
+
+### Page Templates (42)
+
+Complete standalone pages: SaaS, agency, portfolio, shop, company — with Tailwind CDN.
+
+### Motion Recipes (3)
+
+Framework-agnostic animation patterns using GSAP and Motion One. Self-contained HTML files with live scroll demos. Families: reveal, scroll, transition, micro, layout.
+
+### Font Recommendations (25 fonts, 15 pairings)
+
+Semantic font stack recommendations based on domain (legal, saas, agency...) and tone (serious, modern, friendly...). All fonts available as npm packages via @fontsource.
+
+## Offline Support
+
+The MCP works without a permanent internet connection. Registry data is loaded using a layered fallback:
+
+1. **In-memory cache** (5-min TTL) — no re-fetch within the same session
+2. **Remote fetch** from webspire.de — always current, writes to disk when newer
+3. **Disk cache** (`~/.cache/webspire/`) — last successfully fetched version, survives restarts
+4. **Installed copy** — frozen at publish time, last resort
+
+In practice: go online once, the disk cache is written. All subsequent offline starts use that cached version, not the potentially older installed copy.
+
+## 3-Layer Token Architecture
 
 ```
 Host Tokens (your project) → WebSpire Alias Tokens → Component Tokens → Markup
@@ -61,32 +121,23 @@ Host Tokens (your project) → WebSpire Alias Tokens → Component Tokens → Ma
 ```
 > 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>
-```
+## Page Composition
 
-### Customize
+`compose_page` combines semantic pattern selection with snippet recommendations and font pairing.
 
-```css
-:root {
-  --ws-color-primary: #your-brand-color;
-  --ws-color-primary-hover: #your-brand-darker;
-}
 ```
+> compose_page({ domain: "legal", tone: "serious", ux_goals: ["build_trust", "drive_contact"] })
+```
+
+Returns:
+1. Ordered page sections (navbar → hero → features → testimonials → contact → footer)
+2. Recommended CSS snippets for visual polish
+3. Font stack recommendation (heading + body + mono with npm install command)
 
 ## Available Resources
 
@@ -100,20 +151,6 @@ Host Tokens (your project) → WebSpire Alias Tokens → Component Tokens → Ma
 | `webspire://templates` | All templates with brief metadata |
 | `webspire://template/{id}` | Full template data including HTML |
 
-## Content
-
-### CSS Snippets
-
-Effects that Tailwind v4 can't do natively across 12 categories: glass, animations, easing, scroll, decorative, interactions, text, lighting, depth, masks, surfaces, atmosphere.
-
-### UI Patterns
-
-Patterns across page sections and content elements — all using `--ws-*` component tokens.
-
-### Page Templates
-
-Complete standalone pages: SaaS, agency, portfolio, shop, company — with Tailwind CDN.
-
 ## Programmatic Usage
 
 ```typescript
@@ -126,16 +163,14 @@ const results = searchSnippets(registry, {
 });
 ```
 
-Docs: https://webspire.de/tokens
-
-## Page Composition
+## Stability Model
 
-`compose_page` combines semantic pattern selection with a lightweight snippet recommendation layer.
+Webspire is intentionally iterative.
 
-Typical flow:
+- Registry contents, taxonomy, scoring, and composition output may change over time.
+- The only guaranteed answer is the snapshot you receive when you make the request.
+- This is by design: the registry keeps improving instead of acting like a fixed framework API.
 
-1. Call `compose_page` with `domain`, `tone`, and `ux_goals`
-2. Retrieve section markup with `get_pattern(id)`
-3. Retrieve enhancement CSS with `get_snippet(id)` for the recommended snippets
+The important invariant: MCP provides context, discovery, and composition help, while the resulting code remains something you own directly in your project. No runtime dependency is introduced.
 
-That keeps structure and polish separate, but coordinated.
+Docs: https://webspire.de

package/css/webspire-components.css

@@ -280,6 +280,8 @@
   --ws-steps-accent: var(--ws-color-primary);
   --ws-steps-accent-text: var(--ws-color-primary-text);
   --ws-steps-line: var(--ws-color-border);
+  --ws-steps-border: var(--ws-color-border);
+  --ws-steps-number: var(--ws-color-border);
 }
 
 .ws-divider {
@@ -358,8 +360,10 @@
 .ws-code-preview {
   --ws-code-preview-bg: #0f172a;
   --ws-code-preview-text: #e2e8f0;
+  --ws-code-preview-text-muted: #64748b;
   --ws-code-preview-header-bg: #1e293b;
   --ws-code-preview-border: #334155;
+  --ws-code-preview-tab-active-bg: #1e293b;
 }
 
 .ws-cookie-consent {
@@ -655,3 +659,47 @@
   --ws-chat-widget-accent-text: var(--ws-color-primary-text);
   --ws-chat-widget-muted-bg: var(--ws-color-surface-muted);
 }
+
+.ws-case-study {
+  --ws-case-study-bg: var(--ws-color-surface);
+  --ws-case-study-card-bg: var(--ws-color-surface-alt);
+  --ws-case-study-text: var(--ws-color-text);
+  --ws-case-study-text-soft: var(--ws-color-text-soft);
+  --ws-case-study-text-muted: var(--ws-color-text-muted);
+  --ws-case-study-border: var(--ws-color-border);
+  --ws-case-study-accent: var(--ws-color-primary);
+}
+
+.ws-platform {
+  --ws-platform-bg: var(--ws-color-surface);
+  --ws-platform-text: var(--ws-color-text);
+  --ws-platform-text-soft: var(--ws-color-text-soft);
+  --ws-platform-text-muted: var(--ws-color-text-muted);
+  --ws-platform-border: var(--ws-color-border);
+  --ws-platform-accent: var(--ws-color-primary);
+  --ws-platform-diagram-bg: var(--ws-color-surface-alt);
+  --ws-platform-layer-bg: var(--ws-color-surface);
+  --ws-platform-chip-bg: var(--ws-color-surface-alt);
+  --ws-platform-grid-line: var(--ws-color-border);
+}
+
+.ws-changelog {
+  --ws-changelog-bg: var(--ws-color-surface);
+  --ws-changelog-text: var(--ws-color-text);
+  --ws-changelog-text-soft: var(--ws-color-text-soft);
+  --ws-changelog-text-muted: var(--ws-color-text-muted);
+  --ws-changelog-border: var(--ws-color-border);
+  --ws-changelog-accent: var(--ws-color-primary);
+  --ws-changelog-code-bg: var(--ws-color-surface-muted);
+}
+
+.ws-mega-menu {
+  --ws-mega-menu-bg: var(--ws-color-surface);
+  --ws-mega-menu-text: var(--ws-color-text);
+  --ws-mega-menu-text-soft: var(--ws-color-text-soft);
+  --ws-mega-menu-text-muted: var(--ws-color-text-muted);
+  --ws-mega-menu-border: var(--ws-color-border);
+  --ws-mega-menu-accent: var(--ws-color-primary);
+  --ws-mega-menu-hover-bg: var(--ws-color-surface-alt);
+  --ws-mega-menu-icon-bg: var(--ws-color-primary-soft);
+}