divar-mcp 0.1.0__tar.gz

divar_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q

divar_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish
+
+# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
+# pyproject.toml and server.json.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+      contents: write  # GitHub Release
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Check versions match the tag
+        run: |
+          TAG=${GITHUB_REF_NAME#v}
+          grep -q "^version = \"$TAG\"" pyproject.toml
+          test "$(jq -r .version server.json)" = "$TAG"
+          test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
+      - run: uv sync --locked && uv run pytest -q
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  mcp-registry:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # MCP Registry login via GitHub OIDC
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - name: Wait for PyPI to serve the new version
+        run: |
+          for i in $(seq 1 30); do
+            curl -sf "https://pypi.org/pypi/divar-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
+            sleep 10
+          done
+          exit 1
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - run: ./mcp-publisher login github-oidc
+      - run: ./mcp-publisher publish

divar_mcp-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.ruff_cache/
+VERIFY_REPORT.md

divar_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,111 @@
+# divar-mcp
+
+Unofficial, read-only MCP server for Divar (divar.ir), Iran's classifieds site (real estate, cars, phones, jobs, services).
+Repo: GitHub `sepehr071/divar-mcp`. Not released yet: no PyPI or MCP Registry release (planned PyPI name `divar-mcp`).
+It is a sibling of `../fidibo-mcp` and `../digikala-mcp` and copies their layout and idioms; keep them in step.
+
+API map this server is built on (endpoints, samples, quirks, test report, competitor checklist): `../divar/`.
+
+## Layout
+
+- `src/divar_mcp/http.py`: the only HTTP code. One shared `httpx.AsyncClient` (`trust_env=False`, proxy only from
+  `DIVAR_MCP_PROXY`), a concurrency semaphore, `api(path, body=None)` for the gateway `https://api.divar.ir/v8` (GET, or
+  POST when `body` is given: every Divar POST used here is a read-only query), one retry (fixed 0.5 s, `RETRY_DELAY`) on
+  dropped connections, an empty 200 body and 502/503/504, no redirects followed, `ApiError(ToolError)` (passes on the API's
+  own `message` for 400/404), `set_transport()` for tests.
+- `core.py`: not a tool module. Persian `fold`, price parsing (`to_int`, `short_toman`), `price_flags`, `row_prices`, `card`
+  (a POST_ROW -> compact ad), `dist` / `sane` statistics, cached reference data (cities, categories, filter schemas,
+  districts; 1 h, `_CACHE`), resolvers (`resolve_cities`, `resolve_category`, `resolve_districts`), `build_query` (friendly
+  args -> Divar search, reports `ignored` filters), `fetch_cards` (the paged loop) and the shared `Annotated` parameter types.
+- `registry.py`: `@tool("Title")` collects tools. `server.py`: registers them with read-only annotations, holds `INSTRUCTIONS`.
+- Tools: `places.py` (cities, districts, neighbours, locate, place search, mapping), `catalog.py` (categories, filters,
+  filter options, suggest), `search.py` (search, count, cheapest, best for budget, find deals, new since, export, nearby), `post.py`
+  (post, posts, compare, seller, dealer, similar; `parse_post`, `comparables`), `market.py` (market, appraise),
+  `watch.py` (saved watches, price trend; the only tools that write, to the local file of `store.py`), `meta.py` (status).
+  `places.py` also has `dv_boundary` (GeoJSON), `catalog.py` `dv_parse_query` (rule-based text -> dv_search args).
+  31 tools, all `dv_*`. `server.py` also registers MCP resources (`divar://cities`, `categories`, `category-filters/{slug}`)
+  and prompts. No `outputSchema` on purpose (a test checks it): tools return one compact JSON text block.
+  Token budget: `server._rows` trims every ad row on the way out (no `image` unless the call has `thumbnails=true`,
+  no `posted` next to `age_h`, no false/empty values), and `_untitled` flattens optional `anyOf [X, null]` schemas and
+  dedents descriptions. Shared parameter descriptions in `core.py` stay one short line: they repeat across 11 tools.
+- `tests/`: `test_<module>.py` unit tests (MockTransport + trimmed real fixtures in `tests/fixtures/`, clock frozen in
+  `conftest.py`), `test_live_<group>.py` live tests (`@pytest.mark.live`), `test_http.py` for the client and the README tool tables.
+
+## Commands
+
+uv needs the local proxy to download packages; the server and tests call Divar directly (env proxies are ignored).
+
+```bash
+export HTTPS_PROXY=http://127.0.0.1:10898 HTTP_PROXY=http://127.0.0.1:10898
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run pytest -q            # unit tests, offline
+uv run pytest -m live -q    # one live test per tool, about 25 s
+```
+
+## Rules for changes
+
+- Read-only on Divar. The two `local=True` tools (`dv_watch`, `dv_price_trend`) write only `~/.divar-mcp/state.json`
+  (`DIVAR_MCP_STATE`) and are annotated not-read-only. Never call login/OTP (`/v5/auth`), `postcontact` (seller phone), chat, bookmarks, notes, ad submission or
+  drafts, payments, the business panel, or any analytics beacon (`/v1/client-exporter`). Seller phone numbers stay out of scope.
+- Output units: prices in **Toman** (the API is Toman; nothing to convert). Card: `price` = sale price; rentals `deposit`
+  and `rent` (`rent` 0 + `full_deposit` = رهن کامل, from "رهن کامل" rows); no price key = negotiable (`negotiable` true when
+  the seller wrote توافقی or 0); `suspect_price` list = `tiny`, `placeholder`, `absurd`, `tiny_rent`. `slim` drops
+  None / false / empty values (0 stays; `ads` lists stay even when empty). Rankings use `main_price` (sale price, else
+  rent) and skip suspect prices; statistics also drop prices under a tenth of the median (`sane`).
+- Tools never invent data Divar lacks: price ordering, appraisal, best value and trend are computed from fetched asking
+  prices and the answer says so (`scanned`, `comparable_ads`, `caveat`).
+- Filters are validated against the category's filter schema (`filter_specs`, cached): unknown keys go to `ignored`,
+  because Divar silently drops them. Value shapes: number_range (strings), repeated_string, str, boolean.
+- Slugs from API data go into paths only as validated tokens (`Token` pattern); user text is never put into a path.
+- New tool: `@tool("Title")` async function, every param `Annotated[..., Field(...)]` with constraints and an example,
+  docstring = what it returns + when to use + what to call next, compact dict output. Add a unit test with a real trimmed
+  fixture, a live test, a README tool-table row, and an `INSTRUCTIONS` mention.
+- Keep `README.md` tool tables equal to `list_tools()` (a unit test checks it). Deps stay `mcp` + `httpx` only.
+- Write ZWNJ as `\u200c` in code, never the invisible character.
+
+## Divar quirks (keep them)
+
+- No auth, token or header needed. Unknown paths and wrong HTTP methods answer `403 RBAC: access denied`, not 404.
+- List rows are protobuf-JSON widgets; `POST_ROW` is the ad card. Row prices are Persian-digit Toman strings; rent rows put
+  the deposit in `top_description_text` and rent in `middle_description_text` (`رهن کامل` = full deposit). The exact publish time
+  is `action_log.server_side_info.info.sort_date`; row text only has relative time.
+- `POST /v8/postlist/w/search` is newest first only; the first 1-3 rows can be promoted. Paging: send
+  `pagination_data {"@type": "type.googleapis.com/post_list.PaginationData", "last_post_date": <cursor>, "page": 2, "layer_page": 2}`;
+  the cursor is the previous response's `pagination.data.last_post_date`. `page: N` alone returns page 1.
+- Category slugs differ from web URL slugs (`car` = `light`, `buy-apartment` = `apartment-sell`); a wrong one is HTTP 400.
+  Web search URLs with API slugs 404 inconsistently (`house-villa-sell` 404s; `buy-apartment`, `rent-apartment`, `car`,
+  `mobile-phones` work), so `web_url` (`Q.web_url`) is built only for those categories, with `districts=1,2`, `price|credit|rent|size=min-max`
+  and `q=`, and is omitted for anything else.
+- Post detail (`/posts-v2/web/{token}`): `webengage.price/credit/rent` are float32-rounded for big numbers
+  (2,670,000,000 arrives as 2,670,000,128). The exact numbers are in the `UNEXPANDABLE_ROW` "قیمت پایه" / "ودیعه" / "اجارهٔ ماهانه"
+  rows; `parse_post` prefers them.
+- Filter option lists: `/v8/w/lazy-multi-select-hierarchy-options` (no `/postlist`), typed search `/v8/fields-search` (needs
+  `search_key`, e.g. `car_brand_model`; `count` is always 0). `reverse-geocode` needs the `location` key and 404s outside
+  covered districts. Dealer pages (`brand-landing`) give only the first 11 ads.
+- Map pins are fuzzed about 500 m; map price chips are rounded text ("۱٫۵ میلیارد"), parsed by `short_toman`. Sale pins
+  have two chips: "قیمت:" (total, `price`) and "متری:" (per m2, `price_per_m2`). `mapview/viewport` returns nothing without a
+  category. Post detail sale ads (homes) put the exact total in the "قیمت کل" row.
+- A province id (`parent` of a city) works as a search `city_ids` scope; there is no province list, so `city: "استان <city>"`
+  names the province of that city (no `web_url`: the site has no province address we could confirm). Typed brand search (`fields-search`) is fuzzy ('car' finds Kia Carens): `build_query`
+  keeps only hits that contain the typed text and validates keys against the option tree.
+- Business card of a personal ad: `business-data/{token}/lazy` answers 404 "business not found"; `dv_seller` treats that as
+  a personal seller. `/places/districts/{id}/neighbours` is short (Vanak lists only Jordan), so `dv_neighbours` adds `nearest`
+  by centroid distance. `webengage.business_ref` (17 chars) is not a `brand_token`; `dv_post` does not return it.
+- `dv_best_for_budget` / `dv_find_deals` skip ads under 20% of the uncapped market median and bait titles (`_IMPLAUSIBLE`, `_BAIT`, unless the
+  word is in the query). Property for sale is ranked per m2: list rows have no area, so it comes from the title, else from the ad page
+  (`with_areas`, at most 6 fetches: ~30 rapid post fetches got HTTP 429). Per-m2 values are cut to whole thousands like the site (`per_m2`).
+- `sort_date` / `age_h` is the last bump (نردبان), not the publication: only the ad page has the real time ("انتشار آگهی" /
+  "آخرین نردبان" Jalali lines, `published_at` / `bumped_at` via `jalali_time`). `rank_pool` opens the pages of the 6 best per-m2
+  ads to read it plus floor (زیرهمکف), "پارکینگ ندارد", "آسانسور ندارد", and rescales the score; unchecked ads get only +5 for a
+  recent bump. `dv_similar` drops property cards priced 5x off or with a title area 0.4x-2.5x off (`excluded_outliers`).
+- `dv_search` flags prices at or under a tenth of the fetched median as `outlier` (`flag_outliers`, needs 5 priced ads).
+- No rate limit was seen (40 searches in 15 s). Keep calls modest anyway: the semaphore allows 4 at once.
+- Not available: price valuation, a similar-ads endpoint (`dv_similar` searches the ad's breadcrumb), sort by price,
+  dealer paging, SEO slug routes, anything behind login.
+
+## Release (when it is time)
+
+Bump `version` in `pyproject.toml` and both versions in `server.json`, `git init`, create the GitHub repo, tag `vX.Y.Z`.
+`.github/workflows/publish.yml` (copied from fidibo-mcp, untested here) publishes to PyPI and the MCP Registry.
+Then check the server table in `../README.md` and `../../awesome-iran-mcp` (see `../CLAUDE.md`).

divar_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sepehr Radmard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

divar_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: divar-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for Divar (divar.ir): search classified ads in any Iranian city, compare, find the cheapest and best deals, appraise prices, browse the map.
+Project-URL: Homepage, https://github.com/sepehr071/divar-mcp
+Project-URL: Source, https://github.com/sepehr071/divar-mcp
+Project-URL: Changelog, https://github.com/sepehr071/divar-mcp/releases
+Project-URL: Issues, https://github.com/sepehr071/divar-mcp/issues
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cars,classifieds,divar,iran,mcp,model-context-protocol,persian,real-estate
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.2
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.sepehr071/divar-mcp -->
+
+# divar-mcp: Divar MCP server for AI agents
+
+**Unofficial, read-only MCP server that lets your AI agent search Divar (دیوار) ads in any Iranian city: homes, cars, phones and more. It finds the cheapest and best-value ads, compares ads, checks whether a price is fair and browses the map. Prices are in Toman.**
+
+An [MCP](https://modelcontextprotocol.io) server for [Divar](https://divar.ir), Iran's largest classifieds site.
+Search by city, neighbourhood, category, text and any of the category's filters, read a full ad, compare several, see
+the seller's other ads, get market statistics, appraise a price against similar ads and poll for new ads, all from
+Claude, Cursor or Copilot. No account, no API key, nothing is posted or changed.
+
+[Quick start](#quick-start) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
+
+---
+
+## For AI agents
+
+- **What:** Unofficial MCP server for Divar (دیوار, divar.ir), Iran's classifieds site. Persian queries work best; prices in Toman.
+- **Install:** `claude mcp add divar -- uvx divar-mcp` (stdio, needs [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10+).
+- **Auth:** none. Optional `DIVAR_MCP_PROXY` sets an HTTP proxy for every request.
+- **Access:** read-only on Divar. It cannot log in, post, chat, bookmark or reveal a seller's phone number. Only `dv_watch` and `dv_price_trend` write, to a local file of your own searches.
+- **Also:** resources `divar://cities`, `divar://categories`, `divar://category-filters/{slug}`; prompts `compare_ads`, `best_under_budget`, `appraise_listing`, `watch_market`.
+- **Tools:** 31, all prefixed `dv_`. Start with `dv_search`, `dv_post`, `dv_cheapest`, `dv_best_for_budget`, `dv_market`.
+- **Typical sequence:** `dv_cities` / `dv_categories` -> `dv_filters` -> `dv_search` -> `dv_post` -> `dv_similar` / `dv_appraise` / `dv_compare`.
+- **Use when:** the user wants to find, price-check or monitor Divar ads (flats to buy or rent, used cars, phones, furniture, jobs...), or asks what something costs in a city.
+- **Do not use when:** the user wants to post an ad, message a seller or get a phone number (login-only on Divar).
+- **Output:** compact JSON ad cards. `price` for a sale; `deposit` + `rent` for a rental; no price means negotiable. Pass `token` between tools and `next_cursor` back as `cursor`.
+- **Machine-readable:** [server.json](https://github.com/sepehr071/divar-mcp/blob/main/server.json), and the catalog of all Iranian MCP servers [awesome-iran-mcp](https://github.com/sepehr071/awesome-iran-mcp) (`TOOLS.md`, `servers.json`, `llms.txt`).
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+claude mcp add divar -- uvx divar-mcp
+```
+
+Any other MCP client: command `uvx`, args `["divar-mcp"]` (or `pip install divar-mcp` and run `divar-mcp`).
+
+## What it can do
+
+- Search ads in one or several cities by category, text, neighbourhood, price (and deposit for rentals), brand and model, photo, freshness and every other filter of the category; merge several pages with duplicates removed; continue with a cursor
+- Full ad: price in **Toman**, specs, features, description, all images, map position, seller type, shared-housing flag, placeholder-price detection
+- Smart tools: cheapest ads (junk prices skipped), best value and most-for-the-budget, side-by-side comparison showing only the differences, similar ads, fair-price appraisal with percentile and confidence, market statistics by district and by day
+- Monitoring: poll `dv_new_since` with the last timestamp to see only new ads; export results as CSV or JSON lines
+- Map: ads around a GPS point or landmark with distances; neighbourhoods, neighbours, address of a point
+- Sellers and dealers: how many ads a seller has, the business card and its ads
+
+## Tools
+
+All tools are read-only and start with `dv_`. An ad card has `token`, `title`, `price` (sale) or `deposit` + `rent`
+(`rent` 0 with `full_deposit` means رهن کامل), `info` (mileage, condition...), `district`, `seller` (agency label),
+`age_h` (hours since the last bump), `photos`, `image` (thumbnail URL, only from `dv_search` with `thumbnails`), `chat`, `tag` (paid promotion), `url`, and
+`suspect_price` when the price looks like a placeholder. Absent flags mean false. Default page size is 10 to 20 ads.
+
+### Find places and categories
+
+| Tool | What it does |
+|---|---|
+| `dv_cities` | City ids for a name (1,177 cities); no query lists the biggest cities |
+| `dv_districts` | Neighbourhoods of a city with ids, centre and main streets |
+| `dv_neighbours` | Neighbourhoods adjacent to a district (Divar's list plus the nearest ones by distance) |
+| `dv_locate` | City, neighbourhood and street address of a GPS point |
+| `dv_place_search` | Map autocomplete: landmark or street to coordinates |
+| `dv_place_mapping` | Convert old Divar place ids to current ones |
+| `dv_categories` | The 236-node category tree; search by name, list children |
+| `dv_filters` | Every filter of a category: key, type, label, unit, options |
+| `dv_filter_options` | Brand and model keys (161 car brands), districts and other option lists, with typed search |
+| `dv_suggest` | The search box's suggestions and category guesses for some text |
+| `dv_parse_query` | A plain Persian request ("آپارتمان اجاره ونک زیر ۸ میلیارد") to `dv_search` arguments: city, neighbourhoods, price bounds, area (`80 متری`), category |
+| `dv_boundary` | Neighbourhood borders of a city (GeoJSON): the city box, or one neighbourhood's polygon |
+
+### Search and price
+
+| Tool | What it does |
+|---|---|
+| `dv_search` | Search ads with city, category, text, districts, price, brand, photo, freshness and any category filter; multi-page merge, client-side age and keyword filters, cursor paging |
+| `dv_count` | How many ads match a search (capped at 10,000) |
+| `dv_cheapest` | The cheapest ads of a search; placeholder prices and far-below-median outliers skipped |
+| `dv_best_for_budget` | Within a budget: best value with an explainable `deal_score` (and `reasons`) against the median of the ads that fit (price per m2 for property for sale), and the most you can get; bait / co-op / loan titles are skipped |
+| `dv_find_deals` | Ads priced well below the median of a search, no budget needed; junk prices and bait titles removed |
+| `dv_market` | Price statistics (min, quartiles, median, max) plus breakdown by district and by day |
+| `dv_appraise` | Is an ad's price (or a price you give) high or low versus similar ads: percentile, verdict ("insufficient comparables" when the call is extreme but thin), confidence |
+| `dv_new_since` | Ads published after a timestamp: poll with the returned `latest` to watch a search |
+| `dv_export` | The ads of a search as CSV or JSON lines |
+| `dv_nearby` | Map ads around a point (category required), nearest first, with coordinates, distance and total price |
+| `dv_watch` | Saved searches: create, then check to get only the ads newer than the last check (local file) |
+| `dv_price_trend` | One median asking price per day for a search, kept locally, with change since the previous day |
+| `dv_status` | Is Divar reachable, latency, caches, saved watches and the tool list |
+
+### One ad and its seller
+
+| Tool | What it does |
+|---|---|
+| `dv_post` | Full ad: price, specs, features, description, images, map position, seller type, flags |
+| `dv_posts` | Up to 10 ads in one call, compact |
+| `dv_compare` | 2 to 6 ads side by side: prices and only the specs that differ |
+| `dv_similar` | Ads like this one (same brand and area, widening step by step) |
+| `dv_seller` | A seller's personal and business ad counts, business card (or "personal seller") and other ads |
+| `dv_dealer` | A business's public page: name, member since, first 11 ads |
+
+## Good to know
+
+- **Prices are Toman.** Divar's prices are Toman already; nothing is converted. A missing price means negotiable (توافقی), never 0. Rentals have `deposit` (ودیعه) and `rent` (اجاره); `rent` 0 with `full_deposit` is رهن کامل.
+- **Asking prices.** Everything is what sellers typed, not what deals close at. Some sellers type junk (1,111,111 or a deposit as a car price): `suspect_price` flags placeholders, and rankings and statistics skip them and prices under a tenth of the median.
+- **Province scope.** `city: "استان مشهد"` (or `province:مشهد`) searches the whole province of that city; districts and boundaries need a city.
+- **Order.** Divar's API only returns newest first; the first 1-3 rows can be paid promotions with older dates. `dv_search` `sort` and the price tools sort the ads fetched in the call, not the whole market. Paging is a time cursor (`next_cursor` -> `cursor`).
+- **Filters.** `dv_filters` lists the keys of a category; filters a category lacks are reported in `ignored`, not silently dropped. Web URL slugs (`car`) work next to API slugs (`light`).
+- **Map positions** of most ads are fuzzed by about 500 m (`approximate_location`).
+- **No phone numbers.** Divar shows them only to logged-in users; this server never logs in. Use `url` to open the ad.
+- Detail prices come from the ad's price rows; Divar's raw number elsewhere in the ad is float-rounded for large values.
+- Persian queries work best; Arabic letter variants (ي/ك) are folded, and an empty Persian query is retried once folded.
+
+## FAQ
+
+**Is there a Divar API or MCP server for AI agents?**
+Yes: this unofficial MCP server wraps the public JSON API the Divar website itself uses, so Claude, Cursor or
+Copilot can search ads, read details and compare prices. Divar's official Kenar API is for partners (OAuth and an
+API key) and is not used here.
+
+**Is it official, safe and free?**
+It is unofficial, open source (MIT) and free. It is read-only, needs no account or API key, and runs on your
+machine with no hosted server in between.
+
+**Can it message a seller, post an ad or get a phone number?**
+No. Those need a Divar login and are deliberately left out.
+
+**Can it alert me when a matching ad appears?**
+It does not push. `dv_new_since` returns only ads newer than a timestamp, and `dv_watch` remembers that timestamp for a saved search (in `~/.divar-mcp/state.json`, or `DIVAR_MCP_STATE`), so a scheduler (cron, a Claude Code loop) can call `dv_watch` with `action: "check"`.
+
+## Configuration
+
+The server calls `api.divar.ir` directly and ignores system proxy variables. To use a proxy set `DIVAR_MCP_PROXY=http://host:port`.
+Saved watches and price history go to `~/.divar-mcp/state.json`; set `DIVAR_MCP_STATE` to use another file.
+
+## Development
+
+```bash
+export HTTPS_PROXY=http://127.0.0.1:10898 HTTP_PROXY=http://127.0.0.1:10898   # uv downloads only
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run pytest -q            # offline, recorded fixtures
+uv run pytest -m live -q    # real API, one test per tool
+```
+
+The API map this server is built on lives next to it in `../divar/`.
+
+<a id="فارسی"></a>
+
+## فارسی: سرور MCP دیوار
+
+<div dir="rtl">
+
+**divar-mcp** یک سرور MCP غیررسمی برای دیوار است که به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه
+می&zwnj;دهد در آگهی&zwnj;های هر شهر ایران جستجو کند، آگهی را کامل ببیند، چند آگهی را مقایسه کند، ارزان&zwnj;ترین و
+مناسب&zwnj;ترین آگهی را برای یک بودجه پیدا کند، منصفانه بودن قیمت را بسنجد و آگهی&zwnj;های اطراف یک نقطه روی نقشه را ببیند.
+
+- فقط خواندنی است و حساب کاربری یا کلید API نمی&zwnj;خواهد؛ شماره تلفن فروشنده را نشان نمی&zwnj;دهد.
+- همه قیمت&zwnj;ها به تومان است؛ قیمت نداشتن یعنی توافقی.
+
+بپرسید: «ارزان&zwnj;ترین آپارتمان ۲ خوابه اجاره&zwnj;ای در ونک با ودیعه زیر ۱ میلیارد کدام است؟»
+
+</div>
+
+## Related servers
+
+- All Iranian MCP servers: [awesome-iran-mcp](https://github.com/sepehr071/awesome-iran-mcp)
+
+## Disclaimer
+
+Unofficial; not affiliated with Divar. Read-only access to the data of public pages. Keep request rates low (Divar showed no rate limit, but be polite).
+
+If this saves you clicks, a star helps others find it.
+
+## License
+
+MIT

divar_mcp-0.1.0/README.md

@@ -0,0 +1,177 @@
+<!-- mcp-name: io.github.sepehr071/divar-mcp -->
+
+# divar-mcp: Divar MCP server for AI agents
+
+**Unofficial, read-only MCP server that lets your AI agent search Divar (دیوار) ads in any Iranian city: homes, cars, phones and more. It finds the cheapest and best-value ads, compares ads, checks whether a price is fair and browses the map. Prices are in Toman.**
+
+An [MCP](https://modelcontextprotocol.io) server for [Divar](https://divar.ir), Iran's largest classifieds site.
+Search by city, neighbourhood, category, text and any of the category's filters, read a full ad, compare several, see
+the seller's other ads, get market statistics, appraise a price against similar ads and poll for new ads, all from
+Claude, Cursor or Copilot. No account, no API key, nothing is posted or changed.
+
+[Quick start](#quick-start) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
+
+---
+
+## For AI agents
+
+- **What:** Unofficial MCP server for Divar (دیوار, divar.ir), Iran's classifieds site. Persian queries work best; prices in Toman.
+- **Install:** `claude mcp add divar -- uvx divar-mcp` (stdio, needs [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10+).
+- **Auth:** none. Optional `DIVAR_MCP_PROXY` sets an HTTP proxy for every request.
+- **Access:** read-only on Divar. It cannot log in, post, chat, bookmark or reveal a seller's phone number. Only `dv_watch` and `dv_price_trend` write, to a local file of your own searches.
+- **Also:** resources `divar://cities`, `divar://categories`, `divar://category-filters/{slug}`; prompts `compare_ads`, `best_under_budget`, `appraise_listing`, `watch_market`.
+- **Tools:** 31, all prefixed `dv_`. Start with `dv_search`, `dv_post`, `dv_cheapest`, `dv_best_for_budget`, `dv_market`.
+- **Typical sequence:** `dv_cities` / `dv_categories` -> `dv_filters` -> `dv_search` -> `dv_post` -> `dv_similar` / `dv_appraise` / `dv_compare`.
+- **Use when:** the user wants to find, price-check or monitor Divar ads (flats to buy or rent, used cars, phones, furniture, jobs...), or asks what something costs in a city.
+- **Do not use when:** the user wants to post an ad, message a seller or get a phone number (login-only on Divar).
+- **Output:** compact JSON ad cards. `price` for a sale; `deposit` + `rent` for a rental; no price means negotiable. Pass `token` between tools and `next_cursor` back as `cursor`.
+- **Machine-readable:** [server.json](https://github.com/sepehr071/divar-mcp/blob/main/server.json), and the catalog of all Iranian MCP servers [awesome-iran-mcp](https://github.com/sepehr071/awesome-iran-mcp) (`TOOLS.md`, `servers.json`, `llms.txt`).
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+claude mcp add divar -- uvx divar-mcp
+```
+
+Any other MCP client: command `uvx`, args `["divar-mcp"]` (or `pip install divar-mcp` and run `divar-mcp`).
+
+## What it can do
+
+- Search ads in one or several cities by category, text, neighbourhood, price (and deposit for rentals), brand and model, photo, freshness and every other filter of the category; merge several pages with duplicates removed; continue with a cursor
+- Full ad: price in **Toman**, specs, features, description, all images, map position, seller type, shared-housing flag, placeholder-price detection
+- Smart tools: cheapest ads (junk prices skipped), best value and most-for-the-budget, side-by-side comparison showing only the differences, similar ads, fair-price appraisal with percentile and confidence, market statistics by district and by day
+- Monitoring: poll `dv_new_since` with the last timestamp to see only new ads; export results as CSV or JSON lines
+- Map: ads around a GPS point or landmark with distances; neighbourhoods, neighbours, address of a point
+- Sellers and dealers: how many ads a seller has, the business card and its ads
+
+## Tools
+
+All tools are read-only and start with `dv_`. An ad card has `token`, `title`, `price` (sale) or `deposit` + `rent`
+(`rent` 0 with `full_deposit` means رهن کامل), `info` (mileage, condition...), `district`, `seller` (agency label),
+`age_h` (hours since the last bump), `photos`, `image` (thumbnail URL, only from `dv_search` with `thumbnails`), `chat`, `tag` (paid promotion), `url`, and
+`suspect_price` when the price looks like a placeholder. Absent flags mean false. Default page size is 10 to 20 ads.
+
+### Find places and categories
+
+| Tool | What it does |
+|---|---|
+| `dv_cities` | City ids for a name (1,177 cities); no query lists the biggest cities |
+| `dv_districts` | Neighbourhoods of a city with ids, centre and main streets |
+| `dv_neighbours` | Neighbourhoods adjacent to a district (Divar's list plus the nearest ones by distance) |
+| `dv_locate` | City, neighbourhood and street address of a GPS point |
+| `dv_place_search` | Map autocomplete: landmark or street to coordinates |
+| `dv_place_mapping` | Convert old Divar place ids to current ones |
+| `dv_categories` | The 236-node category tree; search by name, list children |
+| `dv_filters` | Every filter of a category: key, type, label, unit, options |
+| `dv_filter_options` | Brand and model keys (161 car brands), districts and other option lists, with typed search |
+| `dv_suggest` | The search box's suggestions and category guesses for some text |
+| `dv_parse_query` | A plain Persian request ("آپارتمان اجاره ونک زیر ۸ میلیارد") to `dv_search` arguments: city, neighbourhoods, price bounds, area (`80 متری`), category |
+| `dv_boundary` | Neighbourhood borders of a city (GeoJSON): the city box, or one neighbourhood's polygon |
+
+### Search and price
+
+| Tool | What it does |
+|---|---|
+| `dv_search` | Search ads with city, category, text, districts, price, brand, photo, freshness and any category filter; multi-page merge, client-side age and keyword filters, cursor paging |
+| `dv_count` | How many ads match a search (capped at 10,000) |
+| `dv_cheapest` | The cheapest ads of a search; placeholder prices and far-below-median outliers skipped |
+| `dv_best_for_budget` | Within a budget: best value with an explainable `deal_score` (and `reasons`) against the median of the ads that fit (price per m2 for property for sale), and the most you can get; bait / co-op / loan titles are skipped |
+| `dv_find_deals` | Ads priced well below the median of a search, no budget needed; junk prices and bait titles removed |
+| `dv_market` | Price statistics (min, quartiles, median, max) plus breakdown by district and by day |
+| `dv_appraise` | Is an ad's price (or a price you give) high or low versus similar ads: percentile, verdict ("insufficient comparables" when the call is extreme but thin), confidence |
+| `dv_new_since` | Ads published after a timestamp: poll with the returned `latest` to watch a search |
+| `dv_export` | The ads of a search as CSV or JSON lines |
+| `dv_nearby` | Map ads around a point (category required), nearest first, with coordinates, distance and total price |
+| `dv_watch` | Saved searches: create, then check to get only the ads newer than the last check (local file) |
+| `dv_price_trend` | One median asking price per day for a search, kept locally, with change since the previous day |
+| `dv_status` | Is Divar reachable, latency, caches, saved watches and the tool list |
+
+### One ad and its seller
+
+| Tool | What it does |
+|---|---|
+| `dv_post` | Full ad: price, specs, features, description, images, map position, seller type, flags |
+| `dv_posts` | Up to 10 ads in one call, compact |
+| `dv_compare` | 2 to 6 ads side by side: prices and only the specs that differ |
+| `dv_similar` | Ads like this one (same brand and area, widening step by step) |
+| `dv_seller` | A seller's personal and business ad counts, business card (or "personal seller") and other ads |
+| `dv_dealer` | A business's public page: name, member since, first 11 ads |
+
+## Good to know
+
+- **Prices are Toman.** Divar's prices are Toman already; nothing is converted. A missing price means negotiable (توافقی), never 0. Rentals have `deposit` (ودیعه) and `rent` (اجاره); `rent` 0 with `full_deposit` is رهن کامل.
+- **Asking prices.** Everything is what sellers typed, not what deals close at. Some sellers type junk (1,111,111 or a deposit as a car price): `suspect_price` flags placeholders, and rankings and statistics skip them and prices under a tenth of the median.
+- **Province scope.** `city: "استان مشهد"` (or `province:مشهد`) searches the whole province of that city; districts and boundaries need a city.
+- **Order.** Divar's API only returns newest first; the first 1-3 rows can be paid promotions with older dates. `dv_search` `sort` and the price tools sort the ads fetched in the call, not the whole market. Paging is a time cursor (`next_cursor` -> `cursor`).
+- **Filters.** `dv_filters` lists the keys of a category; filters a category lacks are reported in `ignored`, not silently dropped. Web URL slugs (`car`) work next to API slugs (`light`).
+- **Map positions** of most ads are fuzzed by about 500 m (`approximate_location`).
+- **No phone numbers.** Divar shows them only to logged-in users; this server never logs in. Use `url` to open the ad.
+- Detail prices come from the ad's price rows; Divar's raw number elsewhere in the ad is float-rounded for large values.
+- Persian queries work best; Arabic letter variants (ي/ك) are folded, and an empty Persian query is retried once folded.
+
+## FAQ
+
+**Is there a Divar API or MCP server for AI agents?**
+Yes: this unofficial MCP server wraps the public JSON API the Divar website itself uses, so Claude, Cursor or
+Copilot can search ads, read details and compare prices. Divar's official Kenar API is for partners (OAuth and an
+API key) and is not used here.
+
+**Is it official, safe and free?**
+It is unofficial, open source (MIT) and free. It is read-only, needs no account or API key, and runs on your
+machine with no hosted server in between.
+
+**Can it message a seller, post an ad or get a phone number?**
+No. Those need a Divar login and are deliberately left out.
+
+**Can it alert me when a matching ad appears?**
+It does not push. `dv_new_since` returns only ads newer than a timestamp, and `dv_watch` remembers that timestamp for a saved search (in `~/.divar-mcp/state.json`, or `DIVAR_MCP_STATE`), so a scheduler (cron, a Claude Code loop) can call `dv_watch` with `action: "check"`.
+
+## Configuration
+
+The server calls `api.divar.ir` directly and ignores system proxy variables. To use a proxy set `DIVAR_MCP_PROXY=http://host:port`.
+Saved watches and price history go to `~/.divar-mcp/state.json`; set `DIVAR_MCP_STATE` to use another file.
+
+## Development
+
+```bash
+export HTTPS_PROXY=http://127.0.0.1:10898 HTTP_PROXY=http://127.0.0.1:10898   # uv downloads only
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run pytest -q            # offline, recorded fixtures
+uv run pytest -m live -q    # real API, one test per tool
+```
+
+The API map this server is built on lives next to it in `../divar/`.
+
+<a id="فارسی"></a>
+
+## فارسی: سرور MCP دیوار
+
+<div dir="rtl">
+
+**divar-mcp** یک سرور MCP غیررسمی برای دیوار است که به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه
+می&zwnj;دهد در آگهی&zwnj;های هر شهر ایران جستجو کند، آگهی را کامل ببیند، چند آگهی را مقایسه کند، ارزان&zwnj;ترین و
+مناسب&zwnj;ترین آگهی را برای یک بودجه پیدا کند، منصفانه بودن قیمت را بسنجد و آگهی&zwnj;های اطراف یک نقطه روی نقشه را ببیند.
+
+- فقط خواندنی است و حساب کاربری یا کلید API نمی&zwnj;خواهد؛ شماره تلفن فروشنده را نشان نمی&zwnj;دهد.
+- همه قیمت&zwnj;ها به تومان است؛ قیمت نداشتن یعنی توافقی.
+
+بپرسید: «ارزان&zwnj;ترین آپارتمان ۲ خوابه اجاره&zwnj;ای در ونک با ودیعه زیر ۱ میلیارد کدام است؟»
+
+</div>
+
+## Related servers
+
+- All Iranian MCP servers: [awesome-iran-mcp](https://github.com/sepehr071/awesome-iran-mcp)
+
+## Disclaimer
+
+Unofficial; not affiliated with Divar. Read-only access to the data of public pages. Keep request rates low (Divar showed no rate limit, but be polite).
+
+If this saves you clicks, a star helps others find it.
+
+## License
+
+MIT