@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 (144)

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

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