npm package: @shokey/taste-engine-mcp
Description: Visual MCP Server - Transform any React/Tailwind/shadcn codebase into a cohesive visual experience using AI-assisted design intelligence
Author: Anthropic
Latest version: 1.0.0

# 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

```bash
# 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

```bash
# 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`):

```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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```typescript
// 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:

```typescript
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:

```typescript
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

```bash
npm run build:mcp
```

### Testing

```bash
npm run test:mcp
```

### Adding New References

Edit the `KNOWN_REFERENCES` object in `server.ts`:

```typescript
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](https://modelcontextprotocol.io/) SDK.