视觉反馈服务器

┌─────────────────────────────────────────────────────────────┐
│                      Visual MCP Server                       │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────┐      ┌──────────────┐      ┌────────────┐ │
│  │   MCP       │──────│  Screenshot  │──────│  Puppeteer │ │
│  │  Protocol   │      │    Engine    │      │  (Web)     │ │
│  │   Layer     │      │              │      └────────────┘ │
│  └─────────────┘      │              │      ┌────────────┐ │
│        │              │              │──────│  ScreenKit │ │
│        │              └──────────────┘      │  (macOS)   │ │
│        ▼                                    └────────────┘ │
│  ┌─────────────┐      ┌──────────────┐                     │
│  │   Tool      │──────│  Comparison  │                     │
│  │  Handlers   │      │    Engine    │──────Pixelmatch    │
│  └─────────────┘      └──────────────┘                     │
│        │                                                    │
│        │              ┌──────────────┐                     │
│        │──────────────│  Monitoring  │──────Auto-Feedback │
│        │              │    System    │                     │
│        │              └──────────────┘                     │
│        ▼                                                    │
│  ┌─────────────┐      ┌──────────────┐                     │
│  │   Claude    │──────│  AI Feedback │──────Claude API    │
│  │    Code     │      │   Analyzer   │                     │
│  └─────────────┘      └──────────────┘                     │
│                                                              │
└──────────────────────────────────────────────────────────────┘

npm install -g @visualmcp/visual-mcp-server

{
  "mcpServers": {
    "visual-mcp": {
      "command": "visual-mcp"
    }
  }
}

{
  "mcpServers": {
    "visual-mcp": {
      "command": "visual-mcp",
      "env": {
        "VISUAL_MCP_OUTPUT_DIR": "$HOME/.visual-mcp/screenshots",
        "VISUAL_MCP_COMPARISONS_DIR": "$HOME/.visual-mcp/comparisons"
      }
    }
  }
}

{
  "mcpServers": {
    "visual-mcp": {
      "command": "npx",
      "args": ["-y", "@visualmcp/visual-mcp-server"]
    }
  }
}

# Clone the repository
git clone https://github.com/hfyeomans/VisualMCP.git
cd VisualMCP

# Install dependencies
npm install

# Build the project
npm run build

# Validate installation
npm run validate

{
  "mcpServers": {
    "visual-mcp": {
      "command": "visual-mcp"
    }
  }
}

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

{
  "name": "visual-mcp",
  "transport": {
    "type": "stdio",
    "command": "node",
    "args": ["dist/index.js"],
    "cwd": "/absolute/path/to/VisualMCP"
  }
}

VISUAL_MCP_OUTPUT_DIR=/Users/me/screenshots
VISUAL_MCP_TOLERANCE=3
VISUAL_MCP_LOG_LEVEL=debug

{
  type: 'url',
  url: string,              // Full URL to capture
  viewport?: {              // Optional custom viewport
    width: number,          // Viewport width in pixels
    height: number          // Viewport height in pixels
  }
}

{
  type: 'region',
  x: number,                // X coordinate from left
  y: number,                // Y coordinate from top
  width: number,            // Region width in pixels
  height: number            // Region height in pixels
}

{
  filepath: string,         // Absolute path to screenshot
  width: number,           // Image width in pixels
  height: number,          // Image height in pixels
  format: 'png' | 'jpeg',  // Image format
  size: number,            // File size in bytes
  timestamp: string,       // ISO timestamp
  target: object           // Original target specification
}

// Web page screenshot
{
  "target": {
    "type": "url",
    "url": "https://example.com",
    "viewport": { "width": 1920, "height": 1080 }
  },
  "options": {
    "format": "png",
    "fullPage": true
  }
}

// Desktop region (macOS 15+)
{
  "target": {
    "type": "region",
    "x": 0,
    "y": 0,
    "width": 1920,
    "height": 1080
  },
  "options": {
    "format": "jpeg",
    "quality": 85
  }
}

{
  x: number,      // Region X coordinate
  y: number,      // Region Y coordinate
  width: number,  // Region width
  height: number  // Region height
}

{
  differencePercentage: number,    // Total difference (0-100%)
  pixelsDifferent: number,         // Number of pixels changed
  totalPixels: number,             // Total pixels compared
  diffImagePath: string,           // Path to diff visualization
  isMatch: boolean,                // Within tolerance threshold
  regions: [                       // Detected difference regions
    {
      x: number,
      y: number,
      width: number,
      height: number,
      severity: 'low' | 'medium' | 'high'
    }
  ]
}

// Basic comparison
{
  "currentImage": "/screenshots/current.png",
  "referenceImage": "/designs/expected.png"
}

