UI预设配置服务器

一个用于自动配置React UI设计预设的MCP服务器,可集成Monaco IDE,通过确定性质量门控和多风格预设系统确保跨业务构建的设计统一性。

  • by ncsound919
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 ncsound919/OG-Glass

使用说明

UI Preset MCP Server

MCP server for auto-configuring React UI against a swappable design preset system. Integrates with your Monaco IDE to enforce design uniformity across all business builds. Supports glassmorphism, neumorphism, neon cyberpunk, brutalism, soft pastels, aurora gradients, plus new flat/material/healthcare/editorial/minimal styles — a baby Canva for frontend development.

Design precision + JEV decision process (v1.1)

Every project gets a deep, per-project design decision grounded in awesome-design principles and current frontend practice:

Tool What it does
decide_design_direction JEV decides style, palette strategy, graphics treatment, precision level, and dark/light over bounded questions whose criteria encode awesome-design + current-practice standards. Offline JEV falls back to a deterministic keyword classifier with the real error reported (never a fabricated decision).
design_brief The full process: JEV direction → resolve preset on disk → run the deterministic quality gate → export a DESIGN.md contract. "Adheres each time" = decision + quality.passed=true + DESIGN.md emitted.
validate_preset Deterministic precision gate: valid colors, WCAG AA text contrast vs base bg, spacing on the 4pt grid, strictly increasing type scale, zero unresolved {{token:}} refs. Returns score 0-100 + every finding.
list_preset_quality Quality score for every preset, sorted. Use it to pick the most precise preset for a project.
export_design_markdown Exports a preset's tokens as a Stitch/awesome-design-md DESIGN.md (palette, typography, spacing, depth, components, do's/don'ts, agent prompt guide). Deterministic.

Math-enhanced refinement (JEV decides, math improves)

Presets are templates, not final output. design_brief returns both:

  • design_md — the template as-is

  • refined — the template creatively improved by math: JEV picks the strategy (decideRefinement: golden-ratio / perfect-fourth / major-third spacing+type, analogous / complementary / triadic / split-complementary / monochrome harmony, precision, detail), then a deterministic engine applies it:

    • Spacing → golden-ratio scale round4(4·φ^i) kept on the 4pt grid
    • Type → modular scale 0.8125rem · ratio^i (strictly increasing)
    • Color → harmonic accent family derived from the primary hue (HSL offsets)
    • Radius → proportional to the refined scale

