Skip to main content
Glama
krusch-frontend-mcp

krusch-frontend-mcp

by kruschdev

krusch-frontend-mcp

Give your AI agent a design eye — MCP tools for color theory, layout analysis, canonical component templates, and design system enforcement.

Node.js 22+ License: MIT MCP: 12 Tools Storage: sqlite-vec + FTS5 Tests: 48 Passed M8ven Score

AI-powered styling assistant MCP server that provides deterministic design utilities, canonical HTML/SVG/Vercel layout primitives, and Hybrid RAG-backed design rule retrieval for autonomous frontend development.

Features

  • 12 MCP tools — deterministic CSS/color algorithms, canonical component & Vercel templates, provenance graph traversal, and LLM-assisted generation

  • 48 curated design rules — WCAG accessibility, Refactoring UI heuristics, Vercel Next.js App Router / Edge streaming patterns, typography, and spacing

  • Canonical template substrate (16 templates) — bit-for-bit HTML/SVG brand primitives (article-shell, site-header, footer-deadbolt, deadbolt-svg, cyber-grid, nav-back) and @krusch/toolkit + Vercel Lego bricks (lego-vercel-nextjs-shell, lego-vercel-edge-sse, lego-vercel-json, etc.) preventing ad-hoc layout drift

  • Figma token ingestion — parse design system JSON directly into CSS custom properties or the RAG store

  • Hybrid sqlite-vec + SQLite FTS5 (BM25) RRF — combines 1024d cosine similarity with lexical BM25 search via Reciprocal Rank Fusion, with automatic zero-network FTS5 fallback when offline

  • Fleet-aware Ollama routing — optional multi-node load balancing for embeddings

Related MCP server: Atelier-MCP

Requirements

  • Node.js 22+

  • Ollama running locally (or on a remote host; optional for deterministic tools and offline FTS5 rule retrieval)

  • Recommended Ollama models:

    • snowflake-arctic-embed2 — 8,192-ctx 1024-dim embedder for design rules and tokens (or configurable EMBED_MODEL)

    • qwen2.5-coder:7b — for layout analysis and component style generation (or configurable LLM_MODEL)

ollama pull snowflake-arctic-embed2
ollama pull qwen2.5-coder:7b

Installation

Agent-Assisted Setup

Ask your coding agent (Claude Code, Codex, Cursor, Windsurf, or Antigravity):

Read https://raw.githubusercontent.com/kruschdev/krusch-frontend-mcp/main/INSTALL.md and set up krusch-frontend-mcp on this machine.

Manual Setup

git clone https://github.com/kruschdev/krusch-frontend-mcp.git
cd krusch-frontend-mcp
npm install

Seed the RAG store

On first run, seed the database with 48 curated design rules:

npm run seed

This is idempotent — running it again safely replaces existing rules.

Configuration

All configuration is via environment variables. Create a .env file or export them directly:

Variable

Default

Description

OLLAMA_URL

http://localhost:11434

Primary Ollama instance URL

OLLAMA_NODES

(derived from OLLAMA_URL)

Comma-separated host:port list for fleet routing

EMBED_MODEL

snowflake-arctic-embed2

Ollama model for embeddings

EMBED_DIMENSION

1024

Embedding vector dimension

LLM_MODEL

qwen2.5-coder:7b

Ollama model for layout and component style generation

DEBUG

false

Enable debug logging

Multi-node Ollama fleet

If you have multiple Ollama instances, set OLLAMA_NODES for round-robin load balancing on embedding operations:

export OLLAMA_NODES="localhost:11434,gpu-server:11434,inference-node:11434"

Usage with Claude Desktop / Cursor / etc.

Add to your MCP client configuration:

{
  "mcpServers": {
    "krusch-frontend-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/krusch-frontend-mcp/src/index.js"]
    }
  }
}

Tools (12 Tools)

Deterministic & Canonical Primitives (no LLM required)

Tool

Description

generate_color_palette

HSL math palette generation from a base hex code with WCAG contrast scoring

css_to_tailwind

AST-based CSS → Tailwind class mapping (~230 entries + shorthand expansion)

generate_css_variables_from_figma

