WebSearchAndCrawl

MCP-сервер для аутентифицированного обхода веб-сайтов, поиска и обработки документов

***.

🚀 Назначение

WebSearchAndCrawl — это MCP-сервер (Model Context Protocol), предназначенный для:

1. Обхода веб-сайтов (включая сайты с авторизацией) с использованием токенов сессии Firefox или автоматизации браузера.

2. Поиска в обойденном содержимом по регулярным выражениям и сохранения результатов в структурированный индекс.

3. Скачивания и разбора документов (PDF, DOCX, XLSX и т.д.) с обойденных сайтов.

4. Потоковой передачи результатов в реальном времени через HTTP для интеграции с MCP-клиентами.

5. Соблюдения robots.txt и применения ограничений скорости (5 запросов/сек, максимум 5 потоков).

Этот инструмент идеально подходит для:

• Исследователей, которым необходимо парсить сайты с авторизацией или динамические сайты.

• Разработчиков, создающих ИИ-агентов, требующих веб-данных.

• Автоматизации повторяющихся веб-задач (например, мониторинг, извлечение данных).

Related MCP server: Scout MCP Server

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

📦 Установка

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

1. Python 3.9+ (рекомендуется: 3.11+).

2. Firefox (требуется для автоматизации браузера).

3. Системные библиотеки (для обработки документов):

   • PDF: poppler-utils (Linux) или pdfminer.six (кроссплатформенное решение).

   • DOCX/XLSX: python-docx, openpyxl.

Шаги

1. Клонируйте репозиторий

git clone https://github.com/bpweatherill/WebSearchAndCrawl.git
cd WebSearchAndCrawl

2. Создайте виртуальное окружение

python -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate   # Windows

3. Установите зависимости

pip install -r requirements.txt

4. Установите браузеры Playwright

playwright install firefox

5. (Необязательно) настройте переменные окружения

Создайте файл .env в корне проекта:

# Server
MCP_PORT=8808
MCP_HOST=0.0.0.0

# Crawler
MAX_DEPTH=9
MAX_THREADS=5
RATE_LIMIT=5
REQUEST_TIMEOUT=10
MAX_MEMORY_MB=1024

# Firefox
FIREFOX_PROFILE=my_profile  # Optional: Specific Firefox profile
DEFAULT_SEARCH_ENGINE=google

# Directories
INDEX_DIR=./index
DOWNLOADS_DIR=./downloads
CHECKPOINTS_DIR=./checkpoints

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

1. Запустите MCP-сервер

python -m server.main

Сервер запустится на http://localhost:8808 (или на порту, указанном в .env).

2. MCP-инструменты (HTTP-эндпоинты)

Все инструменты возвращают JSON-ответы и поддерживают потоковую передачу для результатов в реальном времени.

Схемы запросов и ответов

CrawlRequest

{
  "url": "https://www.nasa.gov",
  "whitelist_domains": "nasa.gov",
  "max_depth": 3,
  "use_token": false,
  "firefox_profile": "my_profile"
}

• url: стартовый URL для обхода.

• whitelist_domains: список разрешенных доменов через запятую (например, "nasa.gov,spacex.com").

• max_depth: максимальная глубина обхода (1-9).

• use_token: использовать токен сессии Firefox при наличии.

• firefox_profile: имя профиля Firefox (необязательно).

Потоковый ответ (JSONL):

{
  "excerpt": "NASA's Perseverance Rover lands on Mars...",
  "full_text": "Full article text here...",
  "url": "https://www.nasa.gov/mars2020",
  "timestamp": "2024-05-20T12:00:00Z",
  "domain": "nasa.gov"
}

SearchIndexRequest

{
  "domain": "nasa.gov",
  "regex": ".*Mars.*",
  "max_results": 10
}

• domain: домен для поиска (например, "nasa.gov").

• regex: регулярное выражение для сопоставления.

• max_results: максимальное количество возвращаемых результатов.

Ответ:

[
  {
    "url": "https://www.nasa.gov/mars2020",
    "excerpt": "NASA's Perseverance Rover lands on Mars...",
    "timestamp": "2024-05-20T12:00:00Z"
  }
]

