Visual Inspector MCP

Visual Inspector MCP

Servidor MCP para inspeccionar y editar HTML visualmente desde Claude Code, con comunicación bidireccional.

Arquitectura

┌─────────────────────────────────────────────────────────────┐
│  Claude Code                                                │
│  - Usa herramientas: inspect_html, get_selected_element...  │
└──────────────────────┬──────────────────────────────────────┘
                       │ MCP Protocol (stdio)
┌──────────────────────▼──────────────────────────────────────┐
│  visual-inspector-mcp (Node.js)                             │
│  - Servidor MCP (stdio)                                     │
│  - Servidor HTTP (puerto dinámico)                          │
│  - Servidor WebSocket (puerto dinámico)                     │
│  - File watcher para hot reload                             │
└──────────────────────┬──────────────────────────────────────┘
                       │ WebSocket
┌──────────────────────▼──────────────────────────────────────┐
│  Web App (Chrome en modo app)                               │
│  - Preview del HTML en iframe                               │
│  - Panel inspector con propiedades CSS                      │
│  - Click en elemento → enviado a Claude Code                │
└─────────────────────────────────────────────────────────────┘

Herramientas MCP

Ejemplos de uso

Usuario: "abre el inspector para mi presentación"
Claude: [usa inspect_html con file_path="presentacion.html"]

Usuario: "¿qué elemento tengo seleccionado?"
Claude: [usa get_selected_element]
→ Devuelve: { selector: "h1.titulo", tag: "h1", styles: {...} }

Usuario: "cambia el color a rojo"
Claude: [usa apply_css_change con selector="h1.titulo", property="color", value="red"]

Instalación

1. Compilar el proyecto

cd ~/Proyectos/Claude/desarrollos/mcp/visual-inspector-mcp
npm install
npm run build

2. Configurar MCP

El MCP ya está configurado en:

• ~/.mcp.json - Definición del servidor
• ~/.claude/settings.json - Habilitado en enabledMcpjsonServers

3. Reiniciar Claude Code

# Cerrar Claude Code actual y abrir de nuevo
claude

Nota importante de build

Si cambias web/index.html, recompila para mantener dist/ sincronizado:

npm run build

Si dist/web/index.html queda desactualizado, puede romperse la conexión WebSocket del visualizador.

Uso

Desde Claude Code

> abre sample.html en el inspector visual

[Claude usa inspect_html]
→ Se abre ventana de Chrome en modo app
→ Muestra el HTML con panel de inspector

> [seleccionas un elemento en la ventana]
> ¿qué tengo seleccionado?

[Claude usa get_selected_element]
→ "Tienes seleccionado el h1 con selector 'div.card > h1'"

> cambia el fondo a azul

[Claude usa apply_css_change]
→ El archivo se modifica y el preview se actualiza

Características de la Web App

• Tema oscuro por defecto (toggle en la esquina)
• Viewports: mobile / tablet / desktop
• Inspector: colores, dimensiones, tipografía, layout
• Color picker: click en el cuadro de color para abrir selector nativo
• Hot reload: cambios externos se reflejan automáticamente
• Indicador de conexión: punto verde = conectado

Estructura del proyecto

visual-inspector-mcp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts           # Entry point
│   ├── mcp-server.ts      # Herramientas MCP
│   ├── http-server.ts     # Servidor web (puerto dinámico)
│   ├── websocket.ts       # Comunicación bidireccional (puerto dinámico)
│   ├── file-watcher.ts    # Hot reload
│   └── css-editor.ts      # Edición de archivos CSS
├── web/
│   └── index.html         # Web app autocontenida
├── test/
│   └── sample.html        # HTML de prueba
└── dist/                  # Código compilado

Puertos utilizados

El servidor inyecta window.WS_PORT en la web app y el cliente debe usar:

const WS_PORT = window.WS_PORT || 7777;

Troubleshooting rápido

Error: No hay visualizador conectado. Usa inspect_html primero.

Checklist:

1. Reabrir visualizador con inspect_html.
2. Verificar que el HTML servido contiene window.WS_PORT:

- curl -s http://localhost: | rg "window.WS_PORT"

1. Verificar que el cliente usa window.WS_PORT || 7777 en web/index.html y dist/web/index.html.
2. Si cambiaste web/index.html, ejecutar npm run build.
3. Reiniciar Codex/cliente MCP si persiste.

Limitaciones conocidas

• Gradientes: Cambiar background-color no sobreescribe linear-gradient. Usar background directamente.
• Body/HTML: La selección del body puede ser difícil si tiene elementos hijos que cubren todo.
• CSS externo: Solo modifica CSS en ` o archivos .css` locales enlazados.

Desarrollo

# Compilar en modo watch
npm run dev

# Ejecutar manualmente (para pruebas)
node dist/index.js

Tecnologías

• Node.js + TypeScript
• @modelcontextprotocol/sdk
• ws (WebSocket)
• chokidar (file watcher)
• css-tree (parsing CSS)