Parse Figma JSON tokens into a CSS :root block with custom properties

generate_responsive_breakpoints

CSS media query generation with customizable breakpoint widths

get_canonical_template

Retrieve 16 authoritative HTML/SVG, Vercel Next.js/Edge, & @krusch/toolkit Lego templates (article-shell, site-header, footer-deadbolt, deadbolt-svg, cyber-grid, nav-back, lego-node-api, lego-mcp-server, lego-sse-route, lego-react-shell, lego-fastapi-app, lego-cloudflare-worker, lego-webhook-route, lego-vercel-nextjs-shell, lego-vercel-edge-sse, lego-vercel-json)

list_canonical_templates

List all 16 available canonical HTML/SVG brand primitives, Vercel bricks, and Lego code starter templates

RAG & Provenance Lineage (SQLite FTS5 + sqlite-vec)

Tool

Description

ingest_figma_tokens

Embed and store Figma JSON tokens in the vector database

query_design_rules

Hybrid semantic + lexical BM25 search over 48 curated design rules with optional paradigm filter

frontend_get_provenance

Trace version history and provenance of a design rule or token in SQLite

frontend_traverse_graph

Traverse parent/child lineage graphs for frontend design rules

LLM-assisted (requires Ollama for inference)

Tool

Description

analyze_layout_structure

HTML → CSS layout analysis (Flexbox vs Grid recommendation)

generate_component_styles

RAG-enriched component style generation from natural language descriptions

Design Rule Paradigms

The query_design_rules and generate_component_styles tools support an optional paradigm filter:

  • universal (35 rules) — WCAG accessibility, spacing scales, typography, color systems, layout patterns, animation timing

  • refactoring-ui (7 rules) — Heuristics from Refactoring UI: hierarchy through weight, de-emphasized borders, visual alignment

  • vercel (6 rules) — Vercel Next.js App Router SSR hydration safety (useMounted), unbuffered Edge SSE streaming (force-dynamic, no-transform), Web-Standards Edge runtime purity, zero-CLS font/SVG sizing, and vercel.json security headers

Development

# Run tests (48 cases)
npm test

# Seed RAG store (idempotent)
npm run seed

# Start MCP server (stdio mode)
npm start

Architecture

krusch-frontend-mcp/
├── src/
│   ├── index.js           # MCP server entrypoint (stdio transport)
│   ├── config.js           # Environment-based configuration
│   ├── rag-engine.js       # sqlite-vec vector store + paradigm-aware search
│   ├── lib/
│   │   ├── db.js           # Standalone better-sqlite3 wrapper
│   │   └── llm.js          # Minimal Ollama chat client
│   └── tools/
│       ├── color.js        # HSL/Hex math — palette generation + WCAG contrast
│       ├── tailwind.js     # AST-based CSS → Tailwind class mapping
│       ├── figma.js        # Figma JSON token ingestion + CSS variable generation
│       ├── design-rules.js # RAG-powered design rule retrieval
│       ├── layout.js       # LLM HTML → CSS layout analysis
│       ├── embed.js        # Ollama embedding client (fleet-aware)
│       ├── breakpoints.js  # Responsive breakpoint generator
│       └── component-styles.js # LLM-assisted component style generation
├── scripts/
│   ├── seed-utils.js              # Shared seeding utility
│   ├── seed-design-rules.js       # 29 universal baseline rules
│   ├── ingest-refactoring-ui.js   # 7 Refactoring UI aesthetic rules
│   └── ingest-universal-a11y.js   # 6 extended WCAG/ARIA rules
└── tests/                         # 27 test cases (node:test)

License

MIT

Available Tools

12 tools
analyze_layout_structureC
Read-onlyIdempotent

Accepts an HTML structure and returns the optimal CSS layout approach (Flexbox vs Grid) and the necessary CSS.

Inputs: htmlString (required).

css_to_tailwindC
Read-onlyIdempotent

Translates standard CSS properties into Tailwind utility classes.

Inputs: cssString (required).

frontend_get_provenanceB
Read-onlyIdempotent

Company Brain Substrate (SQLite): Interrogate why a piece of context or design rule exists by tracing its version history.

