seo-audit-mcp

MCP-сервер, который даёт Claude (или любому MCP-клиенту) возможность аудировать техническое SEO живого веб-сайта: покрытие sitemap, проблемы на страницах и цепочки редиректов.

Спросите простым языком — «проверь mortgagecalculatortools.com и скажи, о каких страницах Google никогда не узнает» — и модель вызовет инструменты, обойдёт сайт и ответит с подробностями.

Проблема, которую это решает

sitemap.xml сайта — это способ сообщить Google, какие страницы существуют. Когда страница в нём отсутствует, не возникает ни ошибок, ни предупреждений — страница просто никогда не накапливает показы. Проверка вручную означает сравнение списка файлов в файловой системе с XML-файлом, поэтому на практике никто этого не делает.

Кейс: расхождение в 25 страниц, оказавшееся корректным

Первый сайт, на который это было направлено, имел 125 HTML-файлов на диске и 100 URL-адресов в своём sitemap. Расхождение в 25 страниц — это как раз та находка, которую оформляют как баг и назначают ответственному.

Один вызов sitemap_coverage выявил расхождение, а один вызов audit_urls на выборке объяснил его: каждая из 25 страниц содержала <meta name="robots" content="noindex, follow">. Это были два намеренно деиндексируемых контентных кластера, и sitemap был совершенно прав, опустив их. Затем проверили файловую систему: 25 noindex страниц на диске, те же 25 отсутствуют в sitemap, и ни одна noindex страница не была ошибочно включена. Идеальная согласованность.

Вот это и есть полезный результат. Одно только число покрытия («125 против 100») выглядит как дефект и стоит кому-то целого дня; покрытие плюс статус noindex по каждой странице закрывает вопрос за минуту. Этот инструмент настолько же ценен за ложные тревоги, которые он предотвращает, насколько и за реальные пробелы, которые он находит — именно поэтому audit_urls сообщает noindex по каждой странице, а не просто подсчитывает URL-адреса.

Инструменты

Каждый инструмент возвращает структурированный JSON со списком issues для каждой страницы и агрегированным issue_summary, чтобы модель могла рассуждать о количественных показателях, а не перечитывать сырой HTML.

Установка

pip install -e .

Требуется Python 3.10+. Зависимости: mcp>=2.0.0, httpx.

Подключение к Claude Code

Добавьте в .mcp.json в вашем проекте (или в ~/.claude.json для глобального использования):

{
  "mcpServers": {
    "seo-audit": {
      "command": "python",
      "args": ["-m", "seo_audit_mcp"]
    }
  }
}

Для Claude Desktop тот же блок помещается в claude_desktop_config.json.

Затем просто спросите:

Загрузите sitemap для https://example.com/sitemap.xml, проверьте первые 20 URL-адресов и обобщите проблемы по частоте.

Запуск напрямую

python -m seo_audit_mcp        # stdio transport

Заметки о проектировании

Три решения, о которых стоит сказать, потому что они отличают демо-версию от того, что можно показать на продакшен-сайте клиента:

Сканирование ограничено по скорости самой архитектурой. fetch_many работает за asyncio.Semaphore с пределом в 16 одновременных запросов, и каждый инструмент ограничивает свои входные данные. Sitemap на 500 URL-адресов без этого потолка открыл бы 500 сокетов одновременно и был бы воспринят как атака на целевой хост. Сканирование — это стоимость, которую платит целевой сайт, поэтому потолок нельзя увеличить на уровне инструментов.

Ни один сбой загрузки не прерывает выполнение. fetch_one перехватывает httpx.HTTPError и записывает её в возвращаемый PageAudit, а не выбрасывает исключение. Один недоступный хост при сканировании 200 URL-адресов ухудшает одну строку, а не приводит к потере 199 хороших результатов.

Разбор намеренно снисходительный. Реальный HTML достаточно часто бывает некорректным, так что строгий парсер, выбрасывающий исключение в середине сканирования, становится обузой. Экстракторы — это нестрогие регулярные выражения, которые возвращают None, а не выбрасывают ошибку, но с учётом ловушек: содержимое <script> и <style> удаляется перед подсчётом слов и извлечением заголовков, поэтому <h1> внутри строкового литерала JS не считается заголовком, а относительные canonical разрешаются относительно URL-адреса страницы.

normalize_url намеренно не удаляет завершающие слэши: /a и /a/ могут быть действительно разными страницами, и их схлопывание скрыло бы проблемы с дублирующимся контентом, для выявления которых и существует этот инструмент.

Тесты

pip install -e ".[dev]"
pytest

Набор тестов не использует сеть — HTTP тестируется через httpx.MockTransport, поэтому он работает в CI и в самолёте. Он покрывает крайние случаи разбора, которые доставляют проблемы в продакшене: заголовки, встроенные в скрипты, sitemap без пространства имён, относительные canonical, URL-адреса sitemap, возвращающие стилизованную HTML-ошибку 404 со статусом 200, а также ошибочное отнесение не-HTML типов контента к страницам «без заголовка».

Лицензия

MIT