markdown-for-agents-mcp

Сервер MCP (Model Context Protocol), который загружает URL с полноценным рендерингом JavaScript и преобразует их в чистый, эффективный с точки зрения токенов Markdown для ИИ-агентов.

Большинство инструментов для получения данных MCP используют обычный HTTP — они видят то, что отправляет сервер, не выполняя JavaScript. Это работает для статических сайтов, но молча возвращает пустой или некорректный контент для React, Vue, Angular, SPA и любых страниц, загружающих данные динамически. Этот сервер запускает настоящий браузер Chromium через Playwright, поэтому он отрисовывает всю страницу перед извлечением — тот же контент, который увидел бы пользователь.

Работает на базе Playwright и библиотеки markdown-for-agents. Удаляет рекламу, навигацию и шаблонный код, потребляя до 80% меньше токенов, чем исходный HTML.

Зачем нужен Playwright?

Пример сокращения токенов: типичная страница новостной статьи — это ~150 КБ исходного HTML (~40 000 токенов). После рендеринга в Playwright, очистки DOM и преобразования в Markdown та же статья занимает ~2 000 токенов — сокращение на 95%.

Содержание

• Зачем нужен Playwright?

• Возможности

• Установка

• Настройка MCP-клиента

• Доступные инструменты

  • fetch_url

  • fetch_urls

  • web_search

  • download_file

  • health_check

• Использование CLI

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

• Безопасность

• Архитектура

• Разработка

• Устранение неполадок

• Вклад в проект

• Журнал изменений

• Лицензия

Возможности

• Рендеринг JavaScript — Chromium под управлением Playwright отрисовывает React, Vue, Angular и любые страницы с активным JS перед извлечением.

• Структурированный вывод — Инструменты возвращают типизированный structuredContent (url, title, markdown, fetchedAt, contentSize) вместе с текстовым ответом, совместимый с MCP SDK 1.11+.

• Умное извлечение контента — Оценивает и выбирает основной блок контента (main > article > #content > body), автоматически отбрасывая боковые панели, навигацию и рекламу.

• Эффективность токенов — Создает компактный Markdown, готовый для LLM; тесты показывают до 80% меньше токенов, чем в исходном HTML.

• Веб-поиск — Поиск через DuckDuckGo с опциональной загрузкой и преобразованием топовых результатов.

• LRU-кэш — Кэш в оперативной памяти объемом 50 МБ с TTL 15 минут позволяет избежать повторных загрузок.

• Фильтрация доменов — Встроенный черный список трекеров/социальных сетей; поддерживает списки разрешенных/заблокированных доменов для каждого запроса и режим белого списка на уровне сервера.

• Пакетная загрузка — Параллельная загрузка нескольких URL с настраиваемой степенью параллелизма.

• Режим HTTP-сервера — Запуск в качестве HTTP-сервера (--http [port] или переменная окружения HTTP_PORT) с опциональной аутентификацией через bearer-токен.

• Поддержка прокси — Передайте PLAYWRIGHT_PROXY для маршрутизации трафика Playwright через прокси.

• Мониторинг состояния — Инструмент health_check предоставляет метрики кэша и загрузки.

• Нулевая конфигурация — Chromium устанавливается автоматически при первом запуске.

Установка

npm install -g markdown-for-agents-mcp

Chromium загружается автоматически через скрипт postinstall. Если это не удалось, см. Устранение неполадок.

Вы также можете запустить его без глобальной установки, используя npx:

npx markdown-for-agents-mcp

Настройка MCP-клиента

Добавьте сервер в конфигурацию вашего MCP-клиента.

Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "markdown": {
      "command": "markdown-mcp"
    }
  }
}

VS Code (Copilot / Continue)

Добавьте в рабочую область или пользовательский settings.json под соответствующим ключом расширения MCP, например:

{
  "mcpServers": {
    "markdown": {
      "command": "markdown-mcp"
    }
  }
}

Cursor / Windsurf / Zed

Любой клиент, реализующий спецификацию MCP, может использовать этот сервер. Точкой входа команды является markdown-mcp (доступно в PATH после глобальной установки) или полный путь к dist/index.js для локальных сборок.

С переопределением переменных окружения