Inputs: id (required).

frontend_traverse_graphB
Read-onlyIdempotent

Company Brain Substrate (SQLite): Graph Traversal. Traverses parent/child memory lineage for frontend design rules.

Inputs: id (required), depth, direction.

generate_color_paletteA
Read-onlyIdempotent

Generates a cohesive color palette (complementary, analogous, triadic) and contrast scores from a base hex code.

Inputs: baseHex (required).

generate_component_stylesB
Read-onlyIdempotent

Given a component description (e.g. 'glassmorphism card with hover lift'), generates CSS custom properties and classes. Enriches output with RAG-retrieved design rules.

Inputs: description (required), paradigm.

generate_css_variables_from_figmaA
Read-onlyIdempotent

Parses Figma JSON token exports and returns a CSS string with a :root block defining CSS custom properties (variables) for each token. Use this to generate actual CSS rather than ingesting into the RAG.

Inputs: tokensJsonStr (required).

generate_responsive_breakpointsA
Read-onlyIdempotent

Generates standard CSS media queries for responsive breakpoints (e.g. sm, md, lg) with optional custom width overrides.

Inputs: customBreakpoints.

get_canonical_templateB
Read-onlyIdempotent

Returns the authoritative bit-for-bit HTML/SVG component template or @krusch/toolkit & krusch_toolkit Lego starter brick for krusch.dev and homelab projects.

Inputs: templateKey (required).

ingest_figma_tokensB
Idempotent

Parses Figma JSON token exports, converts them to CSS variables/Tailwind configs, and indexes them into the RAG database.

Inputs: tokensJsonStr (required).

list_canonical_templatesA
Read-onlyIdempotent

Lists all available canonical HTML/SVG design templates and @krusch/toolkit & krusch_toolkit Lego starter bricks for homelab projects.

Inputs: no named parameters.

query_design_rulesB
Read-onlyIdempotent

Semantic RAG search over specific design guidelines, CSS architecture, and accessibility standards.

Inputs: queryStr (required), paradigm.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (palette generation, layout analysis, breakpoints, RAG query, provenance). The one genuinely confusable pair is ingest_figma_tokens vs generate_css_variables_from_figma, which both parse Figma JSON, but the descriptions explicitly differentiate RAG ingestion from CSS output. Minor residual overlap between generate_component_styles and generate_css_variables_from_figma is manageable via descriptions.

    Naming Consistency4/5

    All names use consistent snake_case with a verb_noun shape (generate_*, query_*, analyze_*, list_*, get_*). The only deviation is the 'frontend_' prefix applied to just two of twelve tools, which slightly breaks the pattern but remains readable and descriptive.

    Tool Count5/5

    Twelve tools is well within the sweet spot for a design-system/frontend server, with each tool covering a distinct stage (tokens, CSS, layout, components, knowledge retrieval, templates). No obviously redundant or filler tools.

    Completeness4/5

    The surface covers the full frontend design pipeline: palette, CSS-to-Tailwind, Figma token ingestion and CSS variable emission, layout analysis, component styling, breakpoints, RAG queries, provenance/graph traversal, and canonical template listing/retrieval. Minor gaps exist around theme/dark-mode generation and writing back or updating design rules/tokens, but core workflows are covered end to end.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding assistants to inspect frontend projects, search a curated design and motion recipe catalog, prepare and preview structured design plans, apply changes with backups and rollback, capture previews, audit UI accessibility and performance, and monitor activity via a web dashboard.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding assistants to generate bespoke design systems by synthesizing OKLCH color palettes, chamfer highlights and spring physics, teaching layout composition grammar, and returning micro-interaction primitives and component blueprints. Also audits JSX/TSX/HTML through a senior design director's lens to score and critique UI quality.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Gives AI coding agents a ten-phase frontend design pipeline (audit, style direction, build, review, verify, perf, brand) with an exclusive style menu. Its verify_page tool loads a URL in a real Playwright browser at mobile and desktop viewports and returns screenshots, ARIA snapshots, console errors, failed requests, horizontal-overflow offenders, axe-core violations, and pointer type.
      3
      MIT