Charlotte

Веб, доступный для чтения.

Ваш ИИ-агент тратит ~50 000 символов дерева доступности только для того, чтобы посмотреть на главную страницу Hacker News. Charlotte делает это за 364.

Charlotte — это MCP-сервер, который предоставляет ИИ-агентам структурированный, эффективный по токенам доступ к веб-страницам. Вместо того чтобы выгружать полное дерево доступности при каждом вызове, Charlotte возвращает только то, что нужно агенту: компактную сводку страницы при переходе, целевые запросы для конкретных элементов и полные детали только по явному запросу. На страницах с большим количеством контента такая ориентация примерно в ~140 раз меньше, чем полный снимок дерева доступности от Playwright MCP; на тривиально маленьких страницах оба варианта примерно одинакового размера.

Почему Charlotte?

Большинство браузерных MCP-серверов выгружают всё дерево доступности при каждом вызове — плоский текстовый блок, который на страницах с большим количеством контента может превышать миллион символов. Агенты платят за всё это, даже если им это не нужно.

Charlotte разбивает каждую страницу на типизированное, структурированное представление — ориентиры, заголовки, интерактивные элементы, формы, сводки контента — и позволяет агентам контролировать, сколько они получают, с помощью трёх уровней детализации. Когда агент переходит на новую страницу, он получает компактную ориентацию (364 символа для Hacker News) вместо полного дампа элементов (~50 000 символов). Когда ему нужны конкретные детали, он запрашивает их.

Бенчмарки

Измерено на Charlotte v0.8.0 против Playwright MCP v0.0.79, по количеству символов, возвращаемых за вызов инструмента на реальных сайтах (npx tsx benchmarks/run-benchmarks.ts --suite comparison), 2026-08-08. Этот раздел — сводка; каноническая страница бенчмарков (включая стоимость каждой задачи и дрейф релизов) находится на charlotte.mintlify.site/benchmarks; методология, инструменты и необработанные результаты: benchmarks/.

Стоимость ориентации (что платит агент, чтобы «увидеть» страницу при переходе):

По умолчанию navigate в Charlotte возвращает полезную ориентацию — ориентиры, заголовки и количество интерактивных элементов, сгруппированных по областям страницы. Чтобы получить эквивалент с Playwright MCP, агенту нужно вызвать browser_snapshot, который возвращает полное дерево доступности. (Один browser_navigate в Playwright возвращает только короткое подтверждение, а не содержимое страницы, поэтому это не сопоставимое сравнение.)

Преимущество растёт со сложностью страницы: на страницах с большим количеством контента структурированная ориентация в ~10–140 раз меньше, чем полный снимок, а на тривиально маленькой странице, такой как example.com, оба варианта находятся в пределах ~20% друг от друга (и на такой маленькой странице структурированное представление может быть даже больше — просто нечего сжимать). Ценность Charlotte проявляется именно там, где плоский дамп Playwright причиняет больше всего вреда. Когда агенту нужно больше, чем ориентация, он вызывает observe или find для нужной части, вместо того чтобы платить за всё дерево заранее.

Накладные расходы на определения инструментов (невидимая стоимость каждого вызова API):

Определения инструментов отправляются при каждом круговом обращении API. С профилем по умолчанию browse Charlotte несёт на ~49% меньше накладных расходов на определения, чем при загрузке всех 43 инструментов; минимальный профиль core сокращает их на ~75%. Полные результаты см. в отчёте о бенчмарке профилей.

Разница в рабочем процессе: агент Playwright, читающий полный снимок, получает ~50 000 символов каждый раз, когда смотрит на Hacker News, независимо от того, читает ли он заголовки или ищет кнопку входа. Агент Charlotte получает 364 символа при переходе, вызывает find({ type: "link", text: "login" }), чтобы получить именно то, что нужно, и никогда не платит за остальное.

Related MCP server: stealth-agent-browser-mcp

Как это работает

Charlotte поддерживает постоянную сессию headless Chromium и действует как слой перевода между визуальным вебом и текстовым мышлением агента. Каждая страница разбивается на структурированное представление:

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

Агенты получают ориентиры, заголовки, интерактивные элементы с типизированными метаданными, ограничивающие рамки, структуры форм и сводки контента — всё это извлекается из того, что браузер уже знает о каждой странице.

Возможности

Навигация — navigate, back, forward, reload

Наблюдение — observe (3 уровня детализации, структурное дерево), find (пространственный + семантический поиск, режим CSS-селекторов, output_file для больших наборов результатов), screenshot (с постоянным управлением артефактами), screenshots, screenshot_get, screenshot_delete, diff (структурное сравнение со снимками)

Взаимодействие (с учётом iframe) — click, click_at (по координатам), type (с поддержкой медленного ввода), select, toggle, submit, scroll, hover, drag, key (одиночный/последовательность с нацеливанием на элемент), wait_for (асинхронный опрос условий), upload (ввод файла), fill_form (пакетное заполнение форм), dialog (принять/отклонить JS-диалоги)

Мониторинг — console (все уровни серьёзности, фильтрация, временные метки), requests (полная история HTTP, фильтрация по методу/статусу/типу ресурса)

Управление сессией — tabs, tab_open, tab_switch, tab_close, viewport (универсальные пресеты или именованные устройства, такие как «iPhone 15», с эмуляцией DPR, сенсорного ввода и user agent), network (троттлинг, блокировка URL), set_cookies, get_cookies, clear_cookies, set_headers, configure

Режим разработки — dev_serve (статический сервер + отслеживание файлов с автоперезагрузкой), dev_inject (инъекция CSS/JS), dev_audit (a11y, производительность, SEO, контраст, битые ссылки)

Утилиты — evaluate (произвольное выполнение JS в контексте страницы)

Профили инструментов

Charlotte поставляется с 43 инструментами (42 зарегистрированных + мета-инструмент charlotte_tools), но большинству рабочих процессов нужна только часть. Профили запуска определяют, какие инструменты загружаются в контекст агента, снижая накладные расходы на определения до ~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

Агенты могут активировать больше инструментов в середине сессии без перезапуска:

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

Самостоятельный хостинг (Charlotte Remote)

Запустите Charlotte как удалённый MCP-сервер и подключите его к claude.ai — одна команда:

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

Он выводит публичный URL коннектора и операторский токен. В claude.ai: Настройки → Коннекторы → Добавить пользовательский коннектор — вставьте URL, оставьте поля OAuth Client ID/Secret пустыми и введите токен на странице согласия Charlotte, когда она появится. Всё, вы в браузере.

Демо-URL и токен эфемерны (оба меняются при перезапуске). Для реального использования — стабильный домен, собственный туннель или обратный прокси, docker compose: Самостоятельный хостинг. Модель доверия и сетевые защиты: Безопасность. Внутренности контейнера и песочницы: Docker.

Быстрый старт

Предварительные требования

• Node.js >= 20

• npm

Установка

Charlotte указан в MCP Registry как io.github.TickTockBent/charlotte и опубликован на npm как @ticktockbent/charlotte:

npm install -g @ticktockbent/charlotte

Docker-образы доступны на Docker Hub и 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

Или установите из исходников:

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

Запуск

Charlotte общается через stdio по протоколу MCP:

# If installed globally (default browse profile)
charlotte

# With a specific profile
charlotte --profile core

# If installed from source
npm start

Конфигурация MCP-клиента

Claude Code

Создайте .mcp.json в корне проекта:

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

Claude Desktop

Добавьте в claude_desktop_config.json:

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

Cursor

Добавьте в .cursor/mcp.json:

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

Windsurf

Добавьте в ~/.codeium/windsurf/mcp_config.json:

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

VS Code (Copilot)

Добавьте в .vscode/mcp.json:

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

Cline

Добавьте в настройки MCP Cline (через боковую панель Cline > MCP Servers > Configure):

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

Amp

Добавьте в ~/.amp/settings.json:

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

Полное руководство по настройке, включая режим разработки, универсальные MCP-клиенты, шаги проверки и устранение неполадок, см. в docs-internal/mcp-setup.md.

Конфигурация