DownloadRequest

{
  "domain": "nasa.gov",
  "regex": ".*\\.pdf$",
  "output_dir": "./downloads/nasa.gov"
}

• domain: домен, из которого выполняется загрузка.

• regex: регулярное выражение для файлов, которые нужно загрузить (например, "*.pdf").

• output_dir: пользовательский каталог вывода (необязательно).

Потоковый ответ (JSONL):

{
  "filename": "./downloads/nasa.gov/mars_rover.pdf",
  "url": "https://www.nasa.gov/pdf/mars_rover.pdf",
  "parsed_text": "Extracted text from PDF..."
}

WebSearchRequest

{
  "query": "NASA Mars missions",
  "search_engine": "google",
  "use_token": false,
  "firefox_profile": "my_profile"
}

• query: поисковый запрос.

• search_engine: поисковая система (по умолчанию: поисковая система Firefox).

• use_token: использовать токен сессии Firefox при наличии.

• firefox_profile: имя профиля Firefox (необязательно).

Потоковый ответ (JSONL):

{
  "title": "Mars 2020 Mission - NASA",
  "url": "https://www.nasa.gov/mars2020",
  "snippet": "Learn about the Perseverance Rover..."
}

🔍 Примеры

1. Выполнить обход NASA.gov и индексировать результаты

curl -X POST http://localhost:8808/crawl_website \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.nasa.gov",
    "whitelist_domains": "nasa.gov",
    "max_depth": 2,
    "use_token": false
  }'

2. Выполнить поиск в индексированном содержимом для «Mars»

curl -X POST http://localhost:8808/search_index \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "nasa.gov",
    "regex": ".*Mars.*",
    "max_results": 5
  }'

3. Скачать PDF-файлы с NASA.gov

curl -X POST http://localhost:8808/download_documents \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "nasa.gov",
    "regex": ".*\\.pdf$"
  }'

4. Использовать Firefox для поиска через Google

curl -X POST http://localhost:8808/get_search_results \
  -H "Content-Type: application/json" \
  -d '{
    "query": "NASA Mars missions",
    "search_engine": "google"
  }'

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

WebSearchAndCrawl/
│
├── server/                          # Core server logic
│   ├── __init__.py
│   ├── main.py                       # FastAPI app + MCP tools
│   ├── config.py                     # Configuration settings
│   ├── schemas.py                    # Pydantic request/response models
│   │
│   ├── firefox/                      # Firefox browser automation
│   │   ├── __init__.py
│   │   ├── controller.py              # Playwright Firefox management
│   │   └── token_manager.py           # Session token handling
│   │
│   ├── crawler/                     # Web crawling logic
│   │   ├── __init__.py
│   │   ├── crawler.py                # Main crawling logic
│   │   └── rate_limiter.py            # Thread/rate limiting
│   │
│   ├── indexer/                     # Indexing and search
│   │   ├── __init__.py
│   │   ├── indexer.py                 # JSON index management
│   │   └── search_engine.py           # Regex search
│   │
│   ├── downloader/                  # Document downloading and parsing
│   │   ├── __init__.py
│   │   ├── downloader.py              # Download logic
│   │   └── parsers/                  # File type parsers
│   │       ├── __init__.py
│   │       ├── pdf_parser.py
│   │       ├── docx_parser.py
│   │       └── xlsx_parser.py
│   │
│   └── streamer.py                   # Chunked JSON streaming
│
├── tests/                           # Unit and integration tests
│   ├── __init__.py
│   ├── test_firefox.py
│   └── test_crawler.py
│
├── index/                           # Index files (auto-generated)
│   ├── nasa.gov.json
│   └── ...
│
├── downloads/                       # Downloaded documents (auto-generated)
│   ├── nasa.gov/
│   │   ├── document1.pdf
│   │   └── ...
│   └── ...
│
├── checkpoints/                     # Crawl checkpoints (auto-generated)
│   └── ...
│
├── requirements.txt                 # Python dependencies
├── .env.example                     # Example environment variables
└── README.md                        # This file

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

Переменные окружения

🛡️ Вопросы безопасности