// With ignore regions (e.g., timestamps, dynamic content)
{
  "currentImage": "/screenshots/current.png",
  "referenceImage": "/designs/expected.png",
  "options": {
    "tolerance": 3,
    "ignoreRegions": [
      { "x": 10, "y": 10, "width": 200, "height": 50 },  // Ignore header timestamp
      { "x": 0, "y": 900, "width": 1920, "height": 80 }  // Ignore footer
    ]
  }
}

// Strict comparison
{
  "currentImage": "/screenshots/current.png",
  "referenceImage": "/designs/expected.png",
  "options": {
    "tolerance": 0.5,
    "threshold": 0.05
  }
}

{
  summary: string,              // Overall analysis summary
  issues: [                     // Detected issues
    {
      type: string,             // Issue category (layout, colors, etc.)
      severity: 'low' | 'medium' | 'high',
      description: string,      // What's wrong
      location: {               // Where the issue is
        x: number,
        y: number,
        width: number,
        height: number
      }
    }
  ],
  suggestions: [                // Actionable fixes
    {
      type: 'css' | 'general',
      title: string,            // Fix title
      description: string,      // Why this fix helps
      code?: string,            // CSS code (if type: 'css')
      priority: number          // Fix priority (1 = highest)
    }
  ],
  confidence: number            // Analysis confidence (0-100)
}

// Basic feedback
{
  "diffImagePath": "/comparisons/diff_12345.png"
}

// Focused analysis
{
  "diffImagePath": "/comparisons/diff_12345.png",
  "options": {
    "priority": ["layout", "spacing"],
    "context": "Button should be centered with 20px padding",
    "suggestionsType": "css"
  }
}

// General guidance only
{
  "diffImagePath": "/comparisons/diff_12345.png",
  "options": {
    "suggestionsType": "general",
    "context": "Landing page hero section"
  }
}

{
  sessionId: string,           // Monitoring session ID
  target: object,              // Target being monitored
  referenceImage: string,      // Baseline image path
  interval: number,            // Capture interval
  startedAt: string            // ISO timestamp
}

monitoring/{sessionId}/
  ├── session.json          # Session metadata
  ├── baseline.png          # Reference baseline
  └── captures/
      ├── capture_001.png   # Each capture
      ├── capture_002.png
      ├── diff_001.png      # Diff visualizations
      └── feedback_001.json # AI feedback (if enabled)

// Monitor localhost development
{
  "target": {
    "type": "url",
    "url": "http://localhost:3000"
  },
  "referenceImage": "/designs/final-design.png",
  "interval": 5,
  "autoFeedback": true
}

// Monitor desktop region
{
  "target": {
    "type": "region",
    "x": 100,
    "y": 100,
    "width": 1280,
    "height": 720
  },
  "referenceImage": "/baselines/window.png",
  "interval": 10,
  "autoFeedback": false
}

// Fast monitoring (1 second)
{
  "target": { "type": "url", "url": "http://localhost:8080" },
  "referenceImage": "/baseline.png",
  "interval": 1
}

{
  sessionId: string,           // Session ID
  target: object,              // Target that was monitored
  duration: number,            // Total monitoring duration (seconds)
  captureCount: number,        // Total captures taken
  changesDetected: number,     // Number of times changes exceeded tolerance
  finalStatus: string,         // 'matched' | 'different' | 'error'
  sessionDirectory: string,    // Path to session data
  captures: [                  // All captures taken
    {
      timestamp: string,
      filepath: string,
      differencePercentage: number
    }
  ],
  significantChanges: [        // Changes that exceeded tolerance
    {
      timestamp: string,
      differencePercentage: number,
      diffImagePath: string,
      feedback?: object        // AI feedback (if enabled)
    }
  ]
}

// Stop monitoring session
{
  "sessionId": "monitor_abc123"
}

// 1. Capture current implementation
const screenshot = await take_screenshot({
  target: { type: 'url', url: 'http://localhost:3000' },
  options: { filename: 'current.png' }
})

// 2. Compare with design
const comparison = await compare_visuals({
  currentImage: screenshot.filepath,
  referenceImage: '/designs/mockup.png',
  options: { tolerance: 3 }
})

// 3. Get actionable feedback
if (!comparison.isMatch) {
  const feedback = await analyze_ui_feedback({
    diffImagePath: comparison.diffImagePath,
    options: {
      priority: ['layout', 'spacing'],
      suggestionsType: 'css'
    }
  })

  // Apply CSS suggestions and repeat
}

// 1. Capture production-ready implementation
const screenshot = await take_screenshot({
  target: {
    type: 'url',
    url: 'https://staging.example.com',
    viewport: { width: 1920, height: 1080 }
  },
  options: { fullPage: true }
})

// 2. Strict comparison with approved design
const comparison = await compare_visuals({
  currentImage: screenshot.filepath,
  referenceImage: '/approved-designs/final.png',
  options: {
    tolerance: 1,  // Strict threshold
    ignoreRegions: [
      { x: 0, y: 0, width: 1920, height: 60 }  // Ignore nav bar
    ]
  }
})

