4Sale MCP Server (forsale-mcp)

An extensive, read‑only Model Context Protocol server that exposes Kuwait's 4Sale marketplace (q84sale.com) to LLM agents through 62 well‑described tools — search, listings, sellers & reputation, taxonomy, attributes, location & commute intelligence, attribute‑aware car search, market intelligence, fraud & negotiation helpers, promotions, server‑driven UI, diagnostics, and (optionally) authenticated account endpoints — plus a standalone price‑drop watcher (watch.py).

It is a much larger sibling of opensooq-mcp, built by reverse‑engineering 4Sale's private web API from a captured browser session. The request‑signing scheme, the full category taxonomy and every endpoint below were derived from that capture and verified against the live API (the signer matched 71/71 captured requests and returns live data; the live diagnostic passes 15/15).

⚠️ Responsible use (please read)

4Sale (q84sale.com) is a real, live website. This project is an unofficial, educational, read‑only API client intended for personal research and interoperability — it issues the same public calls a browser makes and never posts, edits, deletes, logs in on your behalf, or unmasks private data.

• Respect 4Sale's Terms of Service and Kuwaiti law.

• Do not scrape at scale. The client deliberately paginates modestly, retries with backoff, and enters a local cooldown when throttled. Keep volume low.

• Authenticated tools require your own token; nothing here bypasses auth.

• The API enforces anti‑abuse rate limiting (HTTP 403/429). If you hit it, the tools tell you to back off — please do.

Related MCP server: eBay MCP Server

What it's for — real questions, with vs without the MCP

