haraj-mcp

Un servidor de Model Context Protocol (MCP) para haraj.com.sa, el mercado de anuncios clasificados más grande de Arabia Saudí.

Este servidor expone 21 herramientas a cualquier agente compatible con MCP (Claude Desktop, Cursor, opencode, Zed, etc.) para que pueda buscar y obtener listados del mercado en tiempo real, sin necesidad de copiar y pegar comandos curl.

Todas las herramientas replican las operaciones reales de haraj.com.sa capturadas desde una sesión de navegador en vivo (2026-08-17). Sin filtros inventados: cada argumento coincide exactamente con lo que el frontend real envía en sus llamadas GraphQL.

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

Herramientas expuestas (21)

Descubrimiento

Feed / búsqueda

Detalle de publicación

Usuario

Cuenta

Para fetch_feed, promoted_posts y search, pasa full=True para obtener el objeto Post completo en lugar de un resumen compacto. El resumen compacto tiene estas claves:

{
  "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
}

Instalación

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

Esto instala el script de consola haraj-mcp en tu PATH.

Configurar autenticación

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

Cómo obtener valores nuevos (expiran cada ~10 días):

1. Abre https://haraj.com.sa en Chrome e inicia sesión.

2. F12 → pestaña Network → haz clic en cualquier solicitud de graphql.haraj.com.sa.

3. En Headers, copia authorization (empieza por Bearer eyJ…) y lastRequestId.

4. Pégalo en .env y reinicia el servidor MCP.

Puedes verificarlo con check_auth: devuelve el claim exp del JWT y seconds_remaining.

Conexión con tu cliente MCP

opencode / Claude Desktop / Cursor

Añade esto a la configuración MCP de tu cliente (normalmente ~/.config/opencode/opencode.json, ~/Library/Application Support/Claude/claude_desktop_config.json o ~/.cursor/mcp.json):

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

El servidor lee .env desde cwd, por lo que los secretos permanecen en el directorio del proyecto y no se filtran a la configuración MCP de tu cliente.

Ubicación personalizada de .env

Define HARAJ_MCP_ENV=/path/to/.env en el bloque env de la configuración MCP.

Ejemplos de prompts para agentes

Una vez conectado, tu agente puede responder:

"¿Qué es tendencia en haraj hoy?"

"Obtén las últimas 20 publicaciones en حراج السيارات (la categoría de coches)."

"Busca en haraj RTX 4090 en la última semana (during_date=1week)."

"Obtén el perfil del vendedor y todos sus listados actuales para post_id=185354313."

"¿Qué tarifa de envío pago si compro esta publicación a través de Locker?"

"¿Qué está escribiendo la gente en el cuadro de búsqueda después de شاشة?"

"Enumera todas las transmisiones de compras en vivo abiertas ahora mismo."

Ejecutar sin un cliente MCP (depuración)

Envía mensajes JSON-RPC directamente al servidor:

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

Pruebas

python tests/test_smoke.py

10 pruebas cubren: registro de herramientas (21 herramientas), URL version en vivo, cabecera sec-ch-ua-platform-version, preservación del error tipográfico initalChars, variables de búsqueda reales, forma del serializador compacto, validación de JWT (válido/expirado/malformado), manejo de errores de check_auth y una prueba integral de stdio de extremo a extremo.

Guía para agentes

Para una referencia por herramienta de "para qué se usa esto" (y ejemplos de flujos de trabajo de agentes), consulta docs/AGENT_GUIDE.md. Explica:

• Las 21 herramientas organizadas por caso de uso (descubrimiento, feed/búsqueda, detalle de publicación, usuario, cuenta)

• Flujos de trabajo comunes de varios pasos (p. ej., "encuéntrame una oferta de un RTX 4090" → 5 llamadas a herramientas encadenadas)

• Chuleta de paginación (qué herramientas usan cada cursor)

• Notas de privacidad / seguridad (qué herramientas devuelven datos sensibles como IBANs y números de móvil)

• Fragmentos de conversación que muestran al agente llamando a las herramientas

Comparte docs/AGENT_GUIDE.md con el cliente LLM (o úsalo como referencia al escribir prompts de sistema).

Estructura del proyecto

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

Qué cambió en v0.2.0

v0.1.0 tenía 4 herramientas (search_haraj, get_post, list_regions, check_auth) que había inventado a partir del esquema GraphQL en vivo; muchos de los filtros admitidos nunca los usaba el sitio real.

v0.2.0 las reemplaza con 21 herramientas que replican las operaciones reales que usa haraj.com.sa. Capturadas de una sesión de navegador real el 2026-08-17 (219 solicitudes, 173 POST de GraphQL). Los cambios clave:

• search ya no tiene filtros inventados (carExtraInfo, priceRange, userLocation, notTag, authorUsername); solo las variables que el sitio en vivo realmente envía (search, cities, city, tag, tags, page, limit, onlyWithImage, onlyWithVideo, hideShowRooms, orderByPostId, duringDate, near)

• searchSuggest conserva el error tipográfico initalChars del wire en vivo (el servidor lo requiere)

• El parámetro de URL version se actualizó a 2026-08-11 22 (antes 2026-08-03 15)

• Se añadió la cabecera sec-ch-ua-platform-version (se envía en cada llamada en vivo)

• ViewOptions tiene mustLoginToView (solo presente en la operación posts)

• Nueva herramienta live_streams para el endpoint no GraphQL livestream.haraj.com.sa

• get_post_details ahora usa el endpoint correcto similarPosts(id:) (no el truco de usar el ID como palabra clave)