{
  "mcpServers": {
    "markdown": {
      "command": "markdown-mcp",
      "env": {
        "FETCH_TIMEOUT_MS": "60000",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Режим HTTP-сервера

Вместо stdio вы можете запустить сервер как стандартную HTTP-конечную точку — это полезно для общих развертываний, Docker или любого клиента, который предпочитает транспорт Streamable HTTP:

# Start on port 3456
markdown-mcp --http 3456

# Or use the env var
HTTP_PORT=3456 markdown-mcp

Весь трафик MCP обрабатывается по адресу POST|GET|DELETE /mcp. Чтобы требовать bearer-токен, установите MCP_AUTH_TOKEN:

MCP_AUTH_TOKEN=mysecrettoken HTTP_PORT=3456 markdown-mcp

Клиенты должны передавать Authorization: Bearer mysecrettoken с каждым запросом.

Доступные инструменты

fetch_url

Загружает один URL с полноценным рендерингом JavaScript и возвращает чистый Markdown.

Аргументы:

Пример:

fetch_url(url="https://example.com/blog/post")

Текстовый вывод (всегда присутствует, обратно совместим):

# Blog Post Title

Source: https://example.com/blog/post

This is the main content of the article, stripped of navigation, ads, and boilerplate.

## Related Section

More content here...

---
*Converted by markdown-for-agents-mcp*

Структурированный вывод (доступен клиентам MCP SDK 1.11+ через structuredContent):

{
  "url": "https://example.com/blog/post",
  "title": "Blog Post Title",
  "markdown": "# Blog Post Title\n\nSource: ...",
  "fetchedAt": "2026-04-06T17:00:00.000Z",
  "contentSize": 2048
}

fetch_urls

Загружает несколько URL параллельно и возвращает объединенный Markdown, по одной секции на каждый URL.

Аргументы:

Пример:

fetch_urls(urls=[
  "https://example.com/post1",
  "https://example.com/post2"
])

Текстовый вывод:

# Post 1 Title

Source: https://example.com/post1

...

---

# Post 2 Title

Source: https://example.com/post2

...

---

Структурированный вывод (через structuredContent):

{
  "results": [
    {
      "url": "https://example.com/post1",
      "title": "Post 1 Title",
      "markdown": "...",
      "fetchedAt": "2026-04-06T17:00:00.000Z",
      "contentSize": 1820,
      "success": true
    },
    {
      "url": "https://example.com/post2",
      "title": "Post 2 Title",
      "markdown": "...",
      "fetchedAt": "2026-04-06T17:00:00.000Z",
      "contentSize": 2104,
      "success": true
    }
  ],
  "summary": { "total": 2, "succeeded": 2, "failed": 0 }
}

Параллелизм контролируется параметром MAX_CONCURRENT_FETCHES (по умолчанию: 5).

web_search

Ищет в DuckDuckGo и опционально загружает топовые результаты в виде Markdown. Использует обычную HTTP-конечную точку, чтобы избежать обнаружения ботов — Playwright для самого поиска не используется.

Аргументы:

Пример — только поиск:

web_search(
  query="typescript tutorials",
  maxResults=5,
  allowedDomains=["typescriptlang.org", "github.com"]
)

Пример — поиск и загрузка:

web_search(
  query="react hooks guide",
  fetchResults=true,
  maxResults=3
)

Текстовый вывод:

# Web Search Results

## Query: typescript tutorials
**Found 5 results in 1234ms**

### Results:

1. [TypeScript Handbook](https://www.typescriptlang.org/docs/)
   The TypeScript Handbook provides comprehensive documentation...

2. [Best TypeScript Tutorials](https://github.com/danistefanovic/build-your-own-typescript)
   Learn TypeScript by building your own compiler...

Структурированный вывод (через structuredContent):

{
  "query": "typescript tutorials",
  "results": [
    { "title": "TypeScript Handbook", "url": "https://www.typescriptlang.org/docs/", "snippet": "...", "domain": "typescriptlang.org" }
  ],
  "fetchedContent": [
    { "url": "https://www.typescriptlang.org/docs/", "markdown": "..." }
  ],
  "durationMs": 1234
}

Примечание: Аргументы allowedDomains и blockedDomains применяются только к фильтрации результатов поиска. Настройки сервера BLOCKLIST_DOMAINS / USE_ALLOWLIST_MODE по-прежнему применяются, когда эти результаты впоследствии загружаются.

download_file

Скачивает бинарный файл (PDF, изображение, ZIP и т.д.) по URL и сохраняет его по локальному пути. Использует обычный HTTP-клиент — Playwright не требуется. Применяется защита от SSRF и черный список доменов.

Аргументы:

Пример:

download_file(
  url="https://example.com/report.pdf",
  outputPath="/tmp/report.pdf"
)

Вывод:

{
  "savedPath": "/tmp/report.pdf",
  "sizeBytes": 204800,
  "mimeType": "application/pdf",
  "filename": "report.pdf"
}

Примечание: URL с путями вроде /download/... разрешены для этого инструмента, даже если они заблокированы в fetch_url (чтобы избежать цепочек скачивания бинарных файлов). Используйте fetch_url для HTML-страниц — download_file отклонит ответы text/html.

health_check

Возвращает текущий статус сервера, метрики кэша и статистику загрузок. Полезно для мониторинга и отладки.

Аргументы: нет

Пример вывода:

{
  "status": "healthy",
  "cache": {
    "hits": 47,
    "misses": 15,
    "currentSize": 12,
    "totalBytes": 4194304,
    "maxBytes": 52428800
  },
  "metrics": {
    "totalFetches": 62,
    "successCount": 59,
    "errorCount": 3,
    "avgDuration": 1840,
    "cacheUtilization": 76
  }
}

Использование CLI

Автономный CLI (markdown-cli) включен для использования вне протокола MCP.

Один URL

markdown-cli https://example.com

Несколько URL (пакетный режим)

markdown-cli -b https://example.com https://example.org https://example.net

Сохранение в файл

markdown-cli https://example.com/article > article.md

Скачивание бинарного файла

markdown-cli -d -o /tmp/report.pdf https://example.com/report.pdf

Справочник команд

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

Все настройки считываются из переменных окружения при запуске и проверяются с помощью Zod. Некорректные значения приводят к завершению работы с ненулевым кодом и описательной ошибкой.

Скопируйте .env.example в .env, чтобы начать:

cp .env.example .env

Справочник