Charlotte

La web, legible.

Tu agente de IA consume ~50.000 caracteres del árbol de accesibilidad solo para mirar la portada de Hacker News. Charlotte lo hace en 364.

Charlotte es un servidor MCP que ofrece a los agentes de IA un acceso estructurado y eficiente en tokens a la web. En lugar de volcar el árbol de accesibilidad completo en cada llamada, Charlotte devuelve solo lo que el agente necesita: un resumen compacto de la página al llegar, consultas específicas para elementos concretos y el detalle completo solo cuando se solicita explícitamente. En páginas con mucho contenido, esa orientación es hasta ~140x más pequeña que una instantánea completa del árbol de accesibilidad de Playwright MCP; en páginas trivialmente pequeñas, ambos tienen un tamaño aproximadamente similar.

¿Por qué Charlotte?

La mayoría de los servidores MCP de navegador vuelcan el árbol de accesibilidad completo en cada llamada: un bloque de texto plano que puede superar el millón de caracteres en páginas con mucho contenido. Los agentes pagan por todo ello, lo necesiten o no.

Charlotte descompone cada página en una representación estructurada y tipada: puntos de referencia, encabezados, elementos interactivos, formularios, resúmenes de contenido — y permite a los agentes controlar cuánto reciben con tres niveles de detalle. Cuando un agente navega a una nueva página, recibe una orientación compacta (364 caracteres para Hacker News) en lugar del volcado completo de elementos (~50.000 caracteres). Cuando necesita detalles, los pide.

Puntos de referencia

Medido en Charlotte v0.8.0 contra Playwright MCP v0.0.79, por caracteres devueltos por llamada de herramienta en sitios web reales (npx tsx benchmarks/run-benchmarks.ts --suite comparison), 2026-08-08. Esta sección es un resumen: la página canónica de puntos de referencia (incluido el coste por tarea y la deriva de versiones) está en charlotte.mintlify.site/benchmarks; metodología, instrumentos y resultados brutos: benchmarks/.

Coste de orientación (lo que paga un agente por "ver" una página al llegar):

Un navigate de Charlotte devuelve una orientación utilizable por defecto: puntos de referencia, encabezados y recuentos de elementos interactivos agrupados por región de la página. Para obtener lo equivalente con Playwright MCP, un agente llama a browser_snapshot, que devuelve el árbol de accesibilidad completo. (El browser_navigate de Playwright por sí solo devuelve solo una confirmación breve, no el contenido de la página, por lo que no es una comparación equivalente.)

La ventaja escala con la complejidad de la página: en páginas con mucho contenido, la orientación estructurada es ~10–140x más pequeña que la instantánea completa, mientras que en una página trivialmente pequeña como example.com ambas están dentro de ~20% la una de la otra (y en una página tan pequeña, la representación estructurada puede ser la más grande de las dos — simplemente no hay nada que resumir). El valor de Charlotte se muestra precisamente donde el volcado plano de Playwright duele más. Cuando un agente necesita más que la orientación, llama a observe o find para obtener exactamente la parte que quiere, en lugar de pagar por todo el árbol por adelantado.

Sobrecarga de definición de herramientas (coste invisible por llamada de API):

Las definiciones de herramientas se envían en cada ida y vuelta de API. Con el perfil browse por defecto, Charlotte lleva ~49% menos sobrecarga de definición que cargar las 43 herramientas; el perfil mínimo core la reduce en ~75%. Consulta el informe de puntos de referencia de perfiles para ver los resultados completos.

La diferencia en el flujo de trabajo: Un agente de Playwright que lee la instantánea completa recibe ~50.000 caracteres cada vez que mira Hacker News, ya sea leyendo titulares o buscando un botón de inicio de sesión. Un agente de Charlotte recibe 364 caracteres al llegar, llama a find({ type: "link", text: "login" }) para obtener exactamente lo que necesita y nunca paga por el resto.

Related MCP server: stealth-agent-browser-mcp

Cómo funciona

Charlotte mantiene una sesión persistente de Chromium sin interfaz gráfica y actúa como una capa de traducción entre la web visual y el razonamiento nativo de texto del agente. Cada página se descompone en una representación estructurada:

┌─────────────┐     MCP Protocol     ┌──────────────────┐
│   AI Agent  │<────────────────────>│    Charlotte     │
└─────────────┘                      │                  │
                                     │  ┌────────────┐  │
                                     │  │  Renderer  │  │
                                     │  │  Pipeline  │  │
                                     │  └─────┬──────┘  │
                                     │        │         │
                                     │  ┌─────▼──────┐  │
                                     │  │  Headless  │  │
                                     │  │  Chromium  │  │
                                     │  └────────────┘  │
                                     └──────────────────┘

