Skip to main content
Glama
polatbakir

ui-optimizer-mcp

by polatbakir
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

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

Related MCP server: UI Analyzer MCP Server

MCP tools

scan_website_ui

Scans one URL and returns report JSON.

Input:

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

Output shape:

{
  "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:

{
  "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:

npm install

  1. Install browser runtime:

npx playwright install chromium

  1. Build:

npm run build

  1. Start MCP server (stdio transport):

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:

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:

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

Validation commands

npm run lint
npm run build
npm run test

Available Tools

2 tools
generate_ui_fix_promptB

Generate a concise Claude Code prompt summary from an existing optimization report.

ParametersJSON Schema
NameRequiredDescriptionDefault
reportYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states the core behavior of generating a prompt summary from a report, but it does not mention any side effects, output format, or limitations. This is adequate but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no filler. The key action and input are front-loaded, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complex nested input schema, no output schema, and no annotations, the description is too sparse to be complete. It does not explain what the generated prompt summary looks like, how the report components map to the output, or how this tool relates to scan_website_ui.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only refers to an 'existing optimization report' without explaining the meaning of url, summary, issues, or nested fields like severity and affectedArea. The agent is left to infer semantics from field names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action (generate a concise Claude Code prompt summary) and a clear input source (an existing optimization report). It does not explicitly contrast with the sibling tool scan_website_ui, but the word 'existing' helps distinguish it from a tool that creates the report.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is meant for use after an optimization report already exists, which gives some usage context. However, it does not explicitly state when to prefer this tool over scan_website_ui, nor does it mention any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scan_website_uiA

Open a URL with Playwright, capture screenshots and DOM metadata, run deterministic UI checks, and return a structured optimization report and follow-up prompt.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
viewportPresetsNo

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly mentions using Playwright to open the URL and captures screenshots/DOM metadata, which conveys that this is an active browser automation operation with potential side effects like network requests and page execution. It also names the output artifacts, though it does not warn about failure modes or resource intensity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, dense sentence that front-loads the core action ('Open a URL with Playwright') and lists the key steps and outputs. It is concise with no redundant wording, wasting no tokens.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description gives a high-level overview of the process and outputs but omits details about the viewportPresets parameter and the exact structure/format of the optimization report. With no output schema and no annotations, the description is adequate but not complete enough for an agent to fully anticipate the response shape or handle edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the parameter meaning. It only mentions 'Open a URL' and 'capture screenshots,' but never explains the viewportPresets parameter or how it relates to the scanning behavior. The parameter names are somewhat self-explanatory (url, viewportPresets), but the description adds no additional semantic detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with specific verbs and resources: opens a URL, captures screenshots and DOM metadata, runs deterministic UI checks, and returns a structured report. The combination of scanning and producing a follow-up prompt distinguishes it from the sibling generate_ui_fix_prompt, which likely only generates a fix prompt.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for analyzing a website's UI and getting optimization feedback, but it provides no explicit guidance on when to use this tool versus the sibling generate_ui_fix_prompt. The usage context is inferable but not directly stated, and no exclusions or alternative conditions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedgenerate_ui_fix_prompt
    • First observedscan_website_ui
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct inputs and purposes: one scans a live URL and produces a report, the other consumes an existing report to produce a prompt. There is no realistic overlap or ambiguity between them.

Naming Consistency5/5

Both tool names follow the same verb_noun pattern with snake_case convention: scan_website_ui and generate_ui_fix_prompt. Naming is perfectly consistent.

Tool Count3/5

With only two tools, the server feels quite thin for a 'ui-optimizer' domain. The tools support a narrow scan-and-prompt workflow, but the count is on the low end and could warrant a few more related operations.

Completeness4/5

The workflow of scanning a website and generating a fix prompt is functionally complete for the server's stated purpose. Minor gaps exist such as lacking a way to import external reports or apply fixes directly, but the core flow is not broken.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers