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 → Network タブ → 任意の graphql.haraj.com.sa リクエストをクリックします。

3. Headers で、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"
    }
  }
}

サーバーは .env を cwd から読み込むため、シークレットはプロジェクトディレクトリ内に留まり、MCP クライアント設定に漏れません。

カスタム .env の場所

MCP 設定の env ブロックで HARAJ_MCP_ENV=/path/to/.env を設定します。

エージェント向けのプロンプト例

組み込み後、エージェントは次のような質問に答えられます:

「今日の 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ツール)、ライブ 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 スキーマから私が捏造した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 は正しい similarPosts(id:) エンドポイントを使用するようになりました(IDをキーワードとして使うハックではなく)