# MCP Component Review

An MCP (Model Context Protocol) server for reviewing React component changes. Analyzes structural differences, generates visual diffs, and validates implementations against Figma designs.

## Features

- **Structural Analysis**: Parse React components (TSX/JSX) and extract props, children, and styles
- **Style Detection**: Support for Tailwind CSS, styled-components, and CSS Modules
- **Visual Diff**: Screenshot components and generate pixel-level diff images
- **Figma Integration**: Extract design specs and validate implementation compliance
- **Branch Review**: Analyze all changed components in a git branch

## Installation

```bash
git clone https://github.com/yourusername/mcp-component-review.git
cd mcp-component-review
npm install
npm run build
```

## Usage

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "component-review": {
      "command": "node",
      "args": ["/path/to/mcp-component-review/dist/index.js"]
    }
  }
}
```

### With Claude Code

```bash
claude mcp add component-review node /path/to/mcp-component-review/dist/index.js
```

## Available Tools

### `analyze_component`

Analyze a single React component file.

```typescript
analyze_component({
  file: "/path/to/Button.tsx"
})
```

**Output:**
- Component name and props
- Component tree structure
- Extracted styles (colors, spacing, typography)

### `compare_components`

Compare two component files and get a structured diff.

```typescript
compare_components({
  oldFile: "/path/to/Button.old.tsx",
  newFile: "/path/to/Button.new.tsx"
})
```

**Output:**
- Text content changes
- Child component additions/removals
- Prop changes
- Style changes (colors, spacing, typography)

### `visual_diff_components`

Generate visual diff screenshots.

```typescript
visual_diff_components({
  oldFile: "/path/to/Button.old.tsx",
  newFile: "/path/to/Button.new.tsx",
  outputDir: "/path/to/output"
})
```

**Output:**
- Screenshots of old and new components
- Diff image highlighting changes
- Combined side-by-side view

### `get_figma_specs`

Extract design specifications from Figma.

```typescript
get_figma_specs({
  figmaUrl: "https://www.figma.com/file/ABC123/Design?node-id=1:2",
  figmaToken: "figd_xxxxx"
})
```

**Output:**
- Dimensions (width, height)
- Spacing (padding, margin, gap)
- Colors (background, text, border)
- Typography (font-size, font-weight, line-height)
- Border (radius, width)

### `validate_design_implementation`

Compare Figma specs with implementation.

```typescript
validate_design_implementation({
  figmaUrl: "https://www.figma.com/file/ABC123/Design?node-id=1:2",
  figmaToken: "figd_xxxxx",
  componentFile: "/path/to/Button.tsx",
  tolerance: 2
})
```

**Output:**
```markdown
# Design Validation Report: Button

## Summary ⚠️
- **Score**: 75%
- **Matches**: 6/8
- **Mismatches**: 2

## Validation Details

| Property      | Figma     | Implementation       | Status     |
|---------------|-----------|----------------------|------------|
| padding-top   | 8px       | 8px (p-2)            | ✅ match   |
| background    | #22C55E   | #16A34A (bg-green-600)| ❌ mismatch|
| font-size     | 16px      | 18px (text-lg)       | ❌ mismatch|
```

### `review_branch`

Review all changed components in a git branch.

```typescript
review_branch({
  repoPath: "/path/to/repo",
  baseBranch: "main",
  targetBranch: "feature/new-button",
  figmaToken: "figd_xxxxx",
  figmaFileKey: "ABC123",
  figmaMapping: {
    "src/components/Button.tsx": "1:234",
    "src/components/Card.tsx": "1:567"
  },
  outputDir: "/path/to/visual-diffs"
})
```

**Output:**
- Summary of all changed components
- Structural analysis for each component
- Visual diffs for modified components
- Figma validation scores

### `validate_and_fix`

Validate a component and get auto-fix instructions. If the component doesn't match Figma, returns exact Tailwind/CSS changes needed.

```typescript
validate_and_fix({
  figmaUrl: "https://www.figma.com/file/ABC123/Design?node-id=1:2",
  figmaToken: "figd_xxxxx",
  componentFile: "/path/to/Button.tsx"
})
```

**Output (when fixes needed):**
```markdown
🔧 **AUTO-FIX REQUIRED** for `src/Button.tsx`

Current design compliance: **62%**

## Required Changes

### 🔴 Missing (High Priority)
- **gap**: Add `gap-2`
  - Expected: `8px`

### 🟡 Mismatches (Medium Priority)
- **background**: Change to `bg-green-500`
  - Current: `bg-green-600`
  - Expected: `#22C55E`
- **font-size**: Change to `text-base`
  - Current: `text-lg`
  - Expected: `16px`

## Instructions

1. Open `src/Button.tsx`
2. Find the className or styled-components styles
3. Apply the following Tailwind class changes:

```
Add/Replace: gap-2 bg-green-500 text-base
```

4. Save the file
5. Run validation again to confirm compliance
```

This output is designed to be directly actionable by an AI agent to automatically fix the issues.

## Getting a Figma Token

1. Go to Figma → Settings → Account
2. Scroll to "Personal access tokens"
3. Click "Create new token"
4. Copy the token (starts with `figd_`)

## Example Workflow

### Design Review Automation

```typescript
// 1. Get the Figma specs for a component
const specs = await get_figma_specs({
  figmaUrl: "https://www.figma.com/file/ABC/Design?node-id=1:2",
  figmaToken: process.env.FIGMA_TOKEN
});

// 2. Validate the implementation
const validation = await validate_design_implementation({
  figmaUrl: "https://www.figma.com/file/ABC/Design?node-id=1:2",
  figmaToken: process.env.FIGMA_TOKEN,
  componentFile: "src/components/Button.tsx"
});

// 3. If there are visual changes, generate a diff
const visualDiff = await visual_diff_components({
  oldFile: "src/components/Button.old.tsx",
  newFile: "src/components/Button.tsx",
  outputDir: "./review-output"
});
```

### PR Review Automation

```typescript
// Review all components changed in a PR
const review = await review_branch({
  repoPath: ".",
  baseBranch: "main",
  targetBranch: "HEAD",
  figmaToken: process.env.FIGMA_TOKEN,
  figmaFileKey: "ABC123",
  figmaMapping: {
    "src/components/Button.tsx": "1:234"
  }
});
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev
```

## License

MIT

## Contributing

Contributions are welcome! Please read the contributing guidelines before submitting a PR.