Every change is logged in a math_report ({field, before, after, math}), the refined preset passes the quality gate, and a refined DESIGN.md is emitted. This is the deterministic math core (same substance as math-x's Pyodide/SymPy subsystems) computed in-process — no LLM, and math-x's LLM-routed API is not called.

{ "strategy": { "ratio": "golden", "harmony": "complementary", "precision": 1, "detail": 1 },
  "math_report": { "steps": [ { "field": "spacing.scale", "math": "round4(4 × φ^i)" } ] },
  "refined_quality": { "passed": true, "score": 100 },
  "refined_design_md": "# DESIGN.md — Flat Corporate (refined)" }

refine_design tool refines any preset; REST: POST /api/design-brief returns the same shape.

Design grade — the measurable "high-end" bar

grade_design (tool + GET /api/presets/:id/grade) scores every preset S/A/B/C across eight categories: token completeness, WCAG contrast, 4pt spacing, type scale, elevation depth, motion system, component depth (breadth + variants + a11y coverage), and token validity. Deterministic — same preset, same grade.

Full UI-kit generation

generate_ui_kit (tool + GET /api/presets/:id/kit) emits a complete, runnable React + CSS-variables kit from a preset (template or refined): a complete tokens.css (every token flattened, including nested spacing/typography/ animation), every component + variant with tokens resolved to var(--…), an index.ts barrel, and a README. Deterministic, zero LLM.

The component library now ships 22 components with variants, states, and accessibility (aria/role/focus/disabled): Button, Select, Checkbox, Switch, Tabs, Alert, Skeleton, Tooltip, ProgressBar, Badge, EmptyState, Avatar, Pagination, DataTable, StatCard, FormField, Modal, Toast, Sidebar, GlassCard, OptionGroup, NavGroup.

The quality gate is the prerequisite: all 14 presets pass it (muted text in the legacy dark presets was darkened to reach AA — the gate caught the failures).

New style presets (beyond glassmorphism)

style-flat-corporate, style-material, style-healthcare, style-editorial, style-minimal-light — each extends glassmorphic-base, overrides tokens (palette, type, radius, depth), and inherits components. New base components: DataTable, StatCard, FormField, Modal, Toast.

Env

OG_GLASS_JEV_URL      # default http://127.0.0.1:8080 (System One)
OG_GLASS_JEV_ENABLED  # set 0 to force the offline classifier
OG_GLASS_JEV_TIMEOUT  # seconds per request

Tests

npm test    # build + node --test (11 tests: color math, quality gate, DESIGN.md, JEV)

Architecture

ui-preset-mcp-server/
├── src/
│   ├── index.ts                    # Server entry point (stdio + HTTP transports)
│   ├── constants.ts                # Shared constants and paths
│   ├── types/
│   │   └── index.ts                # All TypeScript types (tokens, presets, corrections)
│   ├── schemas/
│   │   └── toolSchemas.ts          # Zod validation schemas for every tool
│   ├── services/
│   │   ├── presetLoader.ts         # Reads + deep-merges preset files with caching
│   │   ├── sessionState.ts         # Active preset session management + overrides
│   │   ├── uiCorrector.ts          # AST correction engine (10 correction passes)
│   │   ├── tokenResolver.ts        # Resolves {{token:x.y.z}} placeholders + export generators
│   │   └── fileWatcher.ts          # Hot-reload presets on disk changes (dev mode)
│   ├── tools/
│   │   ├── presetTools.ts          # load_preset, swap_template, list_presets, diff_presets, scaffold_preset
│   │   ├── correctionTools.ts      # autocorrect_component, validate_ui, generate_component, generate_tokens, apply_token_overrides
│   │   └── styleTools.ts           # generate_color_palette, suggest_style, list_style_categories
│   ├── routes/
│   │   └── uiRoutes.ts             # REST API + Design Studio dashboard (GET /, /api/*)
│   └── ui/
│       └── dashboardHtml.ts        # Embedded Design Studio HTML (9 sections)
└── presets/
    ├── glassmorphic-base/          # Core preset (all others inherit from this)
    │   ├── manifest.json
    │   ├── tokens.json             # Full design token system
    │   ├── components/
    │   │   ├── shell/Sidebar.json
    │   │   ├── surfaces/GlassCard.json
    │   │   ├── settings/OptionGroup.json
    │   │   └── navigation/NavGroup.json
    │   └── layouts/DashboardLayout.json
    ├── client-fintech/             # Blue accent, dense spacing
    ├── client-saas/                # Purple accent, wider cards
    ├── client-dark-minimal/        # Monochrome, reduced glass intensity
    ├── style-neumorphic/           # Light soft UI, extruded shadows, no blur
    ├── style-neon-cyberpunk/       # Pitch-dark + neon accents, monospace type
    ├── style-brutalist/            # Raw B&W, zero radius, heavy typography
    ├── style-soft-pastel/          # Lavender background, pastel accents, generous rounding
    └── style-aurora/               # Deep navy + iridescent aurora purple/teal accents

MCP Tools

Preset Management

Tool Description
load_preset Activate a preset bundle by ID
swap_template Hot-swap active preset without restart
list_presets List all available presets
diff_presets Compare token/component differences between two presets
scaffold_preset Generate a new preset directory from a parent
get_session_state Check active preset and runtime overrides

Correction & Generation

Tool Description
autocorrect_component Auto-fix React component against active preset
validate_ui Validate component and get conformance score (0–100)
generate_component Generate a component from a preset template
generate_tokens Export tokens as CSS vars, JS, JSON, or Tailwind config
apply_token_overrides Layer runtime token overrides on the active preset

Style & Color

Tool Description
generate_color_palette Generate a harmonious color palette from a seed hex color using color theory (complementary, triadic, analogous, monochromatic, split-complementary, tetradic)
suggest_style Get preset + token override suggestions from a natural-language aesthetic description (e.g. "dark hacker terminal", "friendly pastel kids app")
list_style_categories List all available design style categories with principles, descriptions, and associated presets

Style Categories

Category Preset Description
Glassmorphic glassmorphic-base, client-* Frosted-glass with backdrop blur, dark substrate
Neumorphic style-neumorphic Soft extruded shapes, dual shadows, light background
Neon Cyberpunk style-neon-cyberpunk Pitch-dark + vivid neon accents, monospace type
Brutalist style-brutalist Raw B&W, zero border-radius, maximum contrast
Soft Pastel style-soft-pastel Lavender base, pastel accents, generous rounding
Aurora Gradient style-aurora Deep navy + iridescent aurora purple/teal accents

Installation

npm install
npm run build

Usage

stdio (for Monaco IDE integration)

node dist/index.js

HTTP server

TRANSPORT=http PORT=3001 node dist/index.js

Dev mode with hot-reload

WATCH_PRESETS=true node dist/index.js

Design Studio UI

When running in HTTP mode, a Design Studio mini UI is served at GET /.

UI Sections

Section Description
Dashboard Active preset overview with component/layout stats and color palette preview
Presets Browse all presets in cards; click Load to activate any preset instantly
Style Gallery Visual style category browser — each card shows design principles and a color preview strip; load any style with one click
Palette Color palette generator — pick a seed color, choose a color harmony rule, and generate a full palette with shades and semantic aliases; apply directly to active preset
Tokens Visual token viewer — color swatches, typography scale, blur, spacing, animation
Validate Paste React code and get a conformance score (0–100) with issue list
Correct Auto-correct React code against the active preset; choose context and mode
Export Generate CSS custom properties, TypeScript const, JSON, or Tailwind config
Scaffold Form to create a new preset from any parent with optional accent color

The UI communicates with the server via a REST API also available at /api/*.

REST API (HTTP mode)

Endpoint Method Description
/api/presets GET List all presets with metadata
/api/presets/load POST Load and activate a preset { preset_id }
/api/session GET Get active preset and override state
/api/tokens GET Get effective tokens for the active preset
/api/tokens/export POST Export tokens `{ format: 'css'
/api/tokens/overrides POST Apply runtime token overrides { overrides }
/api/validate POST Validate React code { code, include_suggestions }
/api/correct POST Autocorrect React code { code, context, dry_run }
/api/scaffold POST Create new preset { preset_id, name, description, extends, accent_color }
/api/styles GET List all design style categories with metadata
/api/palette POST Generate color palette { seed_color, harmony, include_shades }

Typical Workflow

1. list_style_categories()                    # Discover available aesthetics
2. suggest_style("dark sci-fi dashboard")     # Get preset recommendation
3. load_preset("style-neon-cyberpunk")        # Activate chosen style
4. const palette = generate_color_palette({ seed_color: "#00ff88", harmony: "triadic" })
5. apply_token_overrides({
     overrides: {
       colors: {
         accent: {
           primary: palette.semantic.accent,
           highlight: palette.semantic.highlight
         }
       }
     }
   })
6. autocorrect_component(code)               # Fix component on save
7. validate_ui(code)                         # Get conformance score
8. generate_tokens({ format: "css" })        # Export CSS variables
9. scaffold_preset({ preset_id: "client-x", extends: "style-aurora" })

Creating New Presets

New presets only need to override tokens that differ from the parent:

// presets/client-newbrand/tokens.json
{
  "colors": {
    "accent": {
      "primary": "#e11d48"
    }
  }
}
// presets/client-newbrand/manifest.json
{
  "id": "client-newbrand",
  "name": "New Brand",
  "extends": "glassmorphic-base",
  "version": "1.0.0",
  "styleCategory": "glassmorphic",
  "designPrinciples": ["backdrop-blur", "dark-substrate"],
  "tags": ["custom"],
  "components": [],
  "layouts": []
}

All base tokens, components, and layouts are inherited automatically.

Correction Rules

The correction engine enforces these rules on every component:

  • no-hardcoded-colors (error): All color values must use CSS custom properties
  • no-hardcoded-spacing (warning): Spacing should use the token scale
  • enforce-glass-surface (error): Surface elements must have backdropFilter + semi-transparent bg
  • no-hardcoded-font-family (error): Font families must use typography tokens
  • use-animation-tokens (warning): Transitions must use animation tokens
  • enforce-sidebar-components (error): Sidebar content must use NavGroup/NavItem
  • enforce-settings-components (error): Settings UI must use OptionGroup/OptionRow
  • a11y-img-alt (warning): Images must have alt attributes
  • a11y-icon-button-label (warning): Icon buttons need aria-label

Monaco Integration

In your Monaco editor, call autocorrect_component on the save event:

editor.onDidSaveModel(async () => {
  const code = editor.getValue();
  const result = await mcpClient.callTool('autocorrect_component', {
    code,
    context: 'auto',
    dry_run: false
  });
  if (result.corrected !== code) {
    editor.setValue(result.corrected);
  }
});