Los agentes reciben puntos de referencia, encabezados, elementos interactivos con metadatos tipados, cuadros delimitadores, estructuras de formularios y resúmenes de contenido, todo derivado de lo que el navegador ya sabe sobre cada página.

Características

Navegación — navigate, back, forward, reload

Observación — observe (3 niveles de detalle, vista de árbol estructural), find (búsqueda espacial y semántica, modo selector CSS, output_file para conjuntos de resultados grandes), screenshot (con gestión persistente de artefactos), screenshots, screenshot_get, screenshot_delete, diff (comparación estructural contra instantáneas)

Interacción (consciente de iframes) — click, click_at (basado en coordenadas), type (con soporte de escritura lenta), select, toggle, submit, scroll, hover, drag, key (única/secuencia con selección de elemento), wait_for (sondeo de condiciones asíncronas), upload (entrada de archivos), fill_form (relleno de formularios por lotes), dialog (aceptar/descartar diálogos JS)

Monitorización — console (todos los niveles de gravedad, filtrado, marcas de tiempo), requests (historial HTTP completo, filtrado por método/estado/tipo de recurso)

Gestión de sesión — tabs, tab_open, tab_switch, tab_close, viewport (preajustes genéricos o dispositivos con nombre como "iPhone 15" con emulación de DPR, táctil y agente de usuario), network (limitación de ancho de banda, bloqueo de URL), set_cookies, get_cookies, clear_cookies, set_headers, configure

Modo de desarrollo — dev_serve (servidor estático + observación de archivos con recarga automática), dev_inject (inyección de CSS/JS), dev_audit (a11y, rendimiento, SEO, contraste, enlaces rotos)

Utilidades — evaluate (ejecución de JS arbitrario en el contexto de la página)

Perfiles de herramientas

Charlotte incluye 43 herramientas (42 registradas + la meta-herramienta charlotte_tools), pero la mayoría de los flujos de trabajo solo necesitan un subconjunto. Los perfiles de inicio controlan qué herramientas se cargan en el contexto del agente, reduciendo la sobrecarga de definición hasta en ~75%.

charlotte --profile browse    # 23 tools (default) — navigate, observe, interact, tabs
charlotte --profile core      # 7 tools — navigate, observe, find, click, type, submit
charlotte --profile full      # 43 tools — everything
charlotte --profile interact  # 31 tools — full interaction + dialog + evaluate
charlotte --profile develop   # 34 tools — interact + dev_serve, dev_inject, dev_audit
charlotte --profile audit     # 14 tools — navigation + observation + dev_audit + viewport

Los agentes pueden activar más herramientas a mitad de sesión sin reiniciar:

charlotte_tools enable dev_mode    → activates dev_serve, dev_audit, dev_inject
charlotte_tools disable dev_mode   → deactivates them
charlotte_tools list               → see what's loaded

Autoalojamiento (Charlotte Remoto)

Ejecuta Charlotte como un servidor MCP remoto y conéctalo a claude.ai — un solo comando:

docker run --cap-add SYS_ADMIN --shm-size 2g -p 3737:3737 ghcr.io/ticktockbent/charlotte

Imprime una URL de conector pública y un token de operador. En claude.ai: Configuración → Conectores → Añadir conector personalizado — pega la URL, deja los campos de ID de cliente OAuth/Secreto en blanco e introduce el token en la página de consentimiento de Charlotte cuando aparezca. Eso es todo; ya estás navegando.

La URL de demostración y el token son efímeros (ambos rotan al reiniciar). Para ejecutarlo de verdad — dominio estable, tu propio túnel o proxy inverso, docker compose: Autoalojamiento. Modelo de confianza y protecciones de red: Seguridad. Internals del contenedor y sandbox: Docker.

Inicio rápido

Requisitos previos

• Node.js >= 20

• npm

Instalación

Charlotte está listado en el Registro MCP como io.github.TickTockBent/charlotte y publicado en npm como @ticktockbent/charlotte:

npm install -g @ticktockbent/charlotte

Las imágenes de Docker están disponibles en Docker Hub y en GitHub Container Registry:

# Alpine (default, smaller)
docker pull ticktockbent/charlotte:alpine

# Debian (if you need glibc compatibility)
docker pull ticktockbent/charlotte:debian

# Or from GHCR
docker pull ghcr.io/ticktockbent/charlotte:latest

O instala desde el código fuente:

git clone https://github.com/ticktockbent/charlotte.git
cd charlotte
npm install
npm run build

Ejecutar

Charlotte se comunica a través de stdio usando el protocolo MCP:

# If installed globally (default browse profile)
charlotte

# With a specific profile
charlotte --profile core

# If installed from source
npm start

Configuración del cliente MCP

Claude Code

Crea .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "charlotte": {
      "type": "stdio",
      "command": "npx",
      "args": ["@ticktockbent/charlotte"],
      "env": {}
    }
  }
}

Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "charlotte": {
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

Cursor

Añade a .cursor/mcp.json:

{
  "mcpServers": {
    "charlotte": {
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

Windsurf

Añade a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "charlotte": {
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

VS Code (Copilot)

Añade a .vscode/mcp.json:

{
  "servers": {
    "charlotte": {
      "type": "stdio",
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

Cline

Añade a la configuración de MCP de Cline (a través de la barra lateral de Cline > Servidores MCP > Configurar):

{
  "mcpServers": {
    "charlotte": {
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

Amp

Añade a ~/.amp/settings.json:

{
  "mcpServers": {
    "charlotte": {
      "command": "npx",
      "args": ["@ticktockbent/charlotte"]
    }
  }
}

Consulta docs-internal/mcp-setup.md para la guía de configuración completa, incluido el modo de desarrollo, clientes MCP genéricos, pasos de verificación y solución de problemas.

Configuración

Charlotte resuelve la configuración de cuatro fuentes, con la precedencia más alta primero: argumentos de CLI → variables de entorno → archivo de configuración → valores predeterminados integrados. Consulta docs/configuration.md para la referencia completa.

Archivo de configuración

Pasa un archivo de configuración JSON con --config, o coloca un charlotte.config.json en el directorio de trabajo y Charlotte lo carga automáticamente:

charlotte --config charlotte.config.json

{
  "browser": { "headless": true, "noSandbox": false },
  "tools": { "profile": "browse" },
  "rendering": { "includeIframes": false, "iframeDepth": 3 },
  "output": { "dir": "./charlotte-output" },
  "limits": {
    "maxInteractiveElements": 2000,
    "maxFullContentChars": 200000,
    "maxResponseBytes": 1000000,
    "maxEvaluateBytes": 256000
  }
}

Cada sección es opcional; un {} vacío es válido. El archivo se valida con zod: claves desconocidas, tipos incorrectos o valores de enumeración no válidos producen un error de inicio claro en stderr y Charlotte sale con un código distinto de cero. Cuatro ajustes también tienen variables de entorno: CHARLOTTE_NO_SANDBOX, CHARLOTTE_OUTPUT_DIR, CHARLOTTE_CDP_ENDPOINT y CHARLOTTE_INIT_SCRIPT. Los scripts que deben ejecutarse en cada documento nuevo antes del JS de la página van en browser.initScripts o --init-script <ruta> (repetible); consulta Scripts de inicio.

El sandbox de Chromium está activado por defecto

Cambio de comportamiento en v0.7.0: Las versiones anteriores incluían --no-sandbox en cada lanzamiento de Chromium. A partir de v0.7.0, el sandbox de Chromium está habilitado por defecto — la principal defensa entre una página no confiable y la cuenta con la que se ejecuta Charlotte. Debes optar por desactivarlo explícitamente donde el sandbox del kernel no esté disponible.

charlotte --no-sandbox                  # CLI flag
CHARLOTTE_NO_SANDBOX=1 charlotte        # environment variable
# or "browser": { "noSandbox": true }   in the config file

Nota de migración (Docker / metal desnudo): Los contenedores normalmente no pueden configurar el sandbox del kernel, por lo que los Dockerfiles proporcionados establecen CHARLOTTE_NO_SANDBOX=1 por ti, y docker-compose.yml ahora mantiene el filtro seccomp predeterminado de Docker (ya no ejecuta seccomp=unconfined). Si ejecutas Charlotte en metal desnudo como root, Chromium se niega a iniciarse con el sandbox habilitado — ejecútalo como un usuario no root (recomendado) o pasa --no-sandbox. Las configuraciones existentes que antes dependían del --no-sandbox implícito y se ejecutan en un entorno donde el sandbox no puede inicializarse ahora deben establecer CHARLOTTE_NO_SANDBOX=1 (o el indicador/equivalente de configuración) para seguir funcionando.

Ejecutar Charlotte Remoto (modo HTTP) a través de la red plantea preguntas adicionales sobre límites de confianza y protecciones de red más allá del sandbox — consulta Seguridad.

Límites de tamaño de salida

Las claves limits.* limitan cuánto puede devolver una sola respuesta de herramienta para que una página patológica (100k enlaces, un feed de desplazamiento infinito, un cuerpo de documento gigante) no pueda desbordar la ventana de contexto del agente. Cuando una respuesta de página supera maxResponseBytes, se degrada a un resumen compacto y sugiere escribir el resultado completo en disco mediante output_file; los resultados de charlotte_evaluate se limitan de forma independiente con maxEvaluateBytes. Las respuestas truncadas llevan un marcador truncation. Consulta docs/configuration.md para las claves y los valores predeterminados.

Recuperación de fallos

Un fallo de Chromium ya no bloquea el servidor. La siguiente llamada a una herramienta relanza automáticamente el navegador, limpia la pestaña muerta y las cachés de sesión CDP, y abre una nueva pestaña en blanco — de modo que un agente puede seguir trabajando después de un fallo del renderizador sin reiniciar el servidor MCP.

Ejemplos de uso

Una vez conectado, un agente puede usar las herramientas de Charlotte:

Navegar por un sitio web

navigate({ url: "https://example.com" })
// → 612 chars: landmarks, headings, interactive element counts

find({ type: "link", text: "More information" })
// → just the matching element with its ID

click({ element_id: "lnk-a3f1c2" })

Rellenar un formulario

navigate({ url: "https://httpbin.org/forms/post" })
find({ type: "text_input" })
type({ element_id: "inp-c7e29b", text: "hello@example.com" })
select({ element_id: "sel-e8a3f5", value: "option-2" })
submit({ form_id: "frm-b1d4e7" })

Bucle de retroalimentación para desarrollo local

dev_serve({ path: "./my-site", watch: true })
observe({ detail: "full" })
dev_audit({ checks: ["a11y", "contrast"] })
dev_inject({ css: "body { font-size: 18px; }" })

Representación de la página

Charlotte devuelve representaciones estructuradas con tres niveles de detalle que permiten a los agentes controlar cuánto contexto consumen:

Mínimo (predeterminado para navigate)

Hitos (landmarks), encabezados y recuentos de elementos interactivos agrupados por región de la página. Diseñado para la orientación — «¿qué hay en esta página?» — sin enumerar cada elemento.

{
  "url": "https://news.ycombinator.com",
  "title": "Hacker News",
  "viewport": { "width": 1280, "height": 720 },
  "structure": {
    "headings": [{ "level": 1, "text": "Hacker News", "id": "hdg-a1b2c3" }]
  },
  "interactive_summary": {
    "total": 93,
    "by_landmark": {
      "(page root)": { "link": 91, "text_input": 1, "button": 1 }
    }
  }
}

Resumen (predeterminado para observe)

Lista completa de elementos interactivos con metadatos tipados, estructuras de formularios y resúmenes de contenido.

{
  "url": "https://example.com/dashboard",
  "title": "Dashboard",
  "viewport": { "width": 1280, "height": 720 },
  "structure": {
    "landmarks": [
      { "id": "rgn-b2c1d0", "role": "banner", "label": "Site header", "bounds": { "x": 0, "y": 0, "w": 1280, "h": 64 } },
      { "id": "rgn-d4e5f6", "role": "main", "label": "Content", "bounds": { "x": 240, "y": 64, "w": 1040, "h": 656 } }
    ],
    "headings": [{ "level": 1, "text": "Dashboard", "id": "hdg-1a2b3c" }],
    "content_summary": "main: 2 headings, 5 links, 1 form"
  },
  "interactive": [
    {
      "id": "btn-a3f1c2",
      "type": "button",
      "label": "Create Project",
      "bounds": { "x": 960, "y": 80, "w": 160, "h": 40 },
      "state": {}
    }
  ],
  "forms": []
}

Completo

Todo lo del resumen, más todo el contenido de texto visible en la página.

Niveles de detalle

Las herramientas de navegación usan minimal por defecto. La herramienta observe usa summary por defecto. Ambas aceptan un parámetro opcional detail para anularlo.

IDs de elementos

Los IDs de elementos son estables ante mutaciones menores del DOM. Se generan aplicando un hash a una clave compuesta por el tipo de elemento, el rol ARIA, el nombre accesible y la firma de la ruta DOM:

btn-a3f1c2  (button)    inp-c7e29b  (text input)
lnk-d4b910  (link)      sel-e8a3f5  (select)
chk-f1a204  (checkbox)  frm-b1d4e7  (form)
rgn-e0d2a8  (landmark)  hdg-0f4063  (heading)
dom-b2c3d9  (DOM element, from CSS selector queries)

Cambio de formato de ID en v0.7.0: los hashes de IDs de elementos ahora son de 6 caracteres hexadecimales (p. ej. btn-a3f1c2), frente a los 4 de versiones anteriores. Esto reduce drásticamente las colisiones de hash entre elementos en páginas grandes. Los agentes que hayan codificado o hecho coincidencia de patrones con IDs de 4 caracteres deberían volver a find los elementos en lugar de reutilizar IDs en caché tras la actualización.

Los IDs sobreviven a cambios no relacionados del DOM y a la reordenación de elementos dentro del mismo contenedor. Cuando un agente navega con detalle mínimo (sin IDs de elementos individuales), usa find para localizar elementos por texto, tipo o proximidad espacial; los elementos devueltos incluyen IDs listos para la interacción.

Desarrollo

# Run in watch mode
npm run dev

# Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run only integration tests
npm run test:integration

# Type check
npx tsc --noEmit

Estructura del proyecto

src/
  browser/          # Puppeteer lifecycle, tab management, CDP sessions
  renderer/         # Accessibility tree extraction, layout, content, element IDs
  state/            # Snapshot store, structural differ
  tools/            # MCP tool definitions (navigation, observation, interaction, session, dev-mode)
  dev/              # Static server, file watcher, auditor
  types/            # TypeScript interfaces
  utils/            # Logger, hash, wait utilities
tests/
  unit/             # Fast tests with mocks
  integration/      # Full Puppeteer tests against fixture HTML
  fixtures/pages/   # Test HTML files

Arquitectura

El Renderer Pipeline es el núcleo: llama a los extractores en orden y ensambla una PageRepresentation:

1. Extracción del árbol de accesibilidad (CDP Accessibility.getFullAXTree)

2. Extracción del diseño (CDP DOM.getBoxModel)

3. Extracción de hitos, encabezados, elementos interactivos y contenido

4. Generación de IDs de elementos (basada en hash, estable entre re-renderizados)

Todas las herramientas pasan por renderActivePage(), que gestiona instantáneas, eventos de recarga, detección de diálogos y el formato de las respuestas.

Sandbox

Charlotte incluye un sitio web de prueba en tests/sandbox/ que ejercita todas las herramientas sin tocar la internet pública. Sírvelo localmente con:

dev_serve({ path: "tests/sandbox" })

Cinco páginas cubren navegación, formularios, elementos interactivos, ventanas emergentes, contenido retardado, contenedores de desplazamiento y más. Consulta docs-internal/sandbox.md para la referencia completa de páginas y una lista de ejercicios herramienta por herramienta.

Problemas conocidos

Shadow DOM — El shadow DOM abierto funciona de forma transparente. El árbol de accesibilidad de Chromium atraviesa los límites del shadow DOM abierto, por lo que los componentes web (p. ej., <relative-time> y <tool-tip> de GitHub) renderizan su contenido en la representación de Charlotte sin tratamiento especial. Las raíces shadow cerradas son opacas para el árbol de accesibilidad y no se capturarán.

Hoja de ruta

Sesión y configuración

Hoja de ruta de funciones

Grabación de vídeo — Graba las interacciones como vídeo, capturando la secuencia completa de navegación y manipulación dirigida por el agente para depuración, documentación y revisión.

Consulta docs-internal/playwright-mcp-gap-analysis.md para el análisis completo de brechas frente a Playwright MCP, incluidos los elementos de menor prioridad (herramientas de visión, pruebas/verificación, trazado, transporte, seguridad) y las áreas donde Charlotte tiene ventajas.

Especificación completa

Consulta docs-internal/CHARLOTTE_SPEC.md para la especificación completa, incluidos todos los parámetros de las herramientas, el formato de representación de la página, la estrategia de identidad de los elementos y los detalles de arquitectura.

Licencia

MIT

Comunidad

• Abre un informe de error para defectos reproducibles, regresiones o problemas específicos de clientes MCP.

• Abre una solicitud de función para mejoras de flujo de trabajo o nuevas capacidades.

• Abre una solicitud de herramienta si quieres proponer una nueva herramienta, superficie de parámetros o ubicación de perfil.

• Explora los problemas abiertos para encontrar trabajo actual y discusiones.

• Consulta el filtro de buenos primeros problemas planificado, ya que los mantenedores etiquetan tareas aptas para principiantes.

Contribuciones

Consulta CONTRIBUTING.md para las directrices.

Parte de un conjunto creciente de servidores MCP con nombres literarios. Ver más en github.com/TickTockBent.