Charlotte разрешает настройки из четырёх источников, в порядке убывания приоритета: аргументы CLI → переменные окружения → файл конфигурации → встроенные значения по умолчанию. Полный справочник см. в docs/configuration.md.

Файл конфигурации

Передайте JSON-файл конфигурации с помощью --config или поместите charlotte.config.json в рабочую директорию, и Charlotte загрузит его автоматически:

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
  }
}

Каждый раздел необязателен; пустой {} допустим. Файл проверяется с помощью zod — неизвестные ключи, неверные типы или недопустимые значения перечислений приводят к понятной ошибке запуска в stderr, и Charlotte завершает работу с ненулевым кодом. Четыре настройки также имеют переменные окружения: CHARLOTTE_NO_SANDBOX, CHARLOTTE_OUTPUT_DIR, CHARLOTTE_CDP_ENDPOINT и CHARLOTTE_INIT_SCRIPT. Скрипты, которые должны выполняться на каждом новом документе до JS страницы, помещаются в browser.initScripts или --init-script <path> (повторяемый); см. Init scripts.

Песочница Chromium включена по умолчанию

Изменение поведения в v0.7.0: В более ранних версиях --no-sandbox встраивался в каждый запуск Chromium. Начиная с v0.7.0 песочница Chromium включена по умолчанию — основная защита между ненадёжной страницей и учётной записью, под которой работает Charlotte. Вы должны явно отказаться от неё там, где песочница ядра недоступна.

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

Примечание по миграции (Docker / bare-metal): Контейнеры обычно не могут настроить песочницу ядра, поэтому предоставленные Dockerfile устанавливают CHARLOTTE_NO_SANDBOX=1 за вас, а docker-compose.yml теперь сохраняет фильтр seccomp Docker по умолчанию (он больше не запускается с seccomp=unconfined). Если вы запускаете Charlotte bare-metal от root, Chromium отказывается запускаться с включённой песочницей — запускайте от непривилегированного пользователя (рекомендуется) или передайте --no-sandbox. Существующие настройки, которые ранее полагались на неявный --no-sandbox и работают в среде, где песочница не может инициализироваться, теперь должны установить CHARLOTTE_NO_SANDBOX=1 (или эквивалент флага/конфигурации), чтобы продолжать работать.

Запуск Charlotte Remote (HTTP-режим) по сети поднимает дополнительные вопросы доверительной границы и сетевых защит, помимо песочницы — см. Безопасность.

Ограничения размера вывода

Ключи limits.* ограничивают, сколько может вернуть один ответ инструмента, чтобы патологическая страница (100k ссылок, бесконечная лента, огромное тело документа) не могла переполнить контекстное окно агента. Когда ответ страницы превышает maxResponseBytes, он деградирует до компактной сводки и предлагает записать полный результат на диск через output_file; результаты charlotte_evaluate ограничиваются отдельно через maxEvaluateBytes. Усечённые ответы содержат маркер truncation. Ключи и значения по умолчанию см. в docs/configuration.md.

Восстановление после сбоя

Сбой Chromium больше не блокирует сервер. Следующий вызов инструмента автоматически перезапускает браузер, очищает кэши мёртвой вкладки и CDP-сессии и открывает новую пустую вкладку — так что агент может продолжать работу после сбоя рендерера без перезапуска MCP-сервера.

Примеры использования

После подключения агент может использовать инструменты Charlotte:

Просмотр веб-сайта

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" })

Заполнение формы

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" })

Цикл обратной связи при локальной разработке

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

Представление страницы

Charlotte возвращает структурированные представления с тремя уровнями детализации, которые позволяют агентам контролировать, сколько контекста они потребляют:

Минимальный (по умолчанию для navigate)

Ориентиры, заголовки и количество интерактивных элементов, сгруппированные по областям страницы. Предназначен для ориентации — «что на этой странице?» — без перечисления каждого элемента.

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

Сводка (по умолчанию для observe)

Полный список интерактивных элементов с типизированными метаданными, структурами форм и сводками содержимого.

{
  "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": []
}

Полный