1. Сессионные токены:

   • Токены хранятся только в памяти (не сохраняются на диск).

   • Область действия токенов проверяется для предотвращения злоупотреблений (например, токен для nasa.gov не может использоваться для evil.com).

2. Санация входных данных:

   • Все входящие данные (URL, регулярные выражения и т.д.) обезаражены для предотвращения инъекций.

3. Ограничение скорости:

   • Обеспечивается 5 запросов/сек и максимум 5 потоков, чтобы не перегружать серверы.

4. Соблюдение robots.txt:

   • Обходчик уважает robots.txt и пропускает запрещенные URL.

5. Белый список:

   • Обходятся только URL, соответствующие доменам из белого списка.

🚀 Дальнейшие улучшения (дорожной карты)

-" button" **)| Высокий | | Поддержка ленивой загрузки | Обнаружение и активация контента с ленивой загрузкой (например, бесконечная прокрутка). | Высокий | | Контрольные точки | Сохранение состояния обхода для возобновления прерванных обходов. | Высокий | | Полнотекстовый поиск | Поддержка полнотекстового поиска в дополнение к регулярным выражениям. | Низкий | | База данных в качестве хранилища | Замена JSON-файлов на БД SQLite/PostgreSQL для масштабируемости. | Низкий | | Распределенный обход | Поддержка горизонтального масштабирования с несколькими воркерами. | Низкий | | Поддержка Docker | Добавление Dockerfile для развертывания в контейнере. | Medium | | Вспомогательные модули аутентификации | Всторенная поддом для распространенных методов аутентификации (OAuth, SAML). | Middle | | Поддержка прокси | Добавление прокси для обхода за файлов. | Low | | Пользовательские заголовки | Возможность задавать пользовательские заголовки для запросов. | Medium | | Webhook-уведомления | Уведомление на webhook при обнаружении новых результатов. | Low |

🤝 Соавторство

1. Сделайте fork (ответвление) репозитория.

2. Создайте ветку для функции (git checkout -b feature/your-feature).

3. Зафиксируйте свои изменения (git commit -m "Add your feature").

4. загрузите своим ветку (git push origin feature/your-feature).

5. Откройте Pull Request.

📜 Лицензия

Этот проект распространяется под лицензией MIT License. См. LICENSE для получения информации.

📞 Поддержка

• Issues: Сообщите об ошибках или запрос новых возможностей в разделе GitHub Issues.

• Discussions: Присоединяйтесь к обсуждению в разделе GitHub Discussions для вопросов и ответов.

🏆 Благодарности

• Playwright: за автоматизацию браузера.

• FastAPI: за HTTP-сервер.

• pdfminer.six: за разбор PDF.

• python-docx/openpyxl: за разбор файлов Office.# WebSearchAndCrawl

MCP-сервер для аутентичного веб-скрапинга, поиска и обработки документов

***.

🚀 Назначение

WebSearchAndCrawl — это MCP-сервер (Model Context Protocol), разработанный для:

1. Обхода веб-сайтов (включая сайты с авторизацией) с использованием токенов сессий Firefox или автоматизации браузера.

2. Поиска в обходе контента по регулярным выражениям и сохранения результатов в структурированный индекс.

3. Загрузка и разбора документов (PDF, DOCX, XLSX и т.д.) с обойденных сайтов.

4. Стримминга результатов в реальном времени через HTTP для интеграции с MCP-клиентами.

5. Соблюдение robots.txt и ограничения скорости запросов (5 запросов в секунду, максимум 5 потоков).

Этот инструмент идеально подходит для:

• Исследователей, нуждающихся в scraping аутентифицированных или динамических веб-сайтов.

• Разработчиков, создающих ИИ-агентов, требующих веб-данных.

• Автоматизации повторяющихся веб-задач (например, мониторинг, извлечение данных).

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

📦 Установка

Необходимые компоненты

1. Python 3.9+ (рекомендуется: 3.11+).

2. Firefox (требуется для автоматизации браузера).

3. Системные библиотеки (для обработки документов):

   • PDF: poppler-utils (Linux) или pdfminer.six (кроссплатформенная версия).

   • DOCX/XLSX: python-docx, openpyxl.

