qavanin-mcp 0.1.0__tar.gz

qavanin_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

qavanin_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/qavanin-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

qavanin_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.ruff_cache/

qavanin_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.

qavanin_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: qavanin-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for qavanin.ir: search Iranian laws and regulations, read their full text, amendments and status.
+Project-URL: Homepage, https://github.com/sepehr071/qavanin-mcp
+Project-URL: Issues, https://github.com/sepehr071/qavanin-mcp/issues
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: iran,law,legal,mcp,model-context-protocol,qavanin,regulations
+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: curl-cffi>=0.16.3
+Requires-Dist: httpx-curl-cffi>=0.1.5
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.2
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.sepehr071/qavanin-mcp -->
+
+# qavanin-mcp: Iranian laws and regulations MCP server for AI agents ⚖️
+
+**Unofficial, read-only MCP server for [qavanin.ir](https://qavanin.ir) (سامانه ملی قوانین و مقررات جمهوری اسلامی ایران), the national database of Iranian laws, regulations, court votes and legal opinions.**<br>
+Search about 168,000 documents by title or full text, read a law or a single article, see how an article was amended, and follow the regulations and court votes that cite it, all from Claude, Cursor or Copilot.
+
+[Quick start](#quick-start) · [For AI agents](#for-ai-agents) · [Tools](#tools) · [Notes](#notes) · [فارسی](#فارسی)
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server for qavanin.ir. Queries work in Persian (Arabic ي/ك and Persian ی/ک are equivalent); dates are Jalali `YYYY/MM/DD`.
+- **Install:** `claude mcp add qavanin -- uvx qavanin-mcp` (stdio transport, needs [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10+).
+- **Auth:** none. Optional `QAVANIN_MCP_PROXY` sets an HTTP proxy for requests to qavanin.ir.
+- **Access:** read-only. No login, subscription or purchase calls exist.
+- **Tools:** 7, all prefixed `qv_`. Typical sequence: `qv_search` → `qv_law` (with `article`) → `qv_amendments` → `qv_article_history`.
+- **Use when:** looking up what an Iranian law, regulation, court ruling or legal opinion says, when it was approved and published, whether it was amended or repealed, and what cites it.
+- **Do not use when:** the user needs legal advice or a binding interpretation. The site is a reference database; always say which version and status you read.
+- **Output:** compact JSON. Document ids (`id`, the site's `IDS`) are 20-digit strings: keep them as strings. Output uses Persian letters. Sections marked `repealed` or `amended` are not current text.
+- **Machine-readable:** [`server.json`](server.json), and the catalog of all Iranian MCP servers at [awesome-iran-mcp](https://github.com/sepehr071/awesome-iran-mcp).
+
+## Quick start
+
+```bash
+claude mcp add qavanin -- uvx qavanin-mcp
+```
+
+```json
+{ "mcpServers": { "qavanin": { "command": "uvx", "args": ["qavanin-mcp"] } } }
+```
+
+Example: «ماده ۱۰ قانون مدنی چه می‌گوید؟» → `qv_search(query="قانون مدنی", kind="law")` → `qv_law(ids=..., article="10")`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `qv_search` | Search titles or full text, with filters for kind, approving body, executor, subject, type, status, dates and gazette numbers |
+| `qv_lookup` | Find the ids the search filters take: approving bodies, executing bodies, subjects, document types, statuses, curated lists |
+| `qv_law` | Read the text of a law as sections, one article with its notes, or the text as of a past date |
+| `qv_law_info` | Metadata: type, approver, approval, notification and gazette numbers and dates, last status, executors |
+| `qv_amendments` | Which laws amended this one, which it amends, and which of its articles were amended |
+| `qv_article_history` | Every amendment of one article: type, date, amending law, replacing text |
+| `qv_related` | Regulations, court votes and legal opinions related to a law |
+
+## Notes
+
+- The site is slow: 1-15 s per call, the civil code about 15 s on first read (it is cached for 5 minutes, so paging through it is fast).
+- The site sometimes ignores search filters and answers with the whole database; the server detects and retries that.
+- Sorting by date has many ties, so paging a long list can repeat or skip a row: narrow the filters instead of paging deep.
+- A bot-check cookie (ArvanCloud) is solved in Python; no browser is needed.
+
+## فارسی
+
+سرور MCP غیررسمی و فقط‌خواندنی برای سامانه ملی قوانین و مقررات (qavanin.ir): جستجو در عنوان یا متن حدود ۱۶۸ هزار سند، خواندن متن قانون یا یک ماده، تاریخچهٔ اصلاحات هر ماده و مقررات، آرا و نظرات مرتبط. نصب: `claude mcp add qavanin -- uvx qavanin-mcp`
+
+## License
+
+MIT. Not affiliated with qavanin.ir or the Iranian government.

qavanin_mcp-0.1.0/README.md

@@ -0,0 +1,61 @@
+<!-- mcp-name: io.github.sepehr071/qavanin-mcp -->
+
+# qavanin-mcp: Iranian laws and regulations MCP server for AI agents ⚖️
+
+**Unofficial, read-only MCP server for [qavanin.ir](https://qavanin.ir) (سامانه ملی قوانین و مقررات جمهوری اسلامی ایران), the national database of Iranian laws, regulations, court votes and legal opinions.**<br>
+Search about 168,000 documents by title or full text, read a law or a single article, see how an article was amended, and follow the regulations and court votes that cite it, all from Claude, Cursor or Copilot.
+
+[Quick start](#quick-start) · [For AI agents](#for-ai-agents) · [Tools](#tools) · [Notes](#notes) · [فارسی](#فارسی)
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server for qavanin.ir. Queries work in Persian (Arabic ي/ك and Persian ی/ک are equivalent); dates are Jalali `YYYY/MM/DD`.
+- **Install:** `claude mcp add qavanin -- uvx qavanin-mcp` (stdio transport, needs [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10+).
+- **Auth:** none. Optional `QAVANIN_MCP_PROXY` sets an HTTP proxy for requests to qavanin.ir.
+- **Access:** read-only. No login, subscription or purchase calls exist.
+- **Tools:** 7, all prefixed `qv_`. Typical sequence: `qv_search` → `qv_law` (with `article`) → `qv_amendments` → `qv_article_history`.
+- **Use when:** looking up what an Iranian law, regulation, court ruling or legal opinion says, when it was approved and published, whether it was amended or repealed, and what cites it.
+- **Do not use when:** the user needs legal advice or a binding interpretation. The site is a reference database; always say which version and status you read.
+- **Output:** compact JSON. Document ids (`id`, the site's `IDS`) are 20-digit strings: keep them as strings. Output uses Persian letters. Sections marked `repealed` or `amended` are not current text.
+- **Machine-readable:** [`server.json`](server.json), and the catalog of all Iranian MCP servers at [awesome-iran-mcp](https://github.com/sepehr071/awesome-iran-mcp).
+
+## Quick start
+
+```bash
+claude mcp add qavanin -- uvx qavanin-mcp
+```
+
+```json
+{ "mcpServers": { "qavanin": { "command": "uvx", "args": ["qavanin-mcp"] } } }
+```
+
+Example: «ماده ۱۰ قانون مدنی چه می‌گوید؟» → `qv_search(query="قانون مدنی", kind="law")` → `qv_law(ids=..., article="10")`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `qv_search` | Search titles or full text, with filters for kind, approving body, executor, subject, type, status, dates and gazette numbers |
+| `qv_lookup` | Find the ids the search filters take: approving bodies, executing bodies, subjects, document types, statuses, curated lists |
+| `qv_law` | Read the text of a law as sections, one article with its notes, or the text as of a past date |
+| `qv_law_info` | Metadata: type, approver, approval, notification and gazette numbers and dates, last status, executors |
+| `qv_amendments` | Which laws amended this one, which it amends, and which of its articles were amended |
+| `qv_article_history` | Every amendment of one article: type, date, amending law, replacing text |
+| `qv_related` | Regulations, court votes and legal opinions related to a law |
+
+## Notes
+
+- The site is slow: 1-15 s per call, the civil code about 15 s on first read (it is cached for 5 minutes, so paging through it is fast).
+- The site sometimes ignores search filters and answers with the whole database; the server detects and retries that.
+- Sorting by date has many ties, so paging a long list can repeat or skip a row: narrow the filters instead of paging deep.
+- A bot-check cookie (ArvanCloud) is solved in Python; no browser is needed.
+
+## فارسی
+
+سرور MCP غیررسمی و فقط‌خواندنی برای سامانه ملی قوانین و مقررات (qavanin.ir): جستجو در عنوان یا متن حدود ۱۶۸ هزار سند، خواندن متن قانون یا یک ماده، تاریخچهٔ اصلاحات هر ماده و مقررات، آرا و نظرات مرتبط. نصب: `claude mcp add qavanin -- uvx qavanin-mcp`
+
+## License
+
+MIT. Not affiliated with qavanin.ir or the Iranian government.

qavanin_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "qavanin-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for qavanin.ir: search Iranian laws and regulations, read their full text, amendments and status."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sepehr Radmard", email = "sepehrr80@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "qavanin", "iran", "law", "legal", "regulations"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=2.2,<3",
+    "httpx>=0.27",
+    "httpx-curl-cffi>=0.1.5",
+    "curl-cffi>=0.16.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/sepehr071/qavanin-mcp"
+Issues = "https://github.com/sepehr071/qavanin-mcp/issues"
+
+[project.scripts]
+qavanin-mcp = "qavanin_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not live'"
+markers = ["live: calls the real qavanin.ir site (run with -m live)"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]  # long Field(description=...) strings read better on one line

qavanin_mcp-0.1.0/server.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.sepehr071/qavanin-mcp",
+  "title": "Qavanin",
+  "description": "Unofficial read-only qavanin.ir: search Iranian laws and regulations, read full text and status.",
+  "repository": {
+    "url": "https://github.com/sepehr071/qavanin-mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/sepehr071/qavanin-mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "qavanin-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "QAVANIN_MCP_PROXY",
+          "description": "Optional HTTP proxy URL, or a comma-separated list tried in turn, for qavanin.ir; system proxies are ignored.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

qavanin_mcp-0.1.0/src/qavanin_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Unofficial MCP server for qavanin.ir (Iran's national laws and regulations portal)."""
+
+from importlib.metadata import version
+
+__version__ = version("qavanin-mcp")

qavanin_mcp-0.1.0/src/qavanin_mcp/http.py

@@ -0,0 +1,212 @@
+"""Shared async HTTP client for qavanin.ir.
+
+Every tool goes through `get_page` (server-rendered ASP.NET MVC HTML) or `post_json`. `_send` caps concurrency,
+solves the site's ArvanCloud JS cookie challenge, retries timeouts, dropped connections, 429 and 5xx (never 403)
+with jittered backoff, and turns HTTP failures into `ToolError` messages the model can act on. The wire format is a
+Chrome impersonation (curl_cffi).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+import re
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import httpx
+from httpx_curl_cffi import AsyncCurlTransport
+from mcp.server.mcpserver.exceptions import ToolError
+
+BASE = "https://qavanin.ir"
+
+# User-Agent, sec-ch-ua and TLS come from the impersonated Chrome profile (see _get_client).
+HEADERS = {
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+    "Accept-Language": "fa-IR,fa;q=0.9,en;q=0.8",
+}
+
+MAX_CONCURRENCY = 2
+JITTER = (0.15, 0.6)  # seconds before each upstream call
+MAX_RETRIES = 2
+MAX_RETRY_WAIT = 10  # cap for Retry-After and backoff, seconds
+RETRY_DELAY = 0.5
+
+_transport: httpx.AsyncBaseTransport | None = None
+_client: httpx.AsyncClient | None = None
+_limit: asyncio.Semaphore | None = None
+_proxy_index = 0
+_cache: dict[Any, tuple[float, Any]] = {}
+
+
+class ApiError(ToolError):
+    """A failed upstream call. `status` is the HTTP status, or None for network errors."""
+
+    def __init__(self, message: str, status: int | None = None, retry_after: float | None = None):
+        super().__init__(message)
+        self.status = status
+        self.retry_after = retry_after
+
+
+def set_transport(transport: httpx.AsyncBaseTransport | None) -> None:
+    """Swap the transport (tests use httpx.MockTransport). Drops the current client."""
+    global _transport, _client, _limit, _proxy_index
+    _transport, _client, _limit, _proxy_index = transport, None, None, 0
+    _cache.clear()
+
+
+async def cached(key: Any, ttl: float, make: Callable[[], Awaitable[Any]]) -> Any:
+    """Return make()'s result, reused for `ttl` seconds per key. Only for results nobody mutates."""
+    hit = _cache.get(key)
+    if hit and time.monotonic() - hit[0] < ttl:
+        return hit[1]
+    value = await make()
+    if len(_cache) >= 32:  # parsed laws can be large: keep only the newest entries
+        _cache.pop(next(iter(_cache)))
+    _cache[key] = (time.monotonic(), value)
+    return value
+
+
+def _proxies() -> list[str]:
+    """QAVANIN_MCP_PROXY: one proxy URL, or a comma-separated list used one at a time."""
+    return [p.strip() for p in os.environ.get("QAVANIN_MCP_PROXY", "").split(",") if p.strip()]
+
+
+def _get_client() -> tuple[httpx.AsyncClient, asyncio.Semaphore]:
+    global _client, _limit
+    if _client is None:
+        # Direct connections work; a system proxy is only used when the user opts in with QAVANIN_MCP_PROXY.
+        proxies = _proxies()
+        _client = httpx.AsyncClient(
+            transport=_transport
+            or AsyncCurlTransport(
+                impersonate="chrome",
+                default_headers=True,
+                proxy=proxies[_proxy_index % len(proxies)] if proxies else None,
+                max_connections=2 * MAX_CONCURRENCY,
+            ),
+            headers=HEADERS,
+            timeout=60,  # the origin is slow: 1-18 s typical, the civil code about 14 s, rare 40 s hangs
+            limits=httpx.Limits(max_connections=2 * MAX_CONCURRENCY),
+            follow_redirects=True,
+            trust_env=False,
+        )
+        _limit = asyncio.Semaphore(MAX_CONCURRENCY)
+    assert _limit is not None
+    return _client, _limit
+
+
+# --- ArvanCloud JS challenge -------------------------------------------------------------------------------
+# A first visit (or an expired cookie, Max-Age 100 s) gets a 200 page whose script computes two cookies from two
+# JSFuck constants (the page's E(E(x)) is the identity) and reloads. The constants are built only from the atoms
+# below, so they are evaluated here instead of running the page's JavaScript.
+_CHALLENGE = re.compile(r"'value_v1': eval\(\"(.*?)\"\), 'value': eval\(\"(.*?)\"\)", re.S)
+_NUM = r"(?:\+!\+\[\]|\+\[\]|!\+\[\](?:\+!\+\[\])*)"  # 1, 0, or n x "!+[]" (n)
+_WORDS = {"(![]+[])": "false", "(!![]+[])": "true", "([][[]]+[])": "undefined"}
+
+
+def _num(expr: str) -> int:
+    return 0 if expr == "+[]" else expr.count("!+[]")
+
+
+def _fuck(expr: str) -> str:
+    """Evaluate a JSFuck string built from digits, false/true/undefined letters, fill/entries and fromCharCode."""
+    expr = re.sub(
+        rf"(\(!?!?\[\]\+\[\]\)|\(\[\]\[\[\]\]\+\[\]\))\[({_NUM})\]",
+        lambda m: repr(_WORDS[m[1]][_num(m[2])]),
+        expr,
+    )
+    expr = expr.replace("([]['fill']+'')[3]", "'c'").replace("([]['entries']()+'')[2]", "'b'")
+    expr = re.sub(r"\(\[\]\+\[\]\)\['constructor'\]\['fromCharCode'\]\((\d+)\)", lambda m: repr(chr(int(m[1]))), expr)
+    expr = re.sub(rf"\[({_NUM})\]", lambda m: repr(str(_num(m[1]))), expr)
+    if left := re.sub(r"'[^']*'|\[\]|\+", "", expr):
+        raise ValueError(left[:60])
+    return "".join(re.findall(r"'([^']*)'", expr))
+
+
+def solve_challenge(html: str) -> dict[str, str] | None:
+    """The cookies a challenge page sets, or None when `html` is not (or not a solvable) challenge page."""
+    m = _CHALLENGE.search(html) if "__arcsjs" in html else None
+    if not m:
+        return None
+    try:
+        return {"__arcsjs": _fuck(m[1]), "__arcsjsc": _fuck(m[2])}
+    except ValueError:
+        return None
+
+
+async def get_page(path: str, params: dict[str, Any] | None = None) -> tuple[str, str]:
+    """GET a site page; returns (final URL after redirects, HTML)."""
+    r = await _send("GET", f"{BASE}{path}", params=params)
+    return str(r.url), r.content.decode("utf-8", "replace")
+
+
+async def get_json(path: str, params: dict[str, Any] | None = None) -> Any:
+    """GET a JSON lookup endpoint (/Law/getOrgs/, /Law/getTopics/)."""
+    r = await _send("GET", f"{BASE}{path}", params=params, headers={"Accept": "application/json, text/plain, */*"})
+    try:
+        return r.json()
+    except ValueError as e:
+        raise ApiError(f"qavanin.ir returned a non-JSON response for {path} (HTTP {r.status_code}).") from e
+
+
+async def _send(method: str, url: str, **kwargs: Any) -> httpx.Response:
+    host = httpx.URL(BASE).host
+    retries = solved = 0
+    while True:
+        client, limit = _get_client()
+        wait = None
+        try:
+            async with limit:
+                await asyncio.sleep(random.uniform(*JITTER))
+                r = await client.request(method, url, **kwargs)
+        except httpx.TimeoutException as e:
+            err = ApiError(f"{host} did not answer in time. Try again in a moment.")
+            err.__cause__ = e
+        except httpx.TransportError as e:
+            err = ApiError(
+                f"Could not reach {host} ({type(e).__name__}). Check the internet connection, or set QAVANIN_MCP_PROXY."
+            )
+            err.__cause__ = e
+        else:
+            if r.status_code == 429 or r.status_code >= 500:
+                err = ApiError(_status_message(r), r.status_code)
+                wait = _retry_after(r)
+            else:
+                cookies = solve_challenge(r.text) if r.status_code == 200 and len(r.content) < 20_000 else None
+                if cookies and solved < 2:
+                    solved += 1
+                    for name, value in cookies.items():
+                        client.cookies.set(name, value, domain=host, path="/")
+                    continue
+                if cookies:
+                    raise ApiError(f"{host} kept answering with its bot challenge. Try again in a moment.", 403)
+                if r.status_code >= 400:
+                    raise ApiError(_status_message(r), r.status_code)
+                return r
+        if retries == MAX_RETRIES:
+            raise err
+        wait = wait if wait is not None else RETRY_DELAY * 2**retries * random.uniform(1, 1.5)
+        retries += 1
+        await asyncio.sleep(min(wait, MAX_RETRY_WAIT))
+
+
+def _retry_after(r: httpx.Response) -> float | None:
+    """Seconds from a numeric Retry-After on a 429/503, else None (HTTP-date form is ignored)."""
+    v = r.headers.get("retry-after", "")
+    return float(v) if r.status_code in (429, 503) and v.replace(".", "", 1).isdigit() else None
+
+
+def _status_message(r: httpx.Response) -> str:
+    code = r.status_code
+    if code == 403:
+        return "qavanin.ir blocked the request (HTTP 403). Turn off VPN/proxy or set QAVANIN_MCP_PROXY."
+    if code == 404:
+        return "Not found on qavanin.ir (HTTP 404). Check the law id."
+    if code == 429:
+        return "qavanin.ir is rate limiting requests (HTTP 429). Wait a minute before retrying."
+    if code >= 500:
+        return f"qavanin.ir had a server error (HTTP {code}). Try again later."
+    return f"qavanin.ir rejected the request (HTTP {code})."