Model Context Protocol (MCP)

What is Model Context Protocol (MCP)?

@shavin/ui includes a native, zero-hallucination Model Context Protocol (MCP) server (shavin-mcp) that exposes machine-readable design system intelligence directly to AI coding assistants (Cursor, Claude Code, Antigravity, VS Code, Windsurf, Claude Desktop).

Zero-Hallucination UI: Instead of guessing component names or fabricating CSS classes, your AI coding assistant queries your exact live component schemas, semantic token roles, and concentric radius formulas in real time.

1-Command Setup (Automated)

The quickest way to wire the MCP server, agent constitution, and IDE autocomplete into any Next.js or React app is running:

npx @shavin/ui init

This automatically installs the package, connects the Tailwind preset, imports global CSS, writes AGENTS.md, copies .agents/skills/, and creates .cursor/mcp.json.

Configuring Your IDE & AI Assistant

You can also connect shavin-mcp directly to your favorite AI development environment:

1. Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "shavin-mcp": {
      "command": "npx",
      "args": ["-y", "shavin-mcp"]
    }
  }
}

2. Claude Desktop (claude_desktop_config.json)

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%/Claude/claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "shavin-mcp": {
      "command": "npx",
      "args": ["-y", "shavin-mcp"]
    }
  }
}

3. Antigravity / Gemini CLI

// Run directly in terminal or add to mcp_config.json:
npx shavin-mcp

The 5 Built-in Agent Skills

In addition to MCP tools, @shavin/ui distributes 5 specialized cognitive skills in .agents/skills/ to eliminate "AI UI Slop" and enforce human-considered visual hierarchy:

shavin-appSkill

SaaS applications, analytics dashboards, AI chat consoles, data tables, and forms.

shavin-webpageSkill

Landing pages, bento showcases, hero sections, and marketing experiences.

visual-compositorSkill

Mathematical geometry, concentric radius math (R_inner = max(0, R_outer - P)), and density laws.

shavin-ui-qa-linterSkill

Automated design QA, token linting, accessibility audits, and verification pipelines.

shavin-ui-builderSkill

Isolated UI sandbox workflows for block composition and iterative user approval.

All 16 MCP Tools Reference

Once connected, AI agents seamlessly invoke these 16 tools during conversation, prompt analysis, and code synthesis:

1. Tokens, Components & Manifests

get_tokens

Retrieves tokens.json by category (foundation, semantic, radius, shadow, easing, presets) with contrast status.

get_components

Queries all 69 primitive component specifications, props, CVA variants, and Radix backing rationale.

get_builder_schema

Returns layout blocks (AppFrame, SidebarLayout) and component block schemas for the visual Studio builder.

get_block_template

Retrieves production-ready TSX block templates from community and enterprise registries by slug or category.

get_project_context

Extracts the live @shavin/ui design system manifest, active theme tokens, primitives, and layout rules for prompt context injection.

2. Quality Gate & Automated Linting

validate_code

Lints JSX code strings for hardcoded hex colors, raw --n-* foundation vars, and forbidden literal radii.

autofix_code

Automatically converts non-compliant code into token-compliant @shavin/ui JSX.

inspect_environment

Audits consumer project configuration (package.json, tailwind, CSS, next.config) with automated diff fixes.

shavin_steer

Executes AI design steering commands (audit, polish, harden, typeset, bolder, quieter) on a code snippet or component.

3. Guidelines & Setup Architecture

get_guidelines

Extracts two-tier token rules, CVA patterns, and concentric radius laws directly from AGENTS.md.

get_setup_instructions

Returns the 5-step setup instructions for Next.js 15, Vite, and standard React apps.

4. Multi-Agent Skills & Cognitive Design

list_skills

Lists all 5 specialized design system skills with section headings and trigger rules.

get_skill

Returns targeted instructions from specific skills (visual-compositor, shavin-app, shavin-webpage, etc.).

get_skill_mode

Determines activation mode (STRUCTURAL, MARKETING, EDITORIAL, HYBRID) for any user requirement.

install_skills

Programmatically scaffolds .agents/skills/ and AGENTS.md into the consumer repository.

synthesize_layout

Generates complete full-page React layouts composed from verified block schemas with token purity.