Шаги

1. Клонируйте репозиторий

git clone https://github.com/bpweatherill/WebSearchAndCrawl.git
cd WebSearchAndCrawl

2. Создайте виртуальное окружение

python -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate   # Windows

3. Установите зависимости

pip install -r requirements.txt

4. Установите браузеры Playwright

playwright install firefox

5. (Необязательно) Настройте переменные окружения

Создайте файл .env в корне проекта:

# Server
MCP_PORT=8808
MCP_HOST=0.0.0.0

# Crawler
MAX_DEPTH=9
MAX_THREADS=5
RATE_LIMIT=5
REQUEST_TIMEOUT=10
MAX_MEMORY_MB=1024

# Firefox
FIREFOX_PROFILE=my_profile  # Optional: Specific Firefox profile
DEFAULT_SEARCH_ENGINE=google

# Directories
INDEX_DIR=./index
DOWNLOADS_DIR=./downloads
CHECKPOINTS_DIR=./checkpoints

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

1. Запустите MCP-сервер

python -m server.main

Сервер будет запущен на http://localhost:8808 (или на порту, указанном в .env).

2. MCP-инструменты (HTTP endpoints)

Все инструменты возвращают JSON-ответы и поддерживают стриминг для результатов реальном времени.

Схемы запросов/ответов

CrawlRequest

{
  "url": "https://www.nasa.gov",
  "whitelist_domains": "nasa.gov",
  "max_depth": 3,
  "use_token": false,
  "firefox_profile": "my_profile"
}

• URL: Начальный URL (обход).

• whitelist_domains: список разрешённых доменов через запятую (например, "nasa.ru,spacex.com").

• max_depth: максимальная глубина обхода (от 1 до 9).

• use_token: Использовать токен сессии Firefox при наличии.

• firefox_profile: имя профиля Firefox (необязательно).

Потоковый ответ (JSONL):

{
  "excerpt": "NASA's Perseverance Rover lands on Mars...",
  "full_text": "Full article text here...",
  "url": "https://www.nasa.gov/mars2020",
  "timestamp": "2024-05-20T12:00:00Z",
  "domain": "nasa.gov"
}

SearchIndexRequest

{
  "domain": "nasa.gov",
  "regex": ".*Mars.*",
  "max_results": 10
}

• domain: дmosферу поиска (например, "nasa.ru").

• regex: регулярное выражение для сопоставления.

• max_results: Максимальное количество результатов.

Ответ:

[
  {
    "url": "https://www.nasa.gov/mars2020",
    "excerpt": "NASA's Perseverance Rover lands on Mars...",
    "timestamp": "2024-05-20T12:00:00Z"
  }
]

DownloadRequest

{
  "domain": "nasa.gov",
  "regex": ".*\\.pdf$",
  "output_dir": "./downloads/nasa.gov"
}

• domain: Домен, из которого скачивать данные.

• regex: регулярное выражение для загружаемых файлов (например, "*.pdf").

• output_dir: пользовательский каталог вывода (необязательно).

Потоковый ответ (JSONL):

{
  "filename": "./downloads/nasa.gov/mars_rover.pdf",
  "url": "https://www.nasa.gov/pdf/mars_rover.pdf",
  "parsed_text": "Extracted text from PDF..."
}

WebSearchRequest

{
  "query": "NASA Mars missions",
  "search_engine": "google",
  "use_token": false,
  "firefox_profile": "my_profile"
}

• query: поисковый запрос.

• search_engine: поисковая система (по умолчанию: поисковая система Firefox).

• use_token: использовать токен-сессии Firefox.

• firefox_profile: имя профиля Firefox (необязательно).

Потоковый ответ (JSON):

{
  "title": "Mars 2020 Mission - NASA",
  "url": "https://www.nasa.gov/mars2020",
  "snippet": "Learn about the Perseverance Rover..."
}

🔍 Примеры

1. Обход NASA.ru и индексирование результатов

curl -X POST http://localhost:8808/crawl_website \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.nasa.gov",
    "whitelist_domains": "nasa.gov",
    "max_depth": 2,
    "use_token": false
  }'

