Перейти к основному содержимому

metawarc MCP-сервер

metawarc включает MCP-сервер (Model Context Protocol) для ИИ-агентов и MCP-совместимых клиентов: Claude Desktop, Cursor и других. Сервер даёт доступ к проиндексированной WARC-коллекции только на чтение через семь инструментов.

Список инструментов и их параметры сверены с metawarc/mcp_server.py версии 2.0.3 и проверены вызовами через клиент FastMCP на тестовом каталоге (октябрь 2026).

Чем он безопаснее прямого доступа​

  • Только перечисленные инструменты — других действий у агента нет.
  • Нет сырого SQL и нет путей файловой системы в параметрах.
  • Нет содержимого записей — только метаданные и заголовки.
  • Нет изменяющих операций — каталог открывается только на чтение (кроме поиска, которому нужен доступ к сайдкару текстов).
  • Ограниченные выборки — list_records отдаёт не больше 100 записей за вызов, листание — через offset.
  • Неверные значения (неизвестное измерение, limit вне диапазона) возвращаются агенту как ошибка инструмента.

Установка и запуск​

pip install 'metawarc[mcp]'

# stdio — обычный режим для локальных клиентов
metawarc mcp --dbfile collection.db

# HTTP на локальном адресе: http://127.0.0.1:8191/mcp
metawarc mcp --dbfile collection.db --transport http

# Другой порт
metawarc mcp --dbfile collection.db --transport http --port 8765

Опции: -d/--dbfile, --data-dir, --transport stdio|http|sse (по умолчанию stdio), --host (по умолчанию 127.0.0.1), --port (по умолчанию 8191), --allow-insecure. Запуск HTTP или SSE на нелокальном адресе без --allow-insecure завершится ошибкой. Авторизации у MCP-сервера нет, поэтому сетевой транспорт стоит держать на 127.0.0.1.

Подключение к клиентам​

Claude Desktop​

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
"mcpServers": {
"ruarxive-metawarc": {
"command": "metawarc",
"args": ["mcp", "--dbfile", "/path/to/collection.db"]
}
}
}

Cursor​

Файл ~/.cursor/mcp.json (или .cursor/mcp.json в проекте):

{
"mcpServers": {
"ruarxive-metawarc": {
"command": "metawarc",
"args": ["mcp", "--dbfile", "/path/to/collection.db"]
}
}
}

Если metawarc установлен в виртуальное окружение, укажите в command полный путь к исполняемому файлу. Формат настроек других клиентов смотрите в их документации.

HTTP-транспорт​

Для клиентов, которые подключаются по URL, запустите metawarc mcp --transport http и укажите адрес http://127.0.0.1:8191/mcp.

Инструменты​

ИнструментНазначениеПараметры
list_archivesСписок архивов в каталоге и их статус—
list_recordsЗаписи с фильтрамиarchive_ids, mimes, exts, url_pattern, host_pattern, status_min, status_max, size_min, size_max, offset (по умолчанию 0), limit (по умолчанию 50, максимум 100)
get_record_metadataОдна запись по архиву и ID записи WARCarchive_id, record_id
get_record_headersСохранённые HTTP-заголовки записиarchive_id, record_id
search_recordsПоиск фразы в сайдкаре textsphrase, limit (по умолчанию 50)
collection_statsСводка по измерениямarchive_ids, dimensions (через запятую из mime, ext, status, host, date, size_bucket; пусто — все), top (1–100 000, по умолчанию 10)
metadata_summaryСводка по извлечённым метаданнымmetadata_types (через запятую из pdfs, images, ooxmldocs, oledocs, videos, audio, fonts или all), archive_ids, top (по умолчанию 10)

Списки (archive_ids, mimes, exts, dimensions, metadata_types) передаются строкой через запятую. list_records возвращает {total, offset, limit, revision, items}, search_records — {phrase, limit, total, hits}, где у каждого результата есть archive_id, warc_id, source, url, snippet.

Чего инструменты не делают​

  • не выполняют SQL;
  • не открывают файлы по пути;
  • не отдают содержимое записей (для этого есть metawarc dump и REST API);
  • не ставят фоновые задачи и ничего не изменяют.

Примеры работы агента​

Пользователь: Что вообще есть в этой коллекции?
Агент: collection_stats(dimensions="mime,host", top=10)
→ самые частые MIME-типы и хосты с числом записей и объёмом
Пользователь: Найди страницы, где упоминается «бюджет».
Агент: search_records(phrase="бюджет", limit=20)
→ список URL с фрагментами текста
Пользователь: Сколько PDF с сайта example.gov.ru?
Агент: list_records(host_pattern="example.gov.ru", mimes="application/pdf", limit=100)
→ total и первые 100 записей; следующие — с offset=100, 200, ...
Пользователь: Что известно о PDF в коллекции?
Агент: metadata_summary(metadata_types="pdfs", top=20)
→ сводка по извлечённым метаданным PDF

Поиск работает только после metawarc index-content --text, сводка по метаданным — после index-content --type … для нужных типов.

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

УгрозаЗащита
SQL-инъекция, выгрузка всего каталогаНет инструмента с произвольным SQL; фильтры типизированы
Чтение произвольных файловПути не принимаются
Выгрузка больших объёмовlimit ≤ 100 у list_records
Изменение данныхИзменяющих инструментов нет
Доступ по сетиПо умолчанию только 127.0.0.1; для другого адреса нужен явный --allow-insecure

Рекомендации: используйте stdio, где это возможно; если нужен HTTP, оставляйте его на локальном адресе. Подробнее — в SECURITY.md и разделе о безопасности.

Ограничения​

  • Только чтение: добавлять архивы, удалять записи и выгружать файлы через MCP нельзя.
  • Пустой результат search_records, если не строился сайдкар texts.
  • Для полного перебора большой коллекции через list_records нужно много вызовов; для выгрузок удобнее REST API и фоновые задачи.
  • Сервер работает с одним каталогом, указанным в --dbfile.

Альтернативы​

  • REST API — для интеграций, содержимого записей и выгрузок.
  • CLI metawarc — для скриптов.
  • SQL в DuckDB поверх Parquet-сайдкаров — для разового анализа, см. рецепты.

Связанные материалы​