# ui-optimizer-mcp

Production-focused, repository-first MCP server for AI-driven UI inspection and optimization reports.

## What it does

- Accepts a website URL and optional viewport presets
- Launches Chromium with Playwright
- Captures screenshots for each viewport
- Collects visible DOM/layout metadata
- Runs deterministic checks:
  - overflow indicators
  - missing image alt text
  - duplicate visible button labels
  - unlabeled inputs and unnamed buttons
  - browser console errors
- Produces a structured, prioritized report
- Produces a concise follow-up prompt for Claude Code

## MCP tools

### `scan_website_ui`
Scans one URL and returns report JSON.

Input:

```json
{
  "url": "https://example.com",
  "viewportPresets": [
    { "name": "desktop", "width": 1440, "height": 900 },
    { "name": "mobile", "width": 390, "height": 844 }
  ]
}
```

Output shape:

```json
{
  "url": "https://example.com",
  "generatedAt": "2026-01-01T00:00:00.000Z",
  "metadata": {
    "toolVersion": "0.1.0",
    "artifactDirectory": "/absolute/path/to/artifacts/2026-01-01T00-00-00.000Z",
    "viewportsScanned": ["desktop", "mobile"]
  },
  "summary": { "totalIssues": 3, "high": 1, "medium": 1, "low": 1 },
  "screenshots": [
    {
      "viewport": "desktop",
      "path": "/absolute/path/to/artifacts/2026-01-01T00-00-00.000Z/desktop.png"
    }
  ],
  "issues": [
    {
      "id": "desktop-1-unlabeled-input-1",
      "title": "Input without accessible label",
      "severity": "high",
      "affectedArea": "input.search",
      "recommendation": "Add a visible <label> and/or aria-label/aria-labelledby for form controls."
    }
  ],
  "nextPrompt": "Analyze and fix UI issues for https://example.com..."
}
```

### `generate_ui_fix_prompt`
Builds a concise fix prompt from a report object.

Input:

```json
{
  "report": {
    "url": "https://example.com",
    "summary": { "totalIssues": 3, "high": 1, "medium": 1, "low": 1 },
    "issues": []
  }
}
```

Output: multiline prompt string.

## Quick start (local)

1. Install dependencies:

```bash
npm install
```

2. Install browser runtime:

```bash
npx playwright install chromium
```

3. Build:

```bash
npm run build
```

4. Start MCP server (stdio transport):

```bash
npm start
```

## Runtime configuration

Optional environment variables:

- `UI_OPTIMIZER_OUTPUT_DIR` (default: `artifacts`)
- `UI_OPTIMIZER_TIMEOUT_MS` (default: `30000`)
- `UI_OPTIMIZER_MAX_VISIBLE_ELEMENTS` (default: `300`)
- `UI_OPTIMIZER_MAX_SIGNAL_ITEMS` (default: `40`)

Example:

```bash
UI_OPTIMIZER_OUTPUT_DIR=artifacts-prod UI_OPTIMIZER_TIMEOUT_MS=45000 npm start
```

## MCP client integration

Point your MCP client to the built server command:

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

## Validation commands

```bash
npm run lint
npm run build
npm run test
```