Below are genuine things a 4Sale user in Kuwait would ask. For each, the first answer is what a normal assistant says with no marketplace access; the second is what it can do with this MCP. (Figures in the "with" answers are pulled live and will vary — they're shown to illustrate the shape of the result.)

1. "I'm selling my 2019 Toyota Camry — what should I list it for?"

Without the MCP:

I can't see live 4Sale prices. As a rough guide a 2019 Camry in Kuwait might be somewhere around 3,000–4,500 KWD depending on mileage and trim — but please check q84sale.com for current listings to be sure.

A vague, possibly stale band with a disclaimer — no real comparables.

With the MCP → forsale_car_market("Toyota","Camry") + forsale_appraise("Toyota Camry 2019"):

From 41 live comparable Camry listings (English + Arabic), 2019 models sit at a median of 3,650 KWD (typical p25–p75 band 3,200–4,100). Depreciation curve right now: 2022 → 5,400 · 2020 → 4,250 · 2019 → 3,650 · 2017 → 2,900. To sell within a week, list at ~3,500 (just under median); the cheapest comparable today is 3,100 KWD.

2. "Find me an iPhone 15 Pro under 250 KWD."

Without the MCP:

I'm not able to browse 4Sale. You could search "iPhone 15 Pro" on q84sale.com and filter by price — sorry I can't pull the listings for you.

With the MCP → forsale_search_bilingual("iphone 15 pro", category_id=99) (also searches ايفون 15 برو):

18 matching listings under 250 KWD. The English query alone returned 6; adding the Arabic term surfaced 12 more Arabic‑only posts. Cheapest: "iPhone 15 Pro 256GB" — 235 KWD in Salmiya (link). Most are 240–290 KWD.

The bilingual trick is the difference between 6 results and 18.

3. "I work in Kuwait City. Find 2‑bedroom apartments for rent within a 20‑minute drive, under 400 KWD."

Without the MCP:

I can't access live listings or compute drive times. Generally Sharq, Salmiya and Hawally are close to the city — try filtering 4Sale by those areas.

With the MCP → forsale_listings_within_drivetime("Kuwait City", max_minutes=20, query="apartment for rent"):

14 apartments within ~20 min: Sharq (~3 min, 2 listings 380–400 KWD), Dasma (~5 min), Salmiya (~15 min, several 350–400 KWD), Jabriya (~13 min). Sorted by ETA with map links — Salmiya offers the most 2BRs in your budget.

4. "Which area has the cheapest furnished apartments for rent?"

Without the MCP:

Prices vary a lot; outer areas like Mahboula or Mangaf are usually cheaper than Salmiya or the city — but I can't give live medians.

With the MCP → forsale_price_by_area("furnished apartment for rent") / forsale_cheapest_area(...):

Live median rent by area: Mahboula 240 KWD (cheapest, 22 listings) · Mangaf 260 · Fintas 290 · Salmiya 420 · Sharq 480. Mahboula is ~45% cheaper than Salmiya for furnished 1‑BRs right now.

5. "I found a PlayStation 5 for 60 KWD — seems too cheap. Is it legit?"

Without the MCP:

That does sound low. General scam tips: meet in person, don't pay in advance, check the seller's history… (generic advice).

With the MCP → forsale_scam_risk(adv_id=…) + forsale_seller_reputation(adv_id=…):

⚠️ Risk score 70/100 (high). Reasons: asking 60 KWD is <50% of the ~135 KWD market median; seller is not verified; account is 11 days old; contact number hidden; only 1 image. Treat with caution — insist on in‑person cash handover.

6. "This phone seller looks professional — what else are they selling?"

Without the MCP:

4Sale doesn't show a public 'all listings by user' page that I can read, so I can't list their other items.

With the MCP → forsale_seller_listings_by_phone(adv_id=…, category_id=99) + forsale_detect_dealer(...):

That phone number appears on 23 active listings in Mobiles — verdict: dealer (posing as a private seller). They're mostly selling Samsung S24/S26 and iPhone 15/16 units, 145–440 KWD. Here are all 23 with prices.

7. "I'm looking at this used GMC Yukon listing — how much should I offer?"

Without the MCP:

Aim a bit below asking and negotiate — maybe 5–10% off. (No live market context.)

With the MCP → forsale_negotiation_advisor(adv_id=…):

Asking 8,900 KWD vs market estimate ~8,100 (medium confidence) → +9.9%, above market. Suggested opening offer 7,300, target 8,100. Talking point: "comparable Yukons are listed near 8,100 — would you do 8,000 cash today?"

8. "Tell me when a used Nissan Patrol under 5,000 KWD gets posted."

Without the MCP:

I can't monitor listings for you — you'd need to check 4Sale periodically.

With the MCP → watch.py --add-search "used nissan patrol" --category 116 --max-price 5000, then on a schedule:

🆕 New: "Nissan Patrol 2016 GCC" — 4,800 KWD in Jahra (posted 12 min ago) · ⬇️ Price drop: "Patrol Platinum" 5,200 → 4,950 KWD. Plus forsale_fresh_deals("nissan patrol", category_id=116) for under‑market posts in the last 24h.

More it answers that a plain assistant can't: "What's trending on 4Sale right now?" (forsale_trending/forsale_demand_index) · "Find verified electronics shops selling mobiles" (forsale_find_business_profiles) · "Is a used iPhone 14 or 15 better value today?" (forsale_compare_terms) · "Are there any active promo codes?" (forsale_valid_promo_codes → e.g. WELCOME25, 25% off) · "What filters exist for used cars?" (forsale_get_category_attributes).

The throughline: without the MCP the assistant guesses from stale training data or sends you to the website; with it, every answer is grounded in live Kuwait listings, in both Arabic and English.

Architecture

MCP client  ↔  server.py        (62 tools, validation, slimming, structured errors)
                   ↔  forsale_client.py   (signing + HTTP + retry/cooldown + health; zero MCP deps)
            reference.py  (offline 509‑node taxonomy, EN↔AR dict, car makes, region data)
            geo.py        (Kuwait governorates/areas, haversine, drive‑time)
            data/categories.json   (cached taxonomy)
            watch.py      (standalone cron price‑drop watcher)
            troubleshoot.py        (live diagnostic harness)

The request‑signing scheme

Every private‑API call carries these headers:

Application-Source: q84sale
Version-Number:     web
Device-Id:          web_user_<uuid>
X-Custom-Authorization: com.forsale.forsale.web <unix_ts> <sha1_hex>

where:

ek  = "/" + last‑3‑segments‑of( path [+ "?" + querystring] )
eL  = JSON.stringify(body)   for write requests,  else  '""'
msg = "com.forsale.forsale.web:" + ek + ":" + eL + ":" + ts + ":" + SECRET
sig = sha1( base64( utf8(msg) ) )

ts/sig are recomputed on every attempt so they never go stale.

Error‑handling strategy

Every tool returns a structured error dict instead of raising — the agent always gets {error, error_type, status, hint} (plus endpoint, and retry_after when relevant). Failures are classified into a typed hierarchy:

Layers of defense:

1. Retry with backoff — transient 403/429/5xx and transport errors are retried up to max_retries (default 2) with linear backoff; signature is re‑signed each attempt.

2. Local cooldown circuit‑breaker — on a rate‑limit hit the client records a cooldown_until (default 90 s). Subsequent calls fail fast with a clear rate_limited error instead of hammering the anti‑abuse layer and extending the block. forsale_health_check bypasses the cooldown to probe.

3. Envelope normalisation — the legacy monolith returns HTTP 200 with {status: 4xx, error:{…}}; the client detects this and classifies it correctly.

4. Graceful aggregation — multi‑call tools (market stats, geo, seller) skip individual failures rather than aborting, and per‑sub‑call errors are surfaced under *_error keys.

Health & rate‑limit monitoring

• forsale_health_check() — actively probes two cheap endpoints (a signed GET and a signed POST), bypassing the cooldown, and returns overall status ∈ {ok, degraded, rate_limited, down}, per‑endpoint results, average latency, remaining cooldown, the active device_id, and a recommendation. Call this first whenever tools start failing.

• forsale_api_status() — a no‑network snapshot of the client's telemetry: request/error counts, last latency, last error + type, and whether a local cooldown is active.

Example forsale_health_check output:

{ "status": "ok", "recommendation": "API reachable and signing valid.",
  "checks": [ {"endpoint": "GET v1/promo/...", "ok": true, "latency_ms": 795},
              {"endpoint": "POST V4/Trends/getTrends", "ok": true, "latency_ms": 165} ],
  "avg_latency_ms": 480, "cooldown_remaining_s": 0.0, "device_id": "web_user_…" }

Tool reference (62)

All tools are async, read‑only, and return a JSON object. lang is en/ar (default en); region_id defaults to 1 (Kuwait).

Diagnostics

forsale_health_check()

Active connectivity + signing + rate‑limit probe (see above). Returns: {status, recommendation, checks[], avg_latency_ms, cooldown_remaining_s, device_id, telemetry}.

forsale_api_status()

No‑network telemetry snapshot. Returns: {device_id, cooldown_remaining_s, in_cooldown, requests, errors, rate_limited_hits, last_status, last_latency_ms, last_error, last_error_type}.

Search & discovery

forsale_search(query="", category_id=None, sorting="newest", page=1, page_size=18, region_id=1, lang="en")

Core listing search (advancedSearch). Provide query and/or category_id. sorting ∈ newest|oldest|price_asc|price_desc. Returns: {total, pages, page, count, items[]}; each item {id, title, price, district_name, image, url, …}.

forsale_search_bilingual(query, category_id=None, pages=1, region_id=1, sorting="newest")

Searches the English term and its Arabic equivalent, merges & de‑dupes by id — maximises coverage (most listings are Arabic‑only). Returns: {query_en, query_ar, count, items[]}.

forsale_autocomplete(query, lang="en")

Keyword suggestions, each mapped to a listing_category and predefined_filters (category/sub_category ids) — use those for precise searches. Returns: {suggestions[]}.

forsale_browse_category(category_id, sorting="newest", page=1, page_size=18, region_id=1, lang="en")

Browse all listings in a category, no keyword (getListings). Returns: {total, pages, page, count, items[]}.

forsale_latest_listings(page=1, page_size=18, region_id=1, lang="en")

Newest listings across the whole marketplace. Returns: {total, pages, page, count, items[]}.

forsale_trending(lang="en")

Currently trending search terms (bilingual). Returns: {title:{ar,en}, trends:[{ar,en}]}.

forsale_recommended_listings(adv_id, category_id, region_id=1, lang="en")

Recommendation engine — related/similar listings for a listing. Returns: {total, pages, count, items[]}.

forsale_search_cards(category_id, query, lang="en")

Sponsored/marketing cards shown for a search (campaign banners, lead‑gen). Returns: {cards[]}.

forsale_map_recommended_listings(category_id, lang="en")

Map‑based recommended listings for a category. Returns: recommendation payload {listings:{…}, …}.

Listings

forsale_get_listing(adv_id, lang="en")

Raw full listing record by id. Returns: {id, title, description, price, contact_no, images[], geotag_lat, geotag_lon, district_id, …}.

forsale_get_listing_details(adv_id, lang="en")

Rich detail: bilingual description, dynamic attributes (attrs), category breadcrumbs, district, geotag, images, bundle/plan and the seller user_id. Returns: the detail object.

forsale_get_listing_stats(listing_id, lang="en")

Engagement: quality score (0–100), CTA count, and the live view counter. Returns: {listing_id, score:{listing_score, ctas_count}, views:{user_views_count}}.

forsale_listing_full_report(adv_id, lang="en")

One‑shot rich report: full details + stats + seller reputation + similar listings. Returns: {adv_id, details, seller, stats, similar}.

Sellers & reputation

forsale_get_seller_profile(slug, lang="en")

Verified business/shop profile by slug (e.g. unlimited-tech-474). Returns: {id, user_id, name, slug, logo, member_since, contact_numbers, is_verified, is_booking_enabled, …}.

forsale_find_business_profiles(category_ids, lang="en")

Verified shops operating in the given category id(s), with each shop's matched‑item count. category_ids is a list, e.g. [99]. Returns: {profiles[]}.

forsale_get_listing_seller(adv_id, lang="en")

Resolve the seller behind a listing. Returns: {user_id, name, is_verified, user_type, member_since, listings_count, business_profile_slug, risk_flags[]}.

forsale_seller_reputation(slug=None, adv_id=None, lang="en")

Trust assessment. Pass a business‑profile slug (preferred for shops) OR a listing adv_id (any seller). Returns: verification, account age, inventory size, trust_signals and risk_flags.

forsale_seller_service_ads(listing_id, user_id, category_id, lang="en")

Other service ads by the same provider (service categories). Get user_id/category_id from forsale_get_listing_details. Returns: {services[]}.

Seller inventory & fraud

forsale_seller_listings_by_phone(phone=None, adv_id=None, query="", category_id=None, pages=4)

Enumerate an individual seller's inventory by grouping on contact phone — the practical "all listings by a seller" (4Sale has no public member feed). Provide a phone, or an adv_id whose phone is looked up. Scope with query/category_id for recall. Returns: {phone_tail, scope, listings_found, listings[]}.

forsale_detect_dealer(adv_id, category_id=None, pages=4)

Is a "private" seller really a dealer? Counts listings sharing the phone in the category. Returns: {adv_id, phone_tail, listings_with_same_phone, verdict ∈ individual|active_seller|dealer}.

forsale_scam_risk(adv_id, category_id=None)

Heuristic scam‑risk score (0–100): below‑market price + unverified/new seller + hidden contact + few images + thin description. Educational signal, not a verdict. Returns: {risk_score, risk_level, asking_price, market_estimate, reasons[], disclaimer}.

Cars (attribute‑aware)

forsale_search_cars(make, model="", year_min=None, year_max=None, price_min=None, price_max=None, max_mileage=None, condition="used", sorting="newest", pages=3)

Resolves make→category and model→sub‑category (server‑side, bilingual), then filters by price, model year and mileage parsed from each listing. condition ∈ used|new. Year/price filters drop listings whose value can't be parsed; the mileage filter only drops when a value is found. Returns: {make, model, condition, resolved_category, resolved_sub_category, filters_applied, count, cars[]} (cars include parsed year, mileage_km).

forsale_car_models(make)

Models (sub‑categories) for a make, via autocomplete. Returns: {make, models:[{model, category, sub_category}]}.

forsale_car_market(make, model="", condition="used", pages=3)

Car market analysis: overall price stats plus a price‑by‑model‑year breakdown (a rough depreciation curve). Returns: {make, model, resolved_category, sample, overall:{min,max,avg,median,p25,p75}, by_year:[{year,count,median_price}]}.

forsale_car_attributes(condition="used", lang="en")

Live attribute schema for the cars category (make/model/year/mileage/transmission fields). Returns: {category_id, attributes}.

Location intelligence

forsale_list_areas()

Kuwait governorates + ~58 known areas (Arabic names + coordinates) usable as place names. Returns: {governorates[], areas[]}.

forsale_resolve_area(name)

Resolve a place name (EN/AR) → coordinates + governorate. Returns: {name, name_ar, type ∈ area|governorate, governorate, lat, lon}.

forsale_get_districts(region_id=1, lang="en")

Live 4Sale district/governorate master list. Returns: {districts}.

forsale_get_subdistricts(district_id, lang="en")

Child districts of a district id. Returns: {districts}.

forsale_listing_location(adv_id, lang="en")

Pin a listing on the map: geotag, nearest known area & governorate, Google Maps link, district id. Returns: {adv_id, title, price, lat, lon, district_id, maps_link, nearest:{area, governorate, distance_km}}.

forsale_listings_near_place(place, query="", category_id=None, radius_km=5.0, pages=2, precise=False, max_precise=12)

Listings within radius_km of a Kuwait place. Default uses each listing's area centroid (fast, no extra calls); precise=True fetches exact geotags for up to max_precise listings. Returns: {center, radius_km, mode, count, listings[]} (each with approx_distance_km, or distance_km in precise mode).

forsale_price_by_area(query, category_id=None, pages=3, region_id=1)

Price heatmap: median price + count per area for an item (bilingual, outlier‑trimmed). Returns: {query, areas_covered, by_area:[{area, listings, median, min, max}]} (sorted cheapest→priciest).

forsale_listing_density_by_area(query="", category_id=None, pages=3, region_id=1)

Supply map: listing count per area (where inventory concentrates). Returns: {query, sample, areas:[{area, listings}]}.

forsale_cheapest_area(query, category_id=None, pages=3)

Which area has the lowest median price for an item (areas with ≥2 listings). Returns: {query, cheapest, priciest, ranked[]}.

forsale_compare_areas(query, areas, category_id=None, pages=3)

Compare price & supply across specific areas (relocation / buy‑where). areas is a list of names. Returns: {query, comparison:{area: {listings, median, …}}}.

Commute / drive‑time

forsale_listings_within_drivetime(destination, max_minutes=20, query="", category_id=None, avg_speed_kmh=45, pages=2)

Listings within an estimated N‑minute drive of a destination (road‑detour speed model over area centroids; not live traffic). Sorted by ETA. Returns: {destination, max_minutes, avg_speed_kmh, count, listings[]} (each with approx_km, est_drive_min).

forsale_commute_estimate(adv_id, destination, avg_speed_kmh=45, lang="en")

Driving distance & ETA between a specific listing (precise geotag, falls back to district centroid) and a destination. Returns: {adv_id, title, destination, location_source, distance_km, est_drive_min, maps_link}.

Taxonomy & attributes

forsale_list_verticals()

The 14 top‑level categories with ids + EN/AR names. Returns: {verticals:[{id, name_en, name_ar, slug}]}.

forsale_list_category_children(category_id)

Direct children of a category (from the cached 509‑node tree), sorted by listing volume. Returns: {parent, children:[{id, name_en, name_ar, slug, listings_count, is_leaf, slug_url}]}.

forsale_resolve_category(query, limit=12)

Fuzzy EN/AR name/slug → category ids. Returns: {matches:[{id, name_en, name_ar, slug, parent_id, listings_count, slug_url}]}.

forsale_get_category_info(category_id, region_id=1, lang="en")

Live category metadata + marketing description. Returns: category object {en_name, name, en_description, …}.

forsale_get_category_attributes(category_id, region_id=1, lang="en")

Live attribute schema for a category (filters/fields, dropdowns, ranges, booleans). Returns: attribute schema.

Market intelligence

forsale_price_stats(query, category_id=None, pages=2, bilingual=True, region_id=1)

min/max/avg/median/p25/p75 over a sample (bilingual, outlier‑trimmed) + cheapest & priciest matches. Returns: {query, sample_size, priced, stats, cheapest, priciest}.

forsale_price_distribution(query, category_id=None, buckets=6, pages=2, region_id=1)

Price histogram across buckets ranges. Returns: {query, min, max, buckets:[{range:[lo,hi], count}]}.

forsale_find_deals(query, category_id=None, below_pct=25, pages=3, region_id=1)

Listings priced at least below_pct% under the median. Returns: {query, median, threshold, count, deals[]}.

forsale_fresh_deals(query, category_id=None, hours=24, below_pct=15, pages=4)

Newly posted (last hours) listings priced under market — first‑mover sniping. Returns: {query, market_median, hours, below_pct, count, deals[]} (each with pct_below_median).

forsale_compare_terms(terms, category_id=None, pages=2, region_id=1)

Compare volume + price stats across multiple item terms. terms is a list (≤5). Returns: {comparison:{term: {listings, stats}}}.

forsale_appraise(query, category_id=None, pages=3)

Fair‑value estimate from comparables: median value, typical band (p25–p75), full range, sample size, confidence. Returns: {query, estimated_value, typical_range, full_range, sample_size, confidence}.

forsale_market_pulse(lang="en")

Quick snapshot: trending terms + a sample of the latest listings + active promo codes. Returns: {trending, latest, promos}.

Negotiation & coverage helpers

forsale_negotiation_advisor(adv_id, category_id=None)

Compares a listing's asking price to the market and suggests an opening offer + target + talking points. Returns: {adv_id, title, asking_price, market_estimate, vs_market_pct, assessment, suggested_opening_offer, suggested_target, talking_points[]}.

forsale_arabic_variants(term)

Generate Arabic spelling variants (alef/hamza, ya/alef‑maqsura, ta‑marbuta) to run several searches and catch differently‑spelled listings. Returns: {input, arabic, variants[], source}.

Trends, promotions, SDUI

forsale_demand_index(enrich=False)

"What's hot" index from trending searches. With enrich=True, fetches live result counts per trend (slower) and ranks by demand. Returns: {trending_count, index:[{term, ar, listings?}]}.

forsale_top_viewed(region_id=1, lang="en")

Most‑viewed listings (Analytics/getTopViewed). Returns: API payload (may be null when unavailable).

forsale_valid_promo_codes(lang="en")

Currently active promo/discount codes. Returns: {promo_codes:[{promo_code, discount_type, discount_value, max_discount, expiry_date, …}]}.

forsale_sdui_component(name="floating-timer-banner", os_name="web", version=1, lang="en")

Fetch a Server‑Driven UI component spec — component, action/deeplink and analytics directives. Returns: {component, action, analytics, …}.

forsale_core_cards(screen_name, adv_id, category_id=None, lang="en")

Contextual SDUI cards for a screen (e.g. screen_name="listing_details_screen"). Returns: {cards[]}.

Geography & translation

forsale_list_regions()

Region ids usable as region_id. Returns: {regions:[{id, en, ar}]}.

forsale_translate_term(term)

English → Arabic search term (+ matching category names). Word‑level for multi‑word inputs (e.g. "iphone 15" → "ايفون 15"). Returns: {input, arabic, source, category_matches[]}.

Authenticated (optional Bearer token)

Pass a token via the auth_token argument or the FORSALE_AUTH_TOKEN env var. Anonymous sessions return an auth error.

forsale_my_account(auth_token=None, lang="en")

The signed‑in user's account profile.

forsale_my_favorites(auth_token=None, page=1, lang="en")

The signed‑in user's saved/favorite listings.

The bilingual coverage trick 🔑

Most 4Sale listings are titled in Arabic only, so an English‑only search misses them. forsale_search_bilingual, forsale_price_stats, forsale_find_deals, forsale_fresh_deals, forsale_compare_terms, forsale_appraise, forsale_price_by_area and the car tools automatically query both the English term and its Arabic equivalent (via forsale_translate_term) and merge — typically a large increase in coverage. For tricky spellings, expand further with forsale_arabic_variants.

Price‑drop watcher (watch.py)

A standalone, cron‑ready watcher (httpx only, no MCP) that tracks searches or specific listings between runs and reports price drops/rises, new listings and removed listings. State lives in watch_state.json; watches in watches.json (auto‑created with an example).

python watch.py --add-search "used nissan patrol" --category 116 --max-price 5000
python watch.py            # run all watches, print alerts, update state
python watch.py --json     # machine-readable alerts
python watch.py --list     # show configured watches

Schedule every 30–60 min (cron / Task Scheduler). Example output:

## iPhone 15 under 200 KWD
   ⬇️  iPhone 15 128GB  185 → 165 KWD  (-20)  https://www.q84sale.com/en/listing/...
   🆕  iPhone 15 Plus    190 KWD        https://www.q84sale.com/en/listing/...

Setup — quick start (3 steps)

Works with any MCP‑capable agent: Claude Desktop, Cursor, Windsurf, Google Antigravity, VS Code (Copilot), Cline, Zed, and more.

Step 1 — Get the code

git clone https://github.com/isaamthalhath07/4sale-mcp.git
cd 4sale-mcp

Step 2 — Install dependencies

Pick one (Python 3.10+ required):

# Option A — uv (recommended; no manual venv)
uv sync            # or: uv pip install -r requirements.txt

# Option B — pip
pip install -r requirements.txt

Step 3 — Smoke‑test it (optional but recommended)

python troubleshoot.py

You should see [HEALTH] status=ok … and a column of [PASS] lines. If so, you're ready to connect it to your agent below.

Connect it to your LLM agent

Every client uses the same idea: add a server entry that tells the client how to launch server.py. Use the uv block if you installed with uv, or the python block if you used pip. Replace /ABSOLUTE/PATH/TO/4sale-mcp with the real path where you cloned the repo (e.g. C:\\Users\\you\\4sale-mcp or /Users/you/4sale-mcp).

uv block:

{
  "mcpServers": {
    "forsale": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/4sale-mcp", "server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

python (pip) block — use the full path to your Python if python isn't on PATH:

{
  "mcpServers": {
    "forsale": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/4sale-mcp/server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

💡 Shortcut: run python install.py from the repo and it will auto‑detect Claude Desktop / Cursor / Windsurf and write the correct block for you. Use python install.py --print to just print the block to paste anywhere.

Claude Desktop

1. Open the config file (create it if missing):

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Paste the block above (merge into any existing "mcpServers").

3. Fully quit and reopen Claude Desktop. The 🔌/tools icon should show forsale.

Cursor

1. Settings → MCP → Add new global MCP server (or edit ~/.cursor/mcp.json; for one project use <project>/.cursor/mcp.json).

2. Paste the block.

3. Reload — the server appears under Settings → MCP with a green dot. Ask in Agent/Composer chat.

Windsurf

1. Open ~/.codeium/windsurf/mcp_config.json (or Settings → Cascade → MCP Servers → Manage → View raw config).

2. Paste the block and save.

3. Click Refresh in the MCP panel. Use the tools from Cascade.

Google Antigravity

1. Open Settings → MCP / Tools (the MCP servers panel) and choose Add server / Edit config (JSON).

2. Paste the same "mcpServers" block (Antigravity uses the standard MCP config schema). Save.

3. Reload the workspace; the forsale tools become available to the agent.

VS Code (GitHub Copilot — native MCP)

VS Code uses a slightly different key (servers, not mcpServers). Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "forsale": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/4sale-mcp", "server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Then open Copilot Chat → Agent mode and pick the tools.

Cline (VS Code extension)

Cline → MCP Servers → Configure MCP Servers → add the standard "mcpServers" block to cline_mcp_settings.json, then toggle the server on.

Any other MCP client (Zed, LibreChat, custom)

They all accept a command + args. Point the command at uv run --directory <path> server.py (or python <path>/server.py). Transport is stdio.

First things to ask your agent

• "Run a 4Sale health check."

• "Search 4Sale for an iPhone 15 in both English and Arabic, cheapest first."

• "What's the median price of a used Nissan Patrol in Kuwait right now?"

• "Find 2‑bedroom apartments within a 20‑minute drive of Kuwait City under 400 KWD."

Optional environment variables

Add them under the "env" object of your server block, e.g. "env": { "PYTHONIOENCODING": "utf-8", "FORSALE_DEVICE_ID": "web_user_my-id" }.

Troubleshooting the connection

• Server doesn't appear / "failed to start": the command isn't on the client's PATH. Use an absolute path to uv/python, and an absolute --directory.

• Tools error with rate_limited: you've been throttled — wait, or set a fresh FORSALE_DEVICE_ID. Run forsale_health_check to confirm.

• Arabic shows as ????: ensure PYTHONIOENCODING=utf-8 is in env.

• Re‑run python troubleshoot.py to confirm the server itself is healthy independent of the client.

Verifying it works (troubleshoot.py)

python troubleshoot.py

Runs offline taxonomy checks, a health check, then ~12 live endpoint probes, printing PASS / FAIL / RATE-LIMITED / AUTH-FAIL / NOT-FOUND per check with the actionable hint. Sample:

[PASS] offline categories: 509 nodes, 14 verticals
[HEALTH] status=ok avg_latency=364ms cooldown=0.0s — API reachable and signing valid.
[PASS] advancedSearch (en): total=347
[PASS] advancedSearch (ar): ar='ايفون' total=333
...

If you see RATE-LIMITED, the anti‑abuse layer has temporarily blocked your IP/device — wait a few minutes and/or set a fresh FORSALE_DEVICE_ID.

Limitations & notes

• Read‑only; no posting/editing/deleting.

• Kuwait market (region_id = 1).

• Unofficial API — endpoints/signing can change; re‑verify with troubleshoot.py / forsale_health_check.

• Rate limiting — keep volume modest; the client backs off and cools down.

• Drive‑times are estimates (straight‑line × detour factor ÷ avg speed), not live traffic.

• A regular member's complete inventory isn't a public endpoint; the phone‑grouping tools approximate it within a search scope.

• Area coordinates are approximate centroids — good for proximity/comparison, not survey‑grade geocoding.