Всё, что в сводке, плюс весь видимый текстовый контент на странице.

Уровни детализации

Инструменты навигации по умолчанию используют minimal. Инструмент observe по умолчанию использует summary. Оба принимают необязательный параметр detail для переопределения.

Идентификаторы элементов

Идентификаторы элементов стабильны при незначительных мутациях DOM. Они генерируются хешированием составного ключа из типа элемента, ARIA-роли, доступного имени и сигнатуры пути 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)

Изменение формата ID в v0.7.0: хеши идентификаторов элементов теперь состоят из 6 шестнадцатеричных символов (например, btn-a3f1c2), вместо 4 в предыдущих версиях. Это значительно снижает коллизии хешей между элементами на больших страницах. Агенты, которые жёстко закодировали или сопоставляли по шаблону 4-символьные ID, должны заново выполнять find для элементов, а не переиспользовать кэшированные ID после обновления.

ID переживают несвязанные изменения DOM и переупорядочивание элементов в пределах одного контейнера. Когда агент работает на минимальном уровне детализации (без отдельных ID элементов), он использует find для поиска элементов по тексту, типу или пространственной близости — возвращаемые элементы включают ID, готовые к взаимодействию.

Разработка

# 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

Структура проекта

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

Архитектура

Конвейер рендеринга — это ядро: он вызывает экстракторы по порядку и собирает PageRepresentation:

1. Извлечение дерева доступности (CDP Accessibility.getFullAXTree)

2. Извлечение макета (CDP DOM.getBoxModel)

3. Извлечение ориентиров, заголовков, интерактивных элементов и содержимого

4. Генерация ID элементов (на основе хеша, стабильна при повторных рендерах)

Все инструменты проходят через renderActivePage(), который обрабатывает снимки, события перезагрузки, обнаружение диалогов и форматирование ответов.

Песочница

Charlotte включает тестовый веб-сайт в tests/sandbox/, который задействует все инструменты без обращения к публичному интернету. Запустите его локально с помощью:

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

Пять страниц охватывают навигацию, формы, интерактивные элементы, всплывающие окна, отложенный контент, контейнеры прокрутки и многое другое. См. docs-internal/sandbox.md для полного справочника страниц и пошагового чек-листа упражнений для каждого инструмента.

Известные проблемы

Shadow DOM — Открытый shadow DOM работает прозрачно. Дерево доступности Chromium проникает через границы открытого shadow DOM, поэтому веб-компоненты (например, <relative-time>, <tool-tip> от GitHub) отображают своё содержимое в представлении Charlotte без специальной обработки. Закрытые shadow-корни непрозрачны для дерева доступности и не будут захвачены.

Дорожная карта

Сессия и конфигурация

Дорожная карта функций

Видеозапись — Запись взаимодействий в видео, захватывающая полную последовательность навигации и манипуляций, выполняемых агентом, для отладки, документации и рецензирования.

См. docs-internal/playwright-mcp-gap-analysis.md для полного анализа пробелов относительно Playwright MCP, включая пункты с более низким приоритетом (инструменты зрения, тестирование/проверка, трассировка, транспорт, безопасность) и области, где Charlotte имеет преимущества.

Полная спецификация

См. docs-internal/CHARLOTTE_SPEC.md для полной спецификации, включая все параметры инструментов, формат представления страницы, стратегию идентификации элементов и детали архитектуры.

Лицензия

MIT

Сообщество

• Откройте отчёт об ошибке для воспроизводимых дефектов, регрессий или проблем, специфичных для MCP-клиентов.

• Откройте запрос функции для улучшений рабочего процесса или новых возможностей.

• Откройте запрос инструмента, если хотите предложить новый инструмент, поверхность параметров или размещение профиля.

• Просмотрите открытые вопросы, чтобы найти текущую работу и обсуждения.

• Проверьте запланированный фильтр good first issue, так как сопровождающие помечают задачи, подходящие для новичков.

Внесение вклада

См. CONTRIBUTING.md для получения рекомендаций.

Часть растущего набора MCP-серверов с литературными названиями. Подробнее на github.com/TickTockBent.