Visual MCP Server

Transform any React/Tailwind/shadcn codebase into a cohesive visual experience using AI-assisted design intelligence.

Version: 1.0.0 Contract: Visual MCP Contract v1

Overview

Visual MCP Server is a Model Context Protocol server that provides intelligent visual design tools. It analyzes codebases, extracts taste profiles from inspirations, proposes page plans, and generates file patches - all while respecting existing code and never touching business logic.

Quick Start

Prerequisites

• Node.js 18+
• npm or pnpm
• An MCP-compatible client (Claude Desktop, etc.)

Installation

# Clone the repository
git clone https://github.com/your-org/visual-mcp-server.git
cd visual-mcp-server

# Install dependencies
npm install

# Build the server
npm run build:mcp

Running Locally

# Start the MCP server (stdio transport)
node mcp/dist/server.js

Connecting to Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "visual-mcp": {
      "command": "node",
      "args": ["/path/to/visual-mcp-server/mcp/dist/server.js"]
    }
  }
}

Tools

1. analyze_repo_ui

Analyzes a repository to detect UI stack, framework, and configuration.

Input:

{
  "repoPath": "/absolute/path/to/repo"
}

Output: RepoMetadata object containing:

• Framework (React, Vue, Svelte)
• CSS solution (Tailwind, styled-components)
• Component library (shadcn, Radix, Chakra)
• Router type
• Build tool
• Design system presence

Example:

{
  "framework": "react",
  "cssFramework": "tailwind",
  "tailwindVersion": "3.4.11",
  "componentLibrary": "shadcn",
  "router": "react-router",
  "buildTool": "vite",
  "hasTypeScript": true,
  "hasDesignSystem": true,
  "designSystemPath": "src/design-system",
  "existingRoutes": ["/", "/dashboard", "/bookings"],
  "srcPath": "src"
}

2. derive_taste_from_inspirations

Extracts visual taste profile from inspiration sources.

Input:

{
  "inspirations": [
    { "type": "reference", "value": "linear", "weight": 1.0 },
    { "type": "reference", "value": "stripe", "weight": 0.5 },
    { "type": "url", "value": "https://example.com" },
    { "type": "screenshot", "value": "/path/to/screenshot.png" }
  ]
}

Known References:

• linear - Clean, abstract, minimal
• stripe - Polished, gradient-heavy
• vercel - Ultra-minimal, typography-focused
• notion - Warm, illustration-friendly
• figma - Playful, colorful
• apple - Premium, photography-driven
• github - Functional, content-focused
• airbnb - Warm, photography-driven
• chronicle - Abstract, dot-pattern, cool

Output: TasteProfile object:

{
  "abstraction": 0.7,
  "restraint": 0.8,
  "density": 0.4,
  "motion": 0.6,
  "motifPreference": ["gradients", "blur"],
  "typographyLooseness": 0.3,
  "colorTemperature": "cool",
  "surfaceComplexity": 0.5
}

3. propose_page_plan

Generates a visual plan for a target page/route.

Input:

{
  "repoMetadata": { /* from analyze_repo_ui */ },
  "tasteProfile": { /* from derive_taste_from_inspirations */ },
  "targetRoute": {
    "path": "/dashboard",
    "intent": "product",
    "audience": "hotel-owner"
  },
  "tuners": {
    "abstraction": 0.8,
    "density": 0.3,
    "motion": 0.6
  }
}

Output: Plan object with:

• Archetype selection (dashboard, landing, detail, wizard, etc.)
• Section structure
• Motif recommendations
• Signature block suggestions
• Applied tuners

4. generate_patch

Generates file modification instructions from a plan.

Input:

{
  "plan": { /* from propose_page_plan */ },
  "repoMetadata": { /* from analyze_repo_ui */ },
  "dryRun": false
}

Output: PatchInstructions with:

• Files to create (with full content)
• Files to modify (with search/replace)
• Files to delete
• Warnings

Important: This tool generates instructions only. It does NOT apply changes automatically.

5. verify_ui

