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

服务器从 cwd 读取 .env，因此密钥保留在项目目录中，不会泄露到你的 MCP 客户端配置中。

自定义 .env 位置

在 MCP 配置的 env 块中设置 HARAJ_MCP_ENV=/path/to/.env。

示例智能体提示

接入后，你的智能体可以回答：

今天 haraj 上有什么热门内容？

获取 حراج السيارات（汽车分类）中最新 20 个帖子。

搜索 haraj 上最近一周（during_date=1week）的 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 有 4 个工具（search_haraj、get_post、list_regions、check_auth），这些工具是我从实时 GraphQL schema 中臆造出来的——其中许多受支持的过滤器从未被真实网站使用过。

v0.2.0 用 21 个工具 替换了它们，这些工具镜像了 haraj.com.sa 实际使用的操作。这些操作是从 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 操作中）

• 新增 live_streams 工具，用于非 GraphQL 的 livestream.haraj.com.sa 端点

• get_post_details 现在使用正确的 similarPosts(id:) 端点（而不是将 ID 当作关键词的黑客做法）