haraj-mcp

Сервер Model Context Protocol (MCP) для haraj.com.sa — крупнейшей доски объявлений в Саудовской Аравии.

Этот сервер предоставляет 21 инструмент любому MCP-совместимому агенту (Claude Desktop, Cursor, opencode, Zed и т.д.), позволяя искать и получать объявления с маркетплейса в реальном времени без копирования и вставки curl-команд.

Все инструменты повторяют реальные операции haraj.com.sa, зафиксированные в ходе живой браузерной сессии (2026-08-17). Никаких выдуманных фильтров — каждый аргумент соответствует тому, что живой фронтенд фактически отправляет в своих GraphQL-запросах.

Claude Desktop / Cursor / opencode
        │
        │  MCP (JSON-RPC over stdio)
        ▼
   ┌──────────────┐
   │  haraj-mcp   │ ── HTTPS ──▶  graphql.haraj.com.sa
   │  (Python)    │                + livestream.haraj.com.sa
   └──────────────┘

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

Обнаружение

Лента / поиск

Детали объявления

Пользователь

Аккаунт

Для fetch_feed, promoted_posts и search передайте full=True, чтобы получить полный объект Post вместо компактной сводки. Компактная сводка содержит следующие ключи:

{
  "id": 185926519,
  "title": "...",
  "price_sar": 650.0,
  "price_display": "650 SAR",
  "url": "https://haraj.com.sa/...",
  "city": "الشرقيه",
  "geo_city": "الدمام",
  "post_date": 1785729404,
  "has_image": true,
  "thumb_url": "https://mimg6cdn.haraj.com.sa/...",
  "tags": ["شاشات", "..."],
  "has_price": true
}

Установка

cd /mnt/W/Desktop/Software/haraj-mcp
pip install -e .

Эта команда устанавливает консольный скрипт haraj-mcp в ваш PATH.

Настройка авторизации

cp .env.example .env
# Edit .env and paste your HARAJ_JWT and LAST_REQUEST_ID.

Как получить свежие значения (они истекают каждые ~10 дней):

1. Откройте https://haraj.com.sa в Chrome и войдите в систему.

2. F12 → вкладка Network → нажмите на любой запрос к graphql.haraj.com.sa.

3. В Headers скопируйте authorization (начинается с Bearer eyJ…) и lastRequestId.

4. Вставьте их в .env и перезапустите MCP-сервер.

Проверить можно с помощью check_auth — он возвращает утверждение exp из JWT и seconds_remaining.

Подключение к вашему MCP-клиенту

opencode / Claude Desktop / Cursor

Добавьте это в конфигурацию MCP вашего клиента (обычно ~/.config/opencode/opencode.json, ~/Library/Application Support/Claude/claude_desktop_config.json или ~/.cursor/mcp.json):

{
  "mcpServers": {
    "haraj": {
      "command": "haraj-mcp",
      "cwd": "/mnt/W/Desktop/Software/haraj-mcp"
    }
  }
}

Сервер читает .env из cwd, поэтому секреты остаются в каталоге проекта и не попадают в конфигурацию MCP-клиента.

Нестандартное расположение .env

Укажите HARAJ_MCP_ENV=/path/to/.env в блоке env конфигурации MCP.

Примеры промптов для агента

После подключения ваш агент сможет отвечать:

"Что сегодня в тренде на haraj?" "Получи последние 20 объявлений в حراج السيارات (категория автомобилей)." "Найди на haraj RTX 4090 за последнюю неделю (during_date=1week)." "Получи профиль продавца и все его текущие объявления для post_id=185354313." "Какую стоимость доставки я заплачу, если куплю это объявление через Locker?" "Что люди вводят в поисковой строке после شاشة?" "Перечисли все открытые прямые эфиры покупок прямо сейчас."

Запуск без MCP-клиента (отладка)

Передавайте JSON-RPC-сообщения прямо на сервер:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_regions","arguments":{}}}' | python -m haraj_mcp

Тесты

python tests/test_smoke.py

10 тестов покрывают: регистрацию инструментов (21 инструмент), живой URL version, заголовок sec-ch-ua-platform-version, сохранение опечатки initalChars, реальные переменные поиска, форму компактного сериализатора, валидацию JWT (действительный/просроченный/некорректный), обработку ошибок check_auth и полный сквозной тест через stdio.

Руководство для агента

Справочник "для чего используется каждый инструмент" (и примеры рабочих процессов агента) см. в docs/AGENT_GUIDE.md. В нём объясняется:

• 21 инструмент, сгруппированный по сценариям использования (обнаружение, лента/поиск, детали объявления, пользователь, аккаунт)

• Типовые многошаговые сценарии (например, "найди мне выгодное предложение на RTX 4090" → 5 последовательных вызовов инструментов)

• Шпаргалка по пагинации (какие инструменты используют какой курсор)

• Примечания по конфиденциальности / безопасности (какие инструменты возвращают чувствительные данные, такие как IBAN и номера мобильных)

• Фрагменты диалогов, показывающие, как агент вызывает инструменты

Поделитесь docs/AGENT_GUIDE.md с LLM-клиентом (или используйте его как справочник при написании системных промптов).

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

haraj-mcp/
├── pyproject.toml
├── README.md
├── .env.example
├── src/haraj_mcp/
│   ├── __init__.py
│   ├── __main__.py        # entry point: `python -m haraj_mcp`
│   ├── server.py         # FastMCP setup, 21 tool registrations
│   ├── tools.py          # the 21 tool implementations
│   └── auth.py           # .env reader + JWT validation
├── haraj/                # GraphQL client (captured from live haraj.com.sa)
│   ├── client.py
│   ├── models.py
│   ├── queries.py        # 20 exact-captured query strings
│   ├── constants.py
│   ├── auth.py
│   └── images.py
└── tests/test_smoke.py

Что изменилось в v0.2.0

В v0.1.0 было 4 инструмента (search_haraj, get_post, list_regions, check_auth), которые я выдумал на основе живой GraphQL-схемы, — многие из поддерживаемых фильтров никогда не использовались реальным сайтом.

v0.2.0 заменяет их на 21 инструмент, повторяющий реальные операции, которые использует haraj.com.sa. Зафиксировано в реальной браузерной сессии 2026-08-17 (219 запросов, 173 POST-запроса GraphQL). Ключевые исправления:

• search больше не содержит выдуманных фильтров (carExtraInfo, priceRange, userLocation, notTag, authorUsername); только те переменные, которые реально отправляет живой сайт (search, cities, city, tag, tags, page, limit, onlyWithImage, onlyWithVideo, hideShowRooms, orderByPostId, duringDate, near)

• searchSuggest сохраняет опечатку initalChars живого API (сервер требует её)

• Параметр version в URL обновлён до 2026-08-11 22 (было 2026-08-03 15)

• Добавлен заголовок sec-ch-ua-platform-version (отправляется при каждом живом вызове)

• ViewOptions теперь содержит mustLoginToView (присутствует только в операции posts)

• Новый инструмент live_streams для не-GraphQL эндпоинта livestream.haraj.com.sa

• get_post_details теперь использует правильный эндпоинт similarPosts(id:) (вместо хака с использованием ID в качестве ключевого слова)