haraj-mcp

haraj.com.sa를 위한 Model Context Protocol (MCP) 서버 — 사우디아라비아 최대의 중고 광고 마켓플레이스입니다.

이 서버는 MCP를 지원하는 모든 에이전트(Claude Desktop, Cursor, opencode, Zed 등)에 21개 도구를 제공하여, 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. Chrome에서 https://haraj.com.sa를 열고 로그인합니다.

2. F12 → 네트워크 탭 → 아무 graphql.haraj.com.sa 요청을 클릭합니다.

3. 헤더에서 authorization(Bearer eyJ…로 시작)과 lastRequestId를 복사합니다.

4. .env에 붙여넣고 MCP 서버를 다시 시작합니다.

check_auth로 확인할 수 있습니다. JWT의 exp 클레임과 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"
    }
  }
}

서버는 cwd에서 .env를 읽으므로 비밀값이 프로젝트 디렉터리에 유지되고 MCP 클라이언트 설정으로 유출되지 않습니다.

사용자 지정 .env 위치

MCP 설정의 env 블록에 HARAJ_MCP_ENV=/path/to/.env를 설정하세요.

에이전트 프롬프트 예시

연동이 완료되면 에이전트는 다음 질문에 답할 수 있습니다:

"오늘 haraj에서 인기 있는 검색어는 뭐야?"

"حراج السيارات(자동차 카테고리)의 최신 게시물 20개를 가져와."

"지난주(during_date=1week) 동안 haraj에서 RTX 4090을 검색해."

"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개 도구), 라이브 version URL, 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에는 라이브 GraphQL 스키마에서 내가 환각(hallucination)으로 만들어 낸 4개의 도구(search_haraj, get_post, list_regions, check_auth)가 있었습니다. 지원되는 필터 중 상당수는 실제 사이트에서 사용되지 않았습니다.

v0.2.0은 이를 haraj.com.sa가 실제로 사용하는 작업을 그대로 반영한 21개 도구로 대체합니다. 2026-08-17의 실제 브라우저 세션(219개 요청, 173개 GraphQL POST)에서 캡처했습니다. 주요 수정 사항:

• search에는 더 이상 환각으로 생성된 필터(carExtraInfo, priceRange, userLocation, notTag, authorUsername)가 없습니다. 라이브 사이트가 실제로 보내는 변수(search, cities, city, tag, tags, page, limit, onlyWithImage, onlyWithVideo, hideShowRooms, orderByPostId, duringDate, near)만 있습니다.

• searchSuggest는 라이브 통신의 오타 initalChars를 보존합니다(서버에서 필요함).

• version URL 매개변수가 2026-08-11 22로 상향되었습니다(이전 2026-08-03 15).

• sec-ch-ua-platform-version 헤더 추가(모든 라이브 호출에 전송)

• ViewOptions에 mustLoginToView 포함(posts 작업에만 존재)

• GraphQL이 아닌 livestream.haraj.com.sa 엔드포인트를 위한 새 live_streams 도구

• get_post_details는 이제 ID를 키워드로 사용하는 임시 방편이 아닌 올바른 similarPosts(id:) 엔드포인트를 사용합니다.