@webspire/mcp

MCP server for Webspire — 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

Claude Code / Claude Desktop

{
  "mcpServers": {
    "webspire": {
      "command": "npx",
      "args": ["-y", "@webspire/mcp"]
    }
  }
}

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, 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 |

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 |

Content

CSS Snippets (148)

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 (628+)

Page sections and content elements across 186 families — hero, navbar, pricing, features, dashboard, e-commerce, AI, developer tools, enterprise SaaS, 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.

Guides (20)

Design system knowledge: semantic composition, token architecture, AI prompting, and pattern usage guides.

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

Setup via MCP

> setup_tokens()
// Returns webspire-tokens.css + webspire-components.css

> setup_tokens({ components: ["hero", "cta", "pricing"] })
// Only includes tokens for the families you use

Page Composition

compose_page combines semantic pattern selection with snippet recommendations and font pairing.

> 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

| URI | Description | |-----|-------------| | 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 |

Programmatic Usage

import { loadRegistry, searchSnippets } from '@webspire/mcp/registry';

const registry = await loadRegistry();
const results = searchSnippets(registry, {
  query: 'glass card hover',
  darkMode: true,
});

Stability Model

Webspire is intentionally iterative.

• 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.

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.

Docs: https://webspire.de