Runs verification checks on the UI implementation.

Input:

{
  "repoPath": "/path/to/repo",
  "routes": ["/dashboard", "/bookings"],
  "updateBaselines": false
}

Output: VerificationChecklist with:

• ui:guard results (component guardrails)
• Visual regression results
• TypeScript compilation status
• Overall pass/fail status

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | DEBUG | Enable debug logging | false | | BASELINE_DIR | Visual baseline storage | design-system/visual-baselines |

Usage Examples

Full Workflow: Dashboard Redesign

// Step 1: Analyze the repo
const repoMetadata = await client.callTool('analyze_repo_ui', {
  repoPath: '/Users/me/my-project'
});

// Step 2: Derive taste from Linear + Stripe
const tasteProfile = await client.callTool('derive_taste_from_inspirations', {
  inspirations: [
    { type: 'reference', value: 'linear', weight: 1.0 },
    { type: 'reference', value: 'stripe', weight: 0.7 }
  ]
});

// Step 3: Propose a dashboard plan
const plan = await client.callTool('propose_page_plan', {
  repoMetadata,
  tasteProfile,
  targetRoute: {
    path: '/dashboard',
    intent: 'product',
    audience: 'hotel-owner'
  },
  tuners: {
    abstraction: 0.7,
    motion: 0.5
  }
});

// Step 4: Generate patches (review before applying!)
const patches = await client.callTool('generate_patch', {
  plan,
  repoMetadata,
  dryRun: false
});

// Step 5: Apply patches manually, then verify
const verification = await client.callTool('verify_ui', {
  repoPath: '/Users/me/my-project',
  routes: ['/dashboard']
});

Taste Blending

Blend multiple inspirations with weights:

const taste = await client.callTool('derive_taste_from_inspirations', {
  inspirations: [
    { type: 'reference', value: 'vercel', weight: 0.6 },  // 60% Vercel minimal
    { type: 'reference', value: 'airbnb', weight: 0.3 }, // 30% Airbnb warmth
    { type: 'reference', value: 'notion', weight: 0.1 }  // 10% Notion friendliness
  ]
});

Tuner Overrides

Fine-tune any plan with depth controls:

const plan = await client.callTool('propose_page_plan', {
  repoMetadata,
  tasteProfile,
  targetRoute: { path: '/landing', intent: 'marketing' },
  tuners: {
    abstraction: 0.9,  // Very abstract
    density: 0.2,      // Very spacious
    motion: 0.8,       // Lots of animation
    contrast: 0.7,     // High contrast
    narrative: 0.9     // Strong storytelling
  }
});

Contract Compliance

All outputs conform to Visual MCP Contract v1. See docs/visual-mcp-contract-v1.md for the full specification.

Non-Goals (What This Server Does NOT Do)

1. No business logic changes - Only visual/presentational code
2. No automatic file writes - Always returns instructions for human review
3. No breaking changes - Patches preserve existing functionality
4. No ML/heavy dependencies - Lightweight heuristics only

Development

Building

npm run build:mcp

Testing

npm run test:mcp

Adding New References

Edit the KNOWN_REFERENCES object in server.ts:

const KNOWN_REFERENCES: Record<string, TasteProfile> = {
  // Add your reference
  myapp: {
    abstraction: 0.5,
    restraint: 0.6,
    density: 0.5,
    motion: 0.4,
    motifPreference: ['lines', 'dots'],
    typographyLooseness: 0.4,
    colorTemperature: 'warm',
    surfaceComplexity: 0.5,
  },
};

Architecture

mcp/
├── server.ts          # MCP server with tool implementations
├── README.md          # This file
└── dist/              # Built output (after npm run build:mcp)

src/design-system/
├── mcp-contract.ts    # TypeScript types for contract
├── tuners.ts          # Recipe depth controls
├── inspiration-scanner.ts  # Taste extraction logic
└── theme/             # Theme pack implementation

docs/
└── visual-mcp-contract-v1.md  # Full contract specification

License

MIT

Credits

Built with the Model Context Protocol SDK.