// 3. Generate QA report
if (!comparison.isMatch) {
  const feedback = await analyze_ui_feedback({
    diffImagePath: comparison.diffImagePath,
    options: { suggestionsType: 'general' }
  })
}

// 1. Take baseline before changes
const baseline = await take_screenshot({
  target: { type: 'url', url: 'http://localhost:3000/dashboard' },
  options: { filename: 'baseline.png', fullPage: true }
})

// 2. ... make code changes ...

// 3. Capture after changes
const after = await take_screenshot({
  target: { type: 'url', url: 'http://localhost:3000/dashboard' },
  options: { filename: 'after-changes.png', fullPage: true }
})

// 4. Detect regressions
const comparison = await compare_visuals({
  currentImage: after.filepath,
  referenceImage: baseline.filepath,
  options: { tolerance: 2 }
})

// 5. Investigate unexpected changes
if (!comparison.isMatch) {
  const feedback = await analyze_ui_feedback({
    diffImagePath: comparison.diffImagePath
  })
}

// 1. Capture variant A
const variantA = await take_screenshot({
  target: { type: 'url', url: 'http://localhost:3000?variant=a' }
})

// 2. Capture variant B
const variantB = await take_screenshot({
  target: { type: 'url', url: 'http://localhost:3000?variant=b' }
})

// 3. Visual difference analysis
const comparison = await compare_visuals({
  currentImage: variantB.filepath,
  referenceImage: variantA.filepath,
  options: { tolerance: 0 }  // Detect all differences
})

// 4. Document differences
const feedback = await analyze_ui_feedback({
  diffImagePath: comparison.diffImagePath,
  options: {
    context: 'Comparing button placement variants',
    suggestionsType: 'general'
  }
})

// 1. Start monitoring
const session = await start_monitoring({
  target: { type: 'url', url: 'http://localhost:3000' },
  referenceImage: '/designs/final.png',
  interval: 5,
  autoFeedback: true
})

// 2. Develop application...
// Monitor automatically detects changes and provides feedback

// 3. Stop and review
const summary = await stop_monitoring({
  sessionId: session.sessionId
})

console.log(`Captured ${summary.captureCount} screenshots`)
console.log(`Detected ${summary.changesDetected} significant changes`)

# Unit tests
npm test

# Unit tests only (no e2e)
npm run test:unit

# Integration tests
npm run test:e2e

# Watch mode
npm run test:watch

# Interactive tool demonstration
npm run demo

# Smoke test all features
npm run test-runner

cd test-app
npm install
npm run dev

# macOS/Linux - Install Chrome dependencies
npm install puppeteer --force

# Linux - Install system dependencies
sudo apt-get install -y libx11-xcb1 libxcomposite1 libxcursor1

# Rebuild the server
npm run clean && npm run build

# Check MCP configuration
npm run validate

# Enable debug logging
DEBUG=visual-mcp:* npm start

# Environment variable
export DEBUG=visual-mcp:*
export VISUAL_MCP_LOG_LEVEL=debug

# Or in .env file
DEBUG=visual-mcp:*
VISUAL_MCP_LOG_LEVEL=debug

VisualMCP/
├── src/
│   ├── index.ts                   # MCP server entry
│   ├── core/                      # Core infrastructure
│   │   ├── config.ts              # Configuration management
│   │   ├── container.ts           # Dependency injection
│   │   ├── logger.ts              # Logging
│   │   └── errors.ts              # Error types
│   ├── handlers/                  # MCP tool handlers
│   │   ├── take-screenshot.ts     # Screenshot handler
│   │   ├── compare-visuals.ts     # Comparison handler
│   │   ├── analyze-feedback.ts    # Feedback handler
│   │   ├── start-monitoring.ts    # Start monitor handler
│   │   └── stop-monitoring.ts     # Stop monitor handler
│   ├── screenshot/                # Screenshot engine
│   │   ├── puppeteer.ts           # Web capture (Puppeteer)
│   │   ├── native-capture.ts      # Desktop capture (ScreenCaptureKit)
│   │   └── monitoring.ts          # Monitoring system
│   ├── comparison/                # Visual analysis
│   │   ├── differ.ts              # Image comparison (Pixelmatch)
│   │   └── analyzer.ts            # AI feedback analyzer
│   ├── interfaces/                # TypeScript interfaces
│   └── types/                     # Type definitions
├── bin/
│   └── screencapture-helper       # Swift helper binary (macOS)
├── docs/                          # Documentation
├── test-app/                      # Test application
├── cli-tools/                     # Testing tools
├── screenshots/                   # Screenshot output
├── comparisons/                   # Diff output
├── monitoring/                    # Monitoring sessions
└── dist/                          # Built JavaScript