2. Поиск в индексированном содержимом ("Марс")

curl -X POST http://localhost:8808/search_index \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "nasa.gov",
    "regex": ".*Mars.*",
    "max_results": 5
  }'

3. Загрузка PDF-файлов с NASA.ru

curl -X POST http://localhost:8808/download_documents \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "nasa.gov",
    "regex": ".*\\.pdf$"
  }'

4. Использование Firefox для поиска через Google

curl -X POST http://localhost:8808/get_search_results \
  -H "Content-Type: application/json" \
  -d '{
    "query": "NASA Mars missions",
    "search_engine": "google"
  }'

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

WebSearchAndCrawl/
│
├── server/                          # Core server logic
│   ├── __init__.py
│   ├── main.py                       # FastAPI app + MCP tools
│   ├── config.py                     # Configuration settings
│   ├── schemas.py                    # Pydantic request/response models
│   │
│   ├── firefox/                      # Firefox browser automation
│   │   ├── __init__.py
│   │   ├── controller.py              # Playwright Firefox management
│   │   └── token_manager.py           # Session token handling
│   │
│   ├── crawler/                     # Web crawling logic
│   │   ├── __init__.py
│   │   ├── crawler.py                # Main crawling logic
│   │   └── rate_limiter.py            # Thread/rate limiting
│   │
│   ├── indexer/                     # Indexing and search
│   │   ├── __init__.py
│   │   ├── indexer.py                 # JSON index management
│   │   └── search_engine.py           # Regex search
│   │
│   ├── downloader/                  # Document downloading and parsing
│   │   ├── __init__.py
│   │   ├── downloader.py              # Download logic
│   │   └── parsers/                  # File type parsers
│   │       ├── __init__.py
│   │       ├── pdf_parser.py
│   │       ├── docx_parser.py
│   │       └── xlsx_parser.py
│   │
│   └── streamer.py                   # Chunked JSON streaming
│
├── tests/                           # Unit and integration tests
│   ├── __init__.py
│   ├── test_firefox.py
│   └── test_crawler.py
│
├── index/                           # Index files (auto-generated)
│   ├── nasa.gov.json
│   └── ...
│
├── downloads/                       # Downloaded documents (auto-generated)
│   ├── nasa.gov/
│   │   ├── document1.pdf
│   │   └── ...
│   └── ...
│
├── checkpoints/                     # Crawl checkpoints (auto-generated)
│   └── ...
│
├── requirements.txt                 # Python dependencies
├── .env.example                     # Example environment variables
└── README.md                        # This file

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

Переменные окружения

🛡️ Аспекты безопасности

1. Токены сессии:

   • Токены хранятся только в полной мере (не сохраняются на диск).

   • Области применения токенов (проверяются на предмет несоответствия (например, токен для nasa.gov нельзя использовать для evil.com).

2. Очистка входных данных:

   • Все входные данные (URL, регулярные выражения и т. д.) санируются для защиты от внедрения.

3. Ограничение скорости:

   • Принудительно задаются 5 запросов/с и максимум 5 потоков, чтобы не перегружать серверы.

4. Уважение robots.txt:

   • Краулер соблюдает robots.txt и пропускает запрещённые URL.

5. Белый список:

   • Обход разрешён только для URL из списка доменов.

🚀 План улучшений (Roadmap)

🤝 Запланированные улучшения

1. Основайте решение.

2. Создайте ветку для ваших изменений.

3. Внесите свои изменения.

4. Выотайте исходных ветку в origin.

5. Откройте Pull Request.

📜 Лицензия

Этот проект распространяется под лицензией MIT. Подробнее см. LICENSE.

📞 Поддержка

• Проблемы: Сообщить об ошибках или запросить функции на странице GitHub Issues .

• ** Обсуждения**: Присоединяйтесь к обсуждениям на GitHub Discussions для вопросов.

🏆 Благодарность

• Playwright: Автоматизация браузера.

• FastAPI: HTTP-сервер.

• pdfminer.six: Разбор PDF-файлов.

• python-docx/openpyxl: Разбор файлов Office.