🎯 The Problem

AI coding assistants are incredibly powerful at writing and modifying code—but they're blind. When you ask an AI to "make the button bigger" or "change the theme to dark mode", it edits the code and hopes for the best. There's no way for the AI to actually see what changed.

💡 The Solution

WebSight gives AI agents vision. It's a set of visual analysis tools exposed via the Model Context Protocol (MCP), allowing AI agents to:

• 🔍 Analyze — Understand page structure, CSS variables, themes, and interactive elements
• 📸 Snapshot — Capture visual baselines before making changes
• 🎯 Compare — Verify changes with pixel-level diffing and percentage metrics

✨ Features

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/h34tsink/websight.git
cd websight

# Install dependencies
npm install

# Build the project
npm run build

# Auto-install to your AI tools
npm run install:mcp

💡 Tip: The installer automatically detects and configures Claude Desktop, Cursor, and VS Code!

Target Specific Tools

npm run install:claude   # Claude Desktop only
npm run install:cursor   # Cursor only
npm run install:vscode   # VS Code Copilot only
npm run install:all      # All detected tools

🔄 How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        AI AGENT WORKFLOW                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. LOOK          2. BASELINE         3. DIFF                  │
│   ┌─────────────┐  ┌─────────────┐     ┌─────────────┐          │
│   │ Analyze the │  │ Save visual │     │ Compare and │          │
│   │ current page│──│ snapshot    │────►│ verify      │          │
│   │ structure   │  │ before edit │     │ the changes │          │
│   └─────────────┘  └─────────────┘     └─────────────┘          │
│                                                                 │
│   "I see CSS vars,   "Baseline          "2.3% pixel             │
│    theme is dark,     saved!"            difference,            │
│    3 buttons..."                         change OK!"            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Example Conversation

You: "Use WebSight to change the primary color to red"

AI: Looking at page... I see --primary: #3b82f6 in the CSS variables. Let me save a baseline first.

[Makes code changes]

Comparing with baseline... Visual difference: 12.4%. The primary color has been updated across 3 buttons and the header accent.

📖 Usage

With AI Agents (Recommended)

Just tell your AI assistant:

"use websight to analyze this page"
"use websight to change the theme to dark mode"  
"use websight to verify my CSS changes worked"

The AI will automatically use the appropriate tools in sequence.

CLI Commands

npm run dev         # Start test page at localhost:5173
npm run look        # Analyze the current page
npm run baseline    # Save snapshot before changes
npm run diff        # Compare current state with baseline

📚 API Reference

MCP Tool Actions

Example Usage

websight(action="look")
websight(action="click", target="Submit")
websight(action="type", target="email", text="[email protected]")
websight(action="select", target="country", value="USA")

Programmatic API

import { analyze, saveBaseline, closeSession, click, type } from 'websight/session';

// Analyze any page
const { snapshot, report } = await analyze('http://localhost:3000');

// Interact
await click('Open Modal');
await type('email', '[email protected]');
await click('Submit');

console.log(analysis.snapshot.theme);        // { mode: 'dark', scheme: 'monochrome' }
console.log(analysis.snapshot.cssVars);      // { '--primary': '#3b82f6', ... }
console.log(analysis.snapshot.actions);      // [{ type: 'button', text: 'Submit', ... }]

// Save baseline before changes
await saveBaseline('http://localhost:3000', './out');

// Clean up
await closeBrowser();

🗂️ Project Structure

websight/
├── 📁 src/
│   ├── mcp-server.ts           # MCP server entry point
│   └── 📁 tools/
│       ├── api.ts              # Programmatic API
│       ├── types.ts            # TypeScript definitions
│       ├── detect.ts           # Dev server auto-detection
│       ├── compare.ts          # Pixel diffing logic
│       ├── report.ts           # Report generation
│       └── 📁 extractors/      # Page analysis modules
│           ├── theme.ts        # Theme & CSS variable extraction
│           ├── landmarks.ts    # Layout landmark detection
│           ├── sections.ts     # Content section analysis
│           ├── actions.ts      # Interactive element finder
│           └── overlays.ts     # Modal/overlay detection
├── 📁 scripts/
│   └── install.js              # Automated MCP installer
├── 📁 test-page/
│   └── index.html              # Development test page
├── 📁 dist/                    # Compiled output
└── 📁 out/                     # Generated analysis & snapshots

⚙️ Configuration

Automatic Setup (Recommended)

npm run install:mcp

This automatically detects and configures your AI tools.

Manual Configuration

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

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

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

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

claude mcp add websight node C:/path/to/websight/dist/src/mcp-server.js

🛠️ Development

npm run dev         # Start test page with hot reload
npm run mcp         # Run MCP server in dev mode
npm run build       # Build for production
npm run clean       # Remove generated files

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests

👤 Author

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.