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 system 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/cli init

This automatically installs the package, connects the Tailwind preset, imports global CSS, wraps your root layout in ThemeProvider, writes SHAVIN.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": {
      "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": {
      "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

Concentric radius system, geometric spacing, density laws, and layout rhythm.

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 19 MCP Tools Reference

Once connected, AI agents seamlessly invoke these 19 tools during conversation, prompt analysis, code synthesis, and real-time browser verification:

1. Tokens, Components & Manifests

get_tokens

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

get_components

Queries all 74 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 7-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.

5. Real-Time Browser Bridge & Live Inspection

shavin_get_live_audit

Retrieves live DOM token compliance, contrast math, and active violations directly from connected browser tabs.

shavin_trigger_rescan

Broadcasts an instant Server-Sent Events (SSE) rescan command across all open browser tabs to re-verify token purity.

shavin_wait_for_clean

Synchronously blocks until connected browser tabs report 0 token violations or timeout expires.

Agent-Browser Bridge Daemon (:7428)

The bridge is an HTTP/SSE background daemon that forms a real-time bi-directional pipeline between your AI editor and running browser tabs:

Fully Automated: The bridge boots automatically whenever an AI agent invokes shavin-mcp, and <ThemeProvider> automatically mounts the DOM scanner in development to stream snapshots without manual wiring.

Running Standalone Bridge & Monitor Dashboard:

# Start standalone bridge monitor via CLI
npx @shavin/cli bridge

# Or via npm script
npm run bridge

# Or directly from @shavin/mcp
npx @shavin/mcp --bridge

Visit http://localhost:7428/ to open the live visual inspection dashboard displaying connected tabs, active DOM violations, and real-time event logs.

AI → Studio Real-Time Bridge

In addition to the 19 development tools above, the MCP server now includes 7 Studio Relay tools that let your AI agent connect to a live Studio canvas and compose designs in real-time. This works across three connection modes: local bridge, remote HTTP, and browser pairing codes.

New: The AI can now compose directly on your Studio canvas — no code generation required. See the full guide at AI → Studio Bridge.