web-perception MCP Server

A Model Context Protocol (MCP) server for DOM-first, vision-second webpage analysis. Built for AI coding assistants like Cline.

What it does

This server gives AI agents the ability to understand webpages by combining structural DOM data with visual analysis via MiniMax vision. Instead of sending a raw screenshot to the vision model, it extracts the page's heading hierarchy, interactive elements, landmarks, and layout first — then sends both the screenshot and the structural context to MiniMax for significantly better analysis.

Tools

Prerequisites

• Node.js 18+

• A nanoGPT account with an API key

• An MCP-compatible client like Cline, Cursor, or Claude Desktop

Installation

git clone https://github.com/JaviGala/web-perception-mcp.git
cd web-perception-mcp
npm install
cp .env.example .env  # add your NANOGPT_API_KEY

Configuration

Set via .env file or environment variables:

MCP Client Configuration

Cline (VS Code)

{
	"mcpServers": {
		"web-perception": {
			"type": "stdio",
			"command": "/usr/local/bin/node",
			"timeout": 120,
			"args": ["/path/to/web-perception-mcp/src/server.js"],
			"env": {
				"NANOGPT_API_KEY": "sk-your-key-here"
			}
		}
	}
}

How analyze_page_visual works

This is the core differentiator — the "clever" analysis workflow:

1. Launch headless browser (Playwright + Chromium, no visible window)

2. Navigate to the target URL and wait for the page to load

3. Extract DOM structure — heading hierarchy, interactive elements with bounding boxes, landmarks, visible text

4. Take a screenshot (viewport or full page)

5. Build enriched prompt — combines DOM structure with the user's question into a structured prompt

6. Send to MiniMax — the vision model receives both the screenshot image AND the structural context

7. Parse response — extracts structured JSON findings with element refs, severity, confidence scores

This produces significantly better analysis than a raw screenshot alone because MiniMax can correlate visual elements with their DOM positions, roles, and content.

Architecture

src/
  server.js      — MCP server, tool definitions, request routing
  vision.js      — MiniMax API client, prompt builder, result parser
  browser.js     — Playwright browser pool management
  extraction.js  — DOM extraction (static + browser-rendered)
  security.js    — URL validation, logging, timeout utilities

Evolution

This project was built as a replacement for nanogpt-vision-mcp, which only supported raw image analysis without DOM context. The MiniMax client code was carried forward with no functional changes. See the nanogpt-vision-mcp README for the full migration story.

License

MIT