basalam-mcp 0.1.0__tar.gz

basalam_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

basalam_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/basalam-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

basalam_mcp-0.1.0/.gitignore

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

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

basalam_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: basalam-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for Basalam: search marketplace products, find the cheapest offers, read shops, categories and reviews.
+Project-URL: Homepage, https://github.com/sepehr071/basalam-mcp
+Project-URL: Issues, https://github.com/sepehr071/basalam-mcp/issues
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: basalam,iran,marketplace,mcp,model-context-protocol,price-comparison
+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/basalam-mcp -->
+
+# basalam-mcp: Basalam marketplace MCP server for AI agents
+
+**Let your AI agent shop on Basalam (باسلام).** An unofficial, read-only MCP server for Iran's marketplace of
+independent shops: search products with price, category, shipping and discount filters, find the cheapest in-stock
+offers, read product details, shops, categories and customer reviews, all from Claude, Cursor or Copilot.
+
+## For AI agents
+
+- **What:** unofficial MCP server for Basalam (basalam.com). Queries in Persian match best; prices in Toman.
+- **Install:** `uvx basalam-mcp` or `claude mcp add basalam -- uvx basalam-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none, no API key or account. Basalam answers from non-Iranian IPs too.
+- **Optional env:** `BASALAM_MCP_PROXY`, an HTTP proxy URL (or a comma-separated list). System proxy settings are ignored on purpose.
+- **Read-only:** no login, basket, order, chat or review posting.
+
+## Quick start
+
+```bash
+claude mcp add basalam -- uvx basalam-mcp
+```
+
+Or in any MCP client config: `{"command": "uvx", "args": ["basalam-mcp"]}`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `bs_search` | Search products; filters: price range (Toman), category, free shipping, discount, top shops, installments; sort by relevance, sales, price, newest. |
+| `bs_find_cheapest` | Cheapest in-stock offers for a query, cheapest first, with a price floor and optional minimum rating. |
+| `bs_product` | One product: price, discount, stock, sales count, free-shipping threshold, options (sizes, colors), attributes, rating, shop. |
+| `bs_vendor` | A shop's profile: city, activity, product count, shipping methods. |
+| `bs_vendor_products` | One shop's products, searchable, filterable and sortable; an unknown shop is an error. |
+| `bs_categories` | The category tree: top level, children of an id, or search by name (inside `parent_id` when both are given). Ids feed `category_id`. |
+| `bs_reviews` | Customer reviews with the star histogram of the product and its shop. |
+
+## Notes
+
+- Prices are Toman. The upstream API reports Rial; the server divides by 10.
+- Result totals stop at 10000 (the search index cap). Pages hold at most 30 products (keeps each reply under 15 KB; a product's link is `https://basalam.com/p/<id>`), and a short page is refilled from the following rows, so neighbouring pages can repeat a few products.
+- The cheapest sort is full of filler listings priced at a few hundred Toman; `bs_find_cheapest` hides prices under 5000 Toman by default.
+- Dates and times are passed through as Basalam returns them (Iran local time, not converted; unconfirmed). The vendor API's own `score` field is always 0, so it is not exposed; use the shop stars from `bs_reviews`.
+- Review and description text is user-generated and cut to 400 characters unless `full_text=true`.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run python -m pytest -q          # offline unit tests
+uv run python -m pytest -m live -q  # one live test per tool
+uv build
+```
+
+Unofficial: not affiliated with Basalam. MIT License.

basalam_mcp-0.1.0/README.md

@@ -0,0 +1,55 @@
+<!-- mcp-name: io.github.sepehr071/basalam-mcp -->
+
+# basalam-mcp: Basalam marketplace MCP server for AI agents
+
+**Let your AI agent shop on Basalam (باسلام).** An unofficial, read-only MCP server for Iran's marketplace of
+independent shops: search products with price, category, shipping and discount filters, find the cheapest in-stock
+offers, read product details, shops, categories and customer reviews, all from Claude, Cursor or Copilot.
+
+## For AI agents
+
+- **What:** unofficial MCP server for Basalam (basalam.com). Queries in Persian match best; prices in Toman.
+- **Install:** `uvx basalam-mcp` or `claude mcp add basalam -- uvx basalam-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none, no API key or account. Basalam answers from non-Iranian IPs too.
+- **Optional env:** `BASALAM_MCP_PROXY`, an HTTP proxy URL (or a comma-separated list). System proxy settings are ignored on purpose.
+- **Read-only:** no login, basket, order, chat or review posting.
+
+## Quick start
+
+```bash
+claude mcp add basalam -- uvx basalam-mcp
+```
+
+Or in any MCP client config: `{"command": "uvx", "args": ["basalam-mcp"]}`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `bs_search` | Search products; filters: price range (Toman), category, free shipping, discount, top shops, installments; sort by relevance, sales, price, newest. |
+| `bs_find_cheapest` | Cheapest in-stock offers for a query, cheapest first, with a price floor and optional minimum rating. |
+| `bs_product` | One product: price, discount, stock, sales count, free-shipping threshold, options (sizes, colors), attributes, rating, shop. |
+| `bs_vendor` | A shop's profile: city, activity, product count, shipping methods. |
+| `bs_vendor_products` | One shop's products, searchable, filterable and sortable; an unknown shop is an error. |
+| `bs_categories` | The category tree: top level, children of an id, or search by name (inside `parent_id` when both are given). Ids feed `category_id`. |
+| `bs_reviews` | Customer reviews with the star histogram of the product and its shop. |
+
+## Notes
+
+- Prices are Toman. The upstream API reports Rial; the server divides by 10.
+- Result totals stop at 10000 (the search index cap). Pages hold at most 30 products (keeps each reply under 15 KB; a product's link is `https://basalam.com/p/<id>`), and a short page is refilled from the following rows, so neighbouring pages can repeat a few products.
+- The cheapest sort is full of filler listings priced at a few hundred Toman; `bs_find_cheapest` hides prices under 5000 Toman by default.
+- Dates and times are passed through as Basalam returns them (Iran local time, not converted; unconfirmed). The vendor API's own `score` field is always 0, so it is not exposed; use the shop stars from `bs_reviews`.
+- Review and description text is user-generated and cut to 400 characters unless `full_text=true`.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run python -m pytest -q          # offline unit tests
+uv run python -m pytest -m live -q  # one live test per tool
+uv build
+```
+
+Unofficial: not affiliated with Basalam. MIT License.

basalam_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "basalam-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for Basalam: search marketplace products, find the cheapest offers, read shops, categories and reviews."
+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", "basalam", "iran", "marketplace", "price-comparison"]
+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/basalam-mcp"
+Issues = "https://github.com/sepehr071/basalam-mcp/issues"
+
+[project.scripts]
+basalam-mcp = "basalam_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 Basalam 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

basalam_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/basalam-mcp",
+  "title": "Basalam",
+  "description": "Unofficial read-only Basalam marketplace: search products, cheapest offers, shops, reviews.",
+  "repository": {
+    "url": "https://github.com/sepehr071/basalam-mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/sepehr071/basalam-mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "basalam-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "BASALAM_MCP_PROXY",
+          "description": "Optional HTTP proxy URL; 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
+        }
+      ]
+    }
+  ]
+}

basalam_mcp-0.1.0/src/basalam_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Unofficial MCP server for the Basalam marketplace."""
+
+from importlib.metadata import version
+
+__version__ = version("basalam-mcp")

basalam_mcp-0.1.0/src/basalam_mcp/catalog.py

@@ -0,0 +1,260 @@
+"""Product search, cheapest offers and the category tree."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import Field
+
+from .http import CORE, SERVICES, fetch
+from .registry import clip, tool
+
+SORTS = {"relevance": "rank", "bestselling": "sales", "cheapest": "price", "expensive": "pricedesc", "newest": "newest"}
+
+Query = Annotated[
+    str, Field(min_length=1, pattern=r"\S", description="Search words, Persian matches best, e.g. 'عسل طبیعی'.")
+]
+MinPrice = Annotated[int | None, Field(ge=0, description="Lowest price in Toman, e.g. 100000.")]
+MaxPrice = Annotated[int | None, Field(ge=0, description="Highest price in Toman, e.g. 500000.")]
+CategoryId = Annotated[
+    int | None, Field(ge=1, description="Category id from bs_categories (any level), e.g. 172 for honey.")
+]
+FreeShipping = Annotated[bool, Field(description="Only products with free shipping to the whole country.")]
+HasDiscount = Annotated[bool, Field(description="Only products with a discount or coupon.")]
+TopVendors = Annotated[bool, Field(description="Only products from top-rated shops (غرفه برتر).")]
+Installments = Annotated[bool, Field(description="Only products that can be bought in installments (قسطی).")]
+
+
+def toman(rial: float | int | None) -> int | None:
+    """Basalam prices are Rial; the tools speak Toman."""
+    return None if rial is None else round(rial / 10)
+
+
+def card(p: dict[str, Any]) -> dict[str, Any]:
+    """One compact product row from a search hit."""
+    price, old = p.get("price"), p.get("primaryPrice")
+    v, r = p.get("vendor") or {}, p.get("rating") or {}
+    return {
+        "id": p["id"],
+        "name": clip(p.get("name"), n=100),
+        "price": toman(price),
+        "original_price": toman(old) if old and price and old > price else None,
+        "discount_pct": round((1 - price / old) * 100) if old and price and old > price else None,
+        "rating": r.get("average") or None,
+        "rating_count": r.get("count") or None,
+        "free_shipping": p.get("isFreeShipping") or None,
+        "in_stock": p.get("IsAvailable"),
+        "stock": p.get("stock"),
+        "unit": p.get("mainAttribute"),
+        "category": p.get("categoryTitle"),
+        "shop": v.get("name"),
+        "shop_id": v.get("identifier"),
+    }
+
+
+def search_params(
+    query: str | None,
+    sort: str,
+    min_price: int | None,
+    max_price: int | None,
+    category_id: int | None,
+    free_shipping: bool,
+    has_discount: bool,
+    top_vendors: bool,
+    installments: bool,
+    vendor: str | None,
+    start: int,
+    size: int,
+) -> dict[str, Any]:
+    flags = {
+        "freeShipping": free_shipping,
+        "hasDiscount": has_discount,
+        "vendorScore": top_vendors,
+        "salampay": installments,
+    }
+    p: dict[str, Any] = {"q": query, "sort": SORTS[sort], "from": start, "size": size}
+    p["filters.minPrice"] = min_price * 10 if min_price is not None else None  # API takes Rial
+    p["filters.maxPrice"] = max_price * 10 if max_price is not None else None
+    p["filters.categories"] = category_id
+    p["filters.vendorIdentifier"] = vendor
+    p.update({f"filters.{k}": "true" for k, on in flags.items() if on})
+    return p
+
+
+async def run_search(**kw: Any) -> tuple[list[dict[str, Any]], int]:
+    """Fetch one search page; return deduplicated cards and the total match count (the API caps it at 10000).
+
+    The API drops duplicate rows, so a page can come back short; the missing ones are fetched from the rows after it
+    (at most 5 requests), which means neighbouring pages can repeat a few products.
+    """
+    start, size = kw.pop("start"), kw.pop("size")
+    seen: set[int] = set()
+    cards: list[dict[str, Any]] = []
+    total = 0
+    for _ in range(5):
+        want = size - len(cards)
+        body = await fetch(f"{SERVICES}/search/product/search", search_params(**kw, start=start, size=want))
+        rows = body.get("products", [])
+        for p in rows:
+            if p["id"] not in seen:
+                seen.add(p["id"])
+                cards.append(card(p))
+        total = (body.get("meta") or {}).get("count", len(cards))
+        start += want
+        if len(cards) >= size or not rows or start >= total:
+            break
+    return cards, total
+
+
+@tool("Search products")
+async def bs_search(
+    query: Query,
+    sort: Annotated[
+        Literal["relevance", "bestselling", "cheapest", "expensive", "newest"], Field(description="Result order.")
+    ] = "relevance",
+    min_price: MinPrice = None,
+    max_price: MaxPrice = None,
+    category_id: CategoryId = None,
+    free_shipping: FreeShipping = False,
+    has_discount: HasDiscount = False,
+    top_vendors: TopVendors = False,
+    installments: Installments = False,
+    page: Annotated[int, Field(ge=1, le=200, description="Page number, 1-based.")] = 1,
+    limit: Annotated[
+        int, Field(ge=1, le=30, description="Products per page (max 30, keeps the reply under 15 KB).")
+    ] = 12,
+) -> dict[str, Any]:
+    """Search Basalam products and return a page of cards with prices in Toman.
+
+    Use for browsing a product type; the filters and sort run on the server. To rank by real price use
+    bs_find_cheapest, for one product bs_product, for one shop's catalog bs_vendor_products. A product's link is
+    https://basalam.com/p/<id>; neighbouring pages can repeat a few products.
+    """
+    cards, total = await run_search(
+        query=query,
+        sort=sort,
+        min_price=min_price,
+        max_price=max_price,
+        category_id=category_id,
+        free_shipping=free_shipping,
+        has_discount=has_discount,
+        top_vendors=top_vendors,
+        installments=installments,
+        vendor=None,
+        start=(page - 1) * limit,
+        size=limit,
+    )
+    return {"total": total, "page": page, "products": cards[:limit]}
+
+
+@tool("Find cheapest products")
+async def bs_find_cheapest(
+    query: Query,
+    min_price: Annotated[
+        int,
+        Field(
+            ge=0,
+            description="Lowest price in Toman. Default 5000 hides sample or filler listings that cost a few hundred.",
+        ),
+    ] = 5000,
+    max_price: MaxPrice = None,
+    category_id: CategoryId = None,
+    free_shipping: FreeShipping = False,
+    top_vendors: TopVendors = False,
+    rating_min: Annotated[
+        float, Field(ge=0, le=5, description="Drop products rated below this; above 0 also drops unrated ones.")
+    ] = 0,
+    limit: Annotated[int, Field(ge=1, le=30, description="Offers to return.")] = 10,
+) -> dict[str, Any]:
+    """List the cheapest in-stock offers for a query, cheapest first, prices in Toman.
+
+    Reads the server's price-ascending sort (two pages of 48), drops out-of-stock items and, with rating_min,
+    low-rated ones. Raise min_price when results are still accessories; narrow with category_id from bs_categories.
+    """
+    offers: list[dict[str, Any]] = []
+    total = 0
+    for start in (0, 48):
+        cards, total = await run_search(
+            query=query,
+            sort="cheapest",
+            min_price=min_price,
+            max_price=max_price,
+            category_id=category_id,
+            free_shipping=free_shipping,
+            has_discount=False,
+            top_vendors=top_vendors,
+            installments=False,
+            vendor=None,
+            start=start,
+            size=48,
+        )
+        offers += [c for c in cards if c["in_stock"] is not False and (c.get("rating") or 0) >= rating_min]
+        if len(offers) >= limit or len(cards) < 48:
+            break
+    offers.sort(key=lambda c: c["price"] or 0)
+    return {"total_matches": total, "offers": offers[:limit]}
+
+
+def _node(c: dict[str, Any]) -> dict[str, Any]:
+    return {"id": c["id"], "title": c["title"], "children": len(c.get("children") or [])}
+
+
+def _find(nodes: list[dict[str, Any]], cid: int) -> dict[str, Any] | None:
+    for n in nodes:
+        if n["id"] == cid:
+            return n
+        if hit := _find(n.get("children") or [], cid):
+            return hit
+    return None
+
+
+@tool("List categories")
+async def bs_categories(
+    parent_id: Annotated[
+        int | None, Field(ge=1, description="Category id to list the children of, e.g. 1 (food). Omit for top level.")
+    ] = None,
+    query: Annotated[
+        str | None,
+        Field(
+            min_length=2,
+            description="Find categories whose title contains this, at any depth (inside parent_id when given), e.g. 'عسل'.",
+        ),
+    ] = None,
+) -> dict[str, Any]:
+    """Browse Basalam's category tree and return ids for the category_id filter of bs_search.
+
+    Without arguments lists the 12 top-level categories; pass parent_id to go one level down, or query to
+    find a category by name anywhere in the tree (returns its path). With both, query searches only inside
+    parent_id's subtree. Ids at any level work as filters.
+    """
+    tree = await fetch(f"{CORE}/category")
+    if query:
+        root = tree
+        base: list[str] = []
+        if parent_id is not None:
+            parent = _find(tree, parent_id)
+            if parent is None:
+                return {"categories": [], "note": f"No category {parent_id}."}
+            root, base = parent.get("children") or [], [parent["title"]]
+
+        def norm(s: str) -> str:  # ZWNJ as space, Arabic yeh/kaf as Persian
+            return s.replace("\u200c", " ").replace("\u064a", "\u06cc").replace("\u0643", "\u06a9")
+
+        q = norm(query)
+        hits: list[dict[str, Any]] = []
+
+        def walk(nodes: list[dict[str, Any]], path: list[str]) -> None:
+            for n in nodes:
+                here = [*path, n["title"]]
+                if q in norm(n["title"]) and len(hits) < 30:
+                    hits.append({**_node(n), "path": " > ".join(here)})
+                walk(n.get("children") or [], here)
+
+        walk(root, base)
+        return {"categories": hits}
+    if parent_id is None:
+        return {"categories": [_node(c) for c in tree]}
+    parent = _find(tree, parent_id)
+    if parent is None:
+        return {"categories": [], "note": f"No category {parent_id}."}
+    return {"parent": parent["title"], "categories": [_node(c) for c in parent.get("children") or []]}