ponisha-mcp 0.1.0__tar.gz

ponisha_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

ponisha_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/ponisha-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

ponisha_mcp-0.1.0/.gitignore

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

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

ponisha_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: ponisha-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for Ponisha (ponisha.ir), the Iranian freelance marketplace: projects, bids, freelancers, skill demand.
+Project-URL: Homepage, https://github.com/sepehr071/ponisha-mcp
+Project-URL: Issues, https://github.com/sepehr071/ponisha-mcp/issues
+Project-URL: Website, https://mcpfarsi.ir/
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bids,claude,freelance,freelancer,iran,marketplace,mcp,model-context-protocol,persian,ponisha,ponisha-ir,projects
+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/ponisha-mcp -->
+
+# ponisha-mcp: Ponisha (پونیشا) freelance marketplace MCP server for AI agents
+
+**ponisha-mcp is an unofficial, read-only MCP server that gives AI agents the public data of Ponisha (ponisha.ir), Iran's freelance marketplace.**<br>
+Its 14 tools search projects (text, skills, category, budget, sort), show a project with the employer's track record, list the offers made on it, search freelancers, read profiles, reviews and portfolios, browse fixed-price service packages, and summarize demand, budgets and trends for a skill.<br>
+No API key or Ponisha account is needed. It works in Claude, Cursor, Copilot and any other MCP client.
+
+[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server (model context protocol) for ponisha.ir: project search, project details, bids, freelancer search, public profiles, skills and categories, skill market summary.
+- **Install:** `uvx ponisha-mcp` or `claude mcp add ponisha -- uvx ponisha-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none. Optional `PONISHA_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
+- **Access:** read-only. It cannot log in, bid, post projects or message anyone, so no confirmation is needed before calling any tool.
+- **Tools:** 14, all prefixed `pn_`. Typical sequences: `pn_skills` -> `pn_search_projects` -> `pn_project` -> `pn_bids`; `pn_search_freelancers` -> `pn_profile`; `pn_skills` -> `pn_market` / `pn_trend`; `pn_profile` -> `pn_reviews` + `pn_portfolios`; `pn_services` -> `pn_service`.
+- **Use when:** the user wants freelance projects to bid on in Iran, what a kind of work pays, how crowded a project is, whether an employer is reliable, or who to hire for a skill.
+- **Do not use when:** the user wants to apply, message or post (read-only), or needs private contact data.
+- **Output:** compact JSON. Money is Toman. Times are Tehran time. Text is Persian user content.
+
+## Quick start
+
+```bash
+claude mcp add ponisha -- uvx ponisha-mcp
+```
+
+Any MCP client: command `uvx`, args `["ponisha-mcp"]`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `pn_search_projects` | Projects by text, skills, category, open/all, budget range, sort. |
+| `pn_project` | One project: brief, budget, deadline, employer track record, optional bid price sample. |
+| `pn_bids` | Offers on a project: price, days, pitch, bidder level and rating (paged). |
+| `pn_search_freelancers` | Freelancers by text, skills, level, portfolio, ranked by score. |
+| `pn_profile` | Public profile of a freelancer or employer. |
+| `pn_skills` | Skill name -> slug/id (about 700 skills). |
+| `pn_categories` | Top-level categories, or the sub-categories of one. |
+| `pn_market` | Open projects, budget quartiles, competition and related skills for one skill. |
+| `pn_trend` | Posting rate, median budget and bids for a skill sampled across its whole history. |
+| `pn_reviews` | Reviews of a user with score breakdown, or recent reviews for a skill. |
+| `pn_portfolios` | Search about 500k portfolio items, or list one user's. |
+| `pn_services` | Fixed-price service packages by category, price, rating. |
+| `pn_service` | One package: deliverables, requirements, paid add-ons. |
+| `pn_user_projects` | An employer's or freelancer's finished/open projects. |
+
+## FAQ
+
+**Is it official?** No. It reads the same public API the ponisha.ir web app uses for anonymous visitors.
+
+**Why are bids slow?** Ponisha serves the bids list slowly (seconds, up to 30 s on projects with 100+ bids). Keep `limit` small.
+
+**Why does the budget filter only look at one page?** The site has no budget filter. The tool scans up to 50 projects per page and keeps those whose range fits.
+
+## فارسی
+
+**ponisha-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای پونیشا (ponisha.ir) است. با آن می‌توانید پروژه‌ها را با کلمه، مهارت، دسته و بودجه جستجو کنید، پیشنهادهای ثبت‌شده و سابقه کارفرما را ببینید، فریلنسرها و پروفایل‌های عمومی را جستجو کنید و وضعیت بازار یک مهارت را بسنجید. بدون کلید API و حساب کاربری. نصب: `uvx ponisha-mcp`.
+
+مبلغ‌ها به تومان و زمان‌ها به وقت تهران (میلادی) هستند. این ابزار ثبت پیشنهاد، پیام یا ثبت پروژه انجام نمی‌دهد.
+
+Author: Sepehr Radmard (سپهر رادمرد) · github.com/sepehr071 · linkedin.com/in/sepehr-radmard

ponisha_mcp-0.1.0/README.md

@@ -0,0 +1,65 @@
+<!-- mcp-name: io.github.sepehr071/ponisha-mcp -->
+
+# ponisha-mcp: Ponisha (پونیشا) freelance marketplace MCP server for AI agents
+
+**ponisha-mcp is an unofficial, read-only MCP server that gives AI agents the public data of Ponisha (ponisha.ir), Iran's freelance marketplace.**<br>
+Its 14 tools search projects (text, skills, category, budget, sort), show a project with the employer's track record, list the offers made on it, search freelancers, read profiles, reviews and portfolios, browse fixed-price service packages, and summarize demand, budgets and trends for a skill.<br>
+No API key or Ponisha account is needed. It works in Claude, Cursor, Copilot and any other MCP client.
+
+[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server (model context protocol) for ponisha.ir: project search, project details, bids, freelancer search, public profiles, skills and categories, skill market summary.
+- **Install:** `uvx ponisha-mcp` or `claude mcp add ponisha -- uvx ponisha-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none. Optional `PONISHA_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
+- **Access:** read-only. It cannot log in, bid, post projects or message anyone, so no confirmation is needed before calling any tool.
+- **Tools:** 14, all prefixed `pn_`. Typical sequences: `pn_skills` -> `pn_search_projects` -> `pn_project` -> `pn_bids`; `pn_search_freelancers` -> `pn_profile`; `pn_skills` -> `pn_market` / `pn_trend`; `pn_profile` -> `pn_reviews` + `pn_portfolios`; `pn_services` -> `pn_service`.
+- **Use when:** the user wants freelance projects to bid on in Iran, what a kind of work pays, how crowded a project is, whether an employer is reliable, or who to hire for a skill.
+- **Do not use when:** the user wants to apply, message or post (read-only), or needs private contact data.
+- **Output:** compact JSON. Money is Toman. Times are Tehran time. Text is Persian user content.
+
+## Quick start
+
+```bash
+claude mcp add ponisha -- uvx ponisha-mcp
+```
+
+Any MCP client: command `uvx`, args `["ponisha-mcp"]`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `pn_search_projects` | Projects by text, skills, category, open/all, budget range, sort. |
+| `pn_project` | One project: brief, budget, deadline, employer track record, optional bid price sample. |
+| `pn_bids` | Offers on a project: price, days, pitch, bidder level and rating (paged). |
+| `pn_search_freelancers` | Freelancers by text, skills, level, portfolio, ranked by score. |
+| `pn_profile` | Public profile of a freelancer or employer. |
+| `pn_skills` | Skill name -> slug/id (about 700 skills). |
+| `pn_categories` | Top-level categories, or the sub-categories of one. |
+| `pn_market` | Open projects, budget quartiles, competition and related skills for one skill. |
+| `pn_trend` | Posting rate, median budget and bids for a skill sampled across its whole history. |
+| `pn_reviews` | Reviews of a user with score breakdown, or recent reviews for a skill. |
+| `pn_portfolios` | Search about 500k portfolio items, or list one user's. |
+| `pn_services` | Fixed-price service packages by category, price, rating. |
+| `pn_service` | One package: deliverables, requirements, paid add-ons. |
+| `pn_user_projects` | An employer's or freelancer's finished/open projects. |
+
+## FAQ
+
+**Is it official?** No. It reads the same public API the ponisha.ir web app uses for anonymous visitors.
+
+**Why are bids slow?** Ponisha serves the bids list slowly (seconds, up to 30 s on projects with 100+ bids). Keep `limit` small.
+
+**Why does the budget filter only look at one page?** The site has no budget filter. The tool scans up to 50 projects per page and keeps those whose range fits.
+
+## فارسی
+
+**ponisha-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای پونیشا (ponisha.ir) است. با آن می‌توانید پروژه‌ها را با کلمه، مهارت، دسته و بودجه جستجو کنید، پیشنهادهای ثبت‌شده و سابقه کارفرما را ببینید، فریلنسرها و پروفایل‌های عمومی را جستجو کنید و وضعیت بازار یک مهارت را بسنجید. بدون کلید API و حساب کاربری. نصب: `uvx ponisha-mcp`.
+
+مبلغ‌ها به تومان و زمان‌ها به وقت تهران (میلادی) هستند. این ابزار ثبت پیشنهاد، پیام یا ثبت پروژه انجام نمی‌دهد.
+
+Author: Sepehr Radmard (سپهر رادمرد) · github.com/sepehr071 · linkedin.com/in/sepehr-radmard

ponisha_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "ponisha-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for Ponisha (ponisha.ir), the Iranian freelance marketplace: projects, bids, freelancers, skill demand."
+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", "ponisha", "ponisha-ir", "freelance", "freelancer", "projects", "iran", "bids", "marketplace", "claude", "persian"]
+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/ponisha-mcp"
+Issues = "https://github.com/sepehr071/ponisha-mcp/issues"
+Website = "https://mcpfarsi.ir/"
+
+[project.scripts]
+ponisha-mcp = "ponisha_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 Ponisha APIs (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

ponisha_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/ponisha-mcp",
+  "title": "Ponisha Freelance",
+  "description": "Read-only Ponisha (ponisha.ir) freelance market: projects, bids, freelancers, skill demand.",
+  "repository": {
+    "url": "https://github.com/sepehr071/ponisha-mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/sepehr071/ponisha-mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "ponisha-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "PONISHA_MCP_PROXY",
+          "description": "Optional HTTP proxy URL for the Ponisha requests; system proxy settings are ignored. Also accepts a comma-separated list: one is used until it gets blocked or fails to connect, then the next.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

ponisha_mcp-0.1.0/src/ponisha_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Unofficial MCP server for Ponisha (ponisha.ir), the Iranian freelance marketplace: projects, bids, freelancers."""
+
+from importlib.metadata import version
+
+__version__ = version("ponisha-mcp")

ponisha_mcp-0.1.0/src/ponisha_mcp/http.py

@@ -0,0 +1,236 @@
+"""Shared async HTTP client for the public APIs behind ponisha.ir (project/freelancer search, project and profile data).
+
+Every tool goes through `fetch`, which caps concurrency, caches answers briefly and turns HTTP failures
+into `ToolError` messages the model can act on.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import json as json_lib
+import os
+import random
+import time
+from typing import Any
+
+import httpx
+from curl_cffi.const import CurlOpt
+from httpx_curl_cffi import AsyncCurlTransport
+from mcp.server.mcpserver.exceptions import ToolError
+
+API = "https://api.ponisha.ir/api/v1"
+SEARCH = "https://search.ponisha.ir/v1"
+SITE = "https://ponisha.ir"
+
+HEADERS = {
+    # User-Agent, sec-ch-ua and TLS come from the impersonated Chrome profile (see _get_client).
+    "Accept-Language": "fa-IR,fa;q=0.9,en;q=0.8",
+    "sec-fetch-dest": "empty",
+    "sec-fetch-mode": "cors",
+    "priority": "u=1, i",
+}
+
+MAX_CONCURRENCY = 3
+JITTER = (0.1, 0.4)  # seconds before each uncached call
+MAX_RETRIES = 1
+MAX_RETRY_WAIT = 10  # cap for Retry-After and backoff, seconds
+CACHE_TTL = 120  # seconds
+CACHE_MAX = 128
+RETRY_DELAY = 0.5  # seconds, doubled per retry
+MAX_BODY = 5_000_000  # bytes; larger responses are refused
+AXIOS = "application/json, text/plain, */*"
+# The web app (ponisha.ir) calls these API hosts cross-site with axios (checked in Chrome 2026-10-31).
+# Doubles as the host allowlist.
+HOSTS = {"api.ponisha.ir", "search.ponisha.ir"}
+
+_transport: httpx.AsyncBaseTransport | None = None
+_client: httpx.AsyncClient | None = None
+_limit: asyncio.Semaphore | None = None
+_proxy_index = 0
+_retired: set[asyncio.Task] = set()
+_cache: dict[tuple, tuple[float, Any]] = {}
+
+
+class _XhrTransport(AsyncCurlTransport):
+    """The Chrome profile sends navigation-only headers; a None value makes curl drop them on XHR calls."""
+
+    def _create_request_params(self, req: httpx.Request) -> dict[str, Any]:
+        # The parent drops "accept: */*" as an httpx default; curl would then send Chrome's page Accept instead.
+        accept = req.headers.get("accept")
+        p = super()._create_request_params(req)
+        extra = [(b"cache-control", None)]  # Chrome sends max-age=0 only on a reload
+        if req.headers.get("sec-fetch-mode") != "navigate":
+            extra += [(b"upgrade-insecure-requests", None), (b"sec-fetch-user", None)]
+        p["headers"] = [*p["headers"], *extra, *([(b"accept", b"*/*")] if accept == "*/*" else [])]
+        return p
+
+
+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):
+        super().__init__(message)
+        self.status = status
+
+
+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()
+
+
+def _proxies() -> list[str]:
+    """PONISHA_MCP_PROXY: one proxy URL, or a comma-separated list used one at a time."""
+    return [p.strip() for p in os.environ.get("PONISHA_MCP_PROXY", "").split(",") if p.strip()]
+
+
+def _next_proxy(client: httpx.AsyncClient) -> None:
+    """Sticky pool: move to the next proxy after a block or connect error; the next call rebuilds the client.
+
+    Only the client that failed may rotate. The old client is closed late because other requests may still use it.
+    """
+    global _client, _limit, _proxy_index
+    if len(_proxies()) < 2 or client is not _client:
+        return
+    _client, _limit, _proxy_index = None, None, _proxy_index + 1
+    t = asyncio.create_task(_close_later(client))
+    _retired.add(t)
+    t.add_done_callback(_retired.discard)
+
+
+async def _close_later(client: httpx.AsyncClient) -> None:
+    await asyncio.sleep(30)  # longer than the 60 s request timeout
+    await client.aclose()
+
+
+def _get_client() -> tuple[httpx.AsyncClient, asyncio.Semaphore]:
+    global _client, _limit
+    if _client is None:
+        # System proxy settings are ignored; the proxy only comes from PONISHA_MCP_PROXY. curl_cffi presents
+        # Chrome's TLS/HTTP2 fingerprint and default headers. The proxy goes to the transport.
+        proxies = _proxies()
+        _client = httpx.AsyncClient(
+            transport=_transport
+            or _XhrTransport(
+                impersonate="chrome",
+                default_headers=True,
+                curl_options={
+                    CurlOpt.NOPROXY: "*"
+                },  # httpx-curl-cffi drops its own NOPROXY unless this dict is non-empty
+                proxy=proxies[_proxy_index % len(proxies)] if proxies else None,
+                max_connections=2 * MAX_CONCURRENCY,
+            ),
+            headers=HEADERS,
+            timeout=httpx.Timeout(60, connect=5),
+            limits=httpx.Limits(max_connections=2 * MAX_CONCURRENCY),
+            follow_redirects=False,
+            trust_env=False,
+        )
+        _limit = asyncio.Semaphore(MAX_CONCURRENCY)
+    assert _limit is not None
+    return _client, _limit
+
+
+async def fetch(url: str, params: dict[str, Any] | None = None, body: dict[str, Any] | None = None) -> Any:
+    """GET (or POST `body` as JSON, the search host's form) an endpoint the way ponisha.ir does; return parsed JSON.
+
+    Retried up to MAX_RETRIES times on timeout, network error, 5xx or 429, with jittered exponential backoff or
+    after Retry-After when sent. 403 is never retried.
+    """
+    query = dict(params or {})
+    host = httpx.URL(url).host
+    if host not in HOSTS:
+        raise ApiError(f"Refusing to call unexpected host {host}.")
+    key = (url, tuple(sorted(query.items())), json_lib.dumps(body, sort_keys=True))
+    if (hit := _cache.get(key)) and time.monotonic() - hit[0] < CACHE_TTL:
+        return copy.deepcopy(hit[1])
+    # axios also sends Content-Type: application/json on GET (seen in Chrome on api.ponisha.ir).
+    headers = {
+        "Origin": SITE,
+        "Referer": f"{SITE}/",
+        "Accept": AXIOS,
+        "Content-Type": "application/json",
+        "sec-fetch-site": "same-site",
+    }
+    for attempt in range(MAX_RETRIES + 1):
+        last = attempt == MAX_RETRIES
+        wait = RETRY_DELAY * 2**attempt * random.uniform(1, 1.5)
+        try:
+            r, content = await _request(url, query, body, headers, host)
+        except ApiError as e:
+            if last or e.status is not None:
+                raise
+            await asyncio.sleep(min(wait, MAX_RETRY_WAIT))
+            continue
+        if (r.status_code == 429 or r.status_code >= 500) and not last:
+            await asyncio.sleep(min(_retry_after(r) or wait, MAX_RETRY_WAIT))
+            continue
+        break
+
+    if r.status_code >= 400:
+        raise ApiError(_status_message(r, host), r.status_code)
+    try:
+        data = json_lib.loads(content)
+    except ValueError as e:
+        raise ApiError(f"{host} returned a non-JSON response (HTTP {r.status_code}).", r.status_code) from e
+    if len(_cache) >= CACHE_MAX:
+        _cache.pop(next(iter(_cache)))
+    _cache[key] = (time.monotonic(), copy.deepcopy(data))
+    return data
+
+
+async def _send(client, limit, url, query, body, headers, host) -> tuple[httpx.Response, bytes]:
+    try:
+        async with limit:
+            await asyncio.sleep(random.uniform(*JITTER))
+            method = "POST" if body is not None else "GET"
+            async with client.stream(method, url, params=query, json=body, headers=headers) as r:
+                return r, await _read_capped(r, host)
+    except httpx.TimeoutException as e:
+        raise ApiError(f"{host} did not answer in time. Try again in a moment.") from e
+    except httpx.RequestError as e:
+        if isinstance(e, httpx.ConnectError | httpx.ProxyError):
+            _next_proxy(client)
+        raise ApiError(
+            f"Could not reach {host} ({type(e).__name__}). Check the internet connection "
+            "(or the PONISHA_MCP_PROXY setting if you use one)."
+        ) from e
+
+
+async def _request(url, query, body, headers, host) -> tuple[httpx.Response, bytes]:
+    client, limit = _get_client()
+    r, content = await _send(client, limit, url, query, body, headers, host)
+    if r.status_code in (403, 429):
+        _next_proxy(client)  # blocked: try the next proxy on the following call
+    return r, content
+
+
+async def _read_capped(r: httpx.Response, host: str) -> bytes:
+    """Read the body, refusing anything over MAX_BODY so one huge answer cannot flood memory or context."""
+    buf = bytearray()
+    async for chunk in r.aiter_bytes():
+        buf += chunk
+        if len(buf) > MAX_BODY:
+            raise ApiError(f"{host} sent a response over {MAX_BODY // 1_000_000} MB; refused.", r.status_code)
+    return bytes(buf)
+
+
+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, host: str) -> str:
+    code = r.status_code
+    if code == 403:
+        return f"{host} blocked the request (HTTP 403). Try another network or set PONISHA_MCP_PROXY."
+    if code == 404:
+        return f"{host} found nothing at that address (HTTP 404). Check the project id or username."
+    if code == 429:
+        return f"{host} is rate limiting requests (HTTP 429). Wait a minute before retrying."
+    if code >= 500:
+        return f"{host} had a server error (HTTP {code}). Try again later."
+    return f"{host} rejected the request (HTTP {code})."