# common-crawl-mcp

MCP-сервер и CLI для запросов к [Common Crawl](https://commoncrawl.org/) — открытому
корпусу веба, на котором учат языковые модели.

Отвечает на вопрос «виден ли сайт для ИИ»: сколько его страниц попало в корпус, какие
разделы, как это менялось, и что видит модель, читая конкретную страницу.

Работает через AWS Athena поверх колоночного индекса (`cc-index`), а не через публичный
API Common Crawl — тот регулярно отдаёт 504. Запрос по домену стоит около `$0.00005`.

## Установка

```bash
uv tool install git+https://github.com/nikolaymokh-dev/common-crawl-mcp
```

Нужны AWS-креды с доступом к Athena, Glue и чтением бакета `commoncrawl`. Берутся
из `~/.aws` обычным способом (`AWS_PROFILE`, `AWS_REGION`; по умолчанию `us-east-1`).

## CLI

```bash
ccq example.com                          # страниц в свежем кравле
ccq example.com --dynamics               # динамика по 18 последним кравлам
ccq example.com --locales --sections     # разбивка по языкам и разделам
ccq example.com --compare example.org,example.net
ccq example.com --errors                 # 404/301/5xx, которые получил краулер
ccq example.com --robots                 # robots.txt глазами краулера
ccq --discover de --min-pages 100        # домены зоны .de
ccq --zone-suffixes uk                   # co.uk / org.uk / gov.uk ...
ccq --list-crawls
```

Любую команду можно получить в JSON: `--json`.

## MCP

```bash
claude mcp add common-crawl -- uvx --from git+https://github.com/nikolaymokh-dev/common-crawl-mcp common-crawl-mcp
```

### Тулы

| Тул | Зачем |
|---|---|
| `cc_presence` | Сколько страниц домена в кравле |
| `cc_dynamics` | Динамика по кравлам — основа для любых выводов |
| `cc_compare` | Несколько доменов одним сканом |
| `cc_locales` | Разбивка по языковым префиксам пути |
| `cc_sections` | Топ разделов: где охват проседает |
| `cc_urls` | Конкретные URL + координаты в архиве |
| `cc_duplicates` | Страницы-дубли (одинаковый `content_digest`) |
| `cc_errors` | Не-200 ответы у домена |
| `cc_robots` | `robots.txt` в момент обхода |
| `cc_discover` | Домены по зоне и/или подстроке |
| `cc_zone_suffixes` | Суффиксы внутри зоны |
| `cc_fetch_text` | Текст страницы из архива — то, что читает модель |
| `cc_crawls` | Список доступных кравлов |

## Что стоит знать

**Ноль страниц ≠ сайта нет.** Охват Common Crawl заметно скачет между кравлами: сайт,
стабильно дающий сотни страниц, может провалиться до единиц. Любой вывод делается по
`cc_dynamics`, а не по одному снимку.

**Поиск по зоне почти бесплатен.** Индекс отсортирован по `url_surtkey` — имени хоста
задом наперёд, — поэтому домены одной зоны лежат в файлах подряд, и Athena пропускает
всё остальное. Замерено на `CC-MAIN-2026-30`: `.uz` — 0.28 MB скана на 7 954 домена,
`.de` — 23 MB на 2 075 692 домена.

**Поиск по подстроке — нет.** `host_contains` не может воспользоваться этой сортировкой,
поэтому без указания зоны он читает колонку хостов по всему кравлу. Тул это запрещает,
пока не передашь `allow_full_scan=True`. Заодно зона отсекает ложные совпадения: короткая
подстрока по всему вебу цепляет случайные домены из чужих зон, внутри одной зоны — нет.

**Составные зоны.** `tld='uk'` захватывает и `example.uk`, и `example.co.uk`. Нужен
конкретный сегмент — фильтруй `registry_suffix='co.uk'`. Посмотреть, что вообще есть
в зоне, — `cc_zone_suffixes`.

**Стоимость возвращается вместе с данными.** В каждом ответе есть `scanned_mb` и
`cost_usd`. Athena billing округляет запрос вверх до 10 MB.

## Разработка

```bash
uv sync --extra dev
uv run pytest              # юнит-тесты, сети не требуют
```

Структура: `athena.py` — транспорт, `crawls.py` — какие кравлы есть, `queries.py` —
построители SQL (чистые функции, тестируются без AWS), `api.py` — операции,
`warc.py` — извлечение текста, `cli.py` и `server.py` — две обёртки над `api`.

## Лицензия

MIT