fidibo-mcp 0.1.0__tar.gz

fidibo_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

fidibo_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/fidibo-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

fidibo_mcp-0.1.0/.gitignore

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

fidibo_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,70 @@
+# fidibo-mcp
+
+Unofficial, read-only MCP server for Fidibo (fidibo.com), an Iranian store for ebooks and audiobooks (Digikala group).
+Not published yet: no git repo, PyPI or MCP Registry release (planned: GitHub `sepehr071/fidibo-mcp`, PyPI `fidibo-mcp`).
+It is a sibling of `../shopino-mcp` and copies their layout and idioms; keep them in step.
+
+API map this server is built on (endpoints, samples, quirks, test report): `../fidibo/`.
+
+## Layout
+
+- `src/fidibo_mcp/http.py`: the only HTTP code. One shared `httpx.AsyncClient` (`trust_env=False`, proxy only from
+  `FIDIBO_MCP_PROXY`), a concurrency semaphore, `api(path, params, body=None)` for the JSON gateway
+  `https://api.fidibo.com` (GET, or POST when `body` is given: the book list is a read-only POST query), `result()`
+  for `data.result`, one retry on dropped connections and on an empty 200 body, HTTP 204 returns `{}`,
+  `ApiError(ToolError)`, `set_transport()` for tests.
+- `registry.py`: `@tool("Title")` collects tools. `server.py`: registers them with read-only annotations, holds `INSTRUCTIONS`.
+- Tools: `books.py` (search, browse, bestsellers, new, free, categories; also `_card`, `_scan`, `book_list`),
+  `detail.py` (book, reviews, similar), `people.py` (author, publisher). 11 tools, all `fd_*`.
+- `tests/`: `test_<module>.py` unit tests (MockTransport + trimmed real fixtures in `tests/fixtures/`),
+  `test_live_<module>.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 Fidibo 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 10 s
+```
+
+## Rules for changes
+
+- Read-only only. Never call login/OTP (`/identity/*`), basket / payment, library / shelves / favorites, review or
+  rating writes, `/flex/search/click`, the Fidibo Plus plans flow, or any analytics beacon.
+- Output units: prices in **Toman** (the API is Toman; nothing to convert; the site's Rial view is x10). Card:
+  `final_price` = `campaign.discounted_price` or `price` (what the customer pays), `price` = before discount (set to
+  `final_price` when there is no discount), `discount_pct` int computed, `free` = no `price` key (price 0), `in_plus` =
+  `badges.subscription`, `rating` absent when nobody voted.
+- 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.
+
+## Fidibo quirks (keep them)
+
+- No auth, token or header needed. `curl` gets an ArvanCloud 403 on fidibo.com pages (TLS fingerprint); httpx and
+  requests are fine, direct or through the proxy.
+- Envelope `{data: {result, total, per_page}}`; many lists are UI components (`{component, items[]}`): search lists
+  wrap cards in `result[0].items`, `POST /flex/list/book` returns cards directly in `result`. Empty page = HTTP 204.
+- `POST /flex/list/book?page&limit` body keys: `order` (BESTSELLER, WEEK_BESTSELLER, MONTH_BESTSELLER, POPULAR, RECENT,
+  LOWEST_PRICE, HIGHEST_PRICE), `contentType` [1,6] text / [2,7] audio, `categoryId` (numeric only; uuid or slug give an
+  empty reply), `authorId`, `publisherId`, `excludeBookId`, `free`, `subscription_only` (`subscription` is ignored),
+  `format`. No price-range filter anywhere: filter client-side (`_scan`, up to 3 pages). `total` is a constant 150.
+- `GET /flex/search/list/content` takes `query, order, contentType "[1,6]", page, size`; ignores every price / Plus /
+  free filter. `total` is the real count.
+- Category slug to numeric id: `GET /flex/{ebooks|audiobooks}/categories/{slug}` -> `action.inputs[categoryId]`
+  (same slug exists in both levels with different ids). Book `breadcrumb[].id` of `category_page` entries are the ids.
+- `GET /flex/book/reviews/{slug}` needs the full slug; a bare id or `?bookId=` hangs until timeout. Same for
+  `/flex/book/editions`. Do not call them.
+- Sorting by price (both APIs) follows the price to pay; free books come first in cheapest order.
+- No similar-books endpoint: `fd_similar` = bestsellers of the leaf category (parents as fallback).
+
+## 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 shopino-mcp, untested here) publishes to PyPI and the MCP Registry.

fidibo_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sepehr
+
+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.

fidibo_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: fidibo-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for Fidibo: search Persian ebooks and audiobooks, compare prices, find free and Fidibo Plus books, read reviews.
+Project-URL: Homepage, https://github.com/sepehr071/fidibo-mcp
+Project-URL: Source, https://github.com/sepehr071/fidibo-mcp
+Project-URL: Changelog, https://github.com/sepehr071/fidibo-mcp/releases
+Project-URL: Issues, https://github.com/sepehr071/fidibo-mcp/issues
+Author-email: Sepehr <sepehr@nextofx.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audiobook,books,ebook,fidibo,iran,mcp,model-context-protocol,persian
+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/fidibo-mcp -->
+
+# fidibo-mcp
+
+**Let your AI agent search Persian ebooks and audiobooks on Fidibo, compare prices, and find free and Fidibo Plus books.**
+
+Unofficial, read-only [MCP](https://modelcontextprotocol.io) server for [Fidibo](https://fidibo.com), the Iranian store
+for ebooks and audiobooks (Digikala group). Search by title or author, see the price in Toman with discount, check
+whether a book is free or in the Fidibo Plus subscription, read reviews, and browse bestsellers, new releases,
+categories, authors and publishers, all from Claude, Cursor or Copilot. No account, no API key, nothing is bought or
+changed.
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+claude mcp add fidibo -- uvx fidibo-mcp
+```
+
+Any other MCP client: command `uvx`, args `["fidibo-mcp"]`.
+
+## What it can do
+
+- Search books and audiobooks by title, author or keyword; sort by price or date; filter by price range, free, Fidibo Plus
+- Full record of a book: price and discount in **Toman**, format, pages or duration, narrators, rating with star distribution, Plus flag, description, printed price
+- Reader reviews, similar books, an author's or publisher's books
+- Bestsellers (week, month, all time), new releases, free books, any category
+
+## Tools
+
+All tools are read-only and start with `fd_`. Every book in a result is a compact card: `id`, `title`, `type` (ebook /
+audiobook / microbook ...), `authors`, `publisher`, `final_price` (what you pay) and `price` (before discount) in Toman,
+`discount_pct`, `free`, `in_plus`, `rating`, `url`.
+
+### Find books
+
+| Tool | What it does |
+|---|---|
+| `fd_search` | Search by title, author or keyword; `kind` ebook / audio; sort relevance, cheapest, most expensive, newest; price range, free and Plus filters |
+| `fd_browse` | List books of a category (or everything) by bestseller, popular, newest or price; free / Plus / price filters |
+| `fd_bestsellers` | Top sellers of the week, month or all time, per kind and category |
+| `fd_new` | Newest books and audiobooks |
+| `fd_free` | Free ebooks and audiobooks |
+| `fd_categories` | Category and sub-category slugs of a top level (ebooks, audiobooks, education, magazines, podcasts) |
+
+### One book, people
+
+| Tool | What it does |
+|---|---|
+| `fd_book` | Full record: price, discount, pages or duration, size, narrators, rating distribution, Plus flag, description, printed price |
+| `fd_reviews` | Reader reviews with stars, date and likes |
+| `fd_similar` | Bestsellers of the book's category (Fidibo has no similar-books endpoint) |
+| `fd_author` | An author's, translator's or narrator's profile and books (by id or name) |
+| `fd_publisher` | A publisher's profile and books (by id or name) |
+
+## Good to know
+
+- **Prices are Toman.** The API returns Toman (checked against the site); `final_price` is the price to pay after a campaign discount, `price` is before it. Free books have price 0.
+- `in_plus` means the book is in the Fidibo Plus subscription catalog; it still has a normal buy price.
+- Price range, free and Plus filters of `fd_search` are applied after fetching (up to 3 pages per call); use `next_page` to continue. `fd_browse` filters free and Plus on the server and the price range after fetching.
+- Fidibo lists are capped: the book list reports at most 150 matches, `fd_search` `total_matches` is the real count.
+- Persian queries work best.
+
+## Configuration
+
+The server calls `api.fidibo.com` directly and ignores system proxy variables. To use a proxy set `FIDIBO_MCP_PROXY=http://host:port`.
+
+## 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 `../fidibo/`.
+
+## Disclaimer
+
+Unofficial; not affiliated with Fidibo or Digikala. Read-only access to the data of public pages. Keep request rates low.
+
+## License
+
+MIT

fidibo_mcp-0.1.0/README.md

@@ -0,0 +1,87 @@
+<!-- mcp-name: io.github.sepehr071/fidibo-mcp -->
+
+# fidibo-mcp
+
+**Let your AI agent search Persian ebooks and audiobooks on Fidibo, compare prices, and find free and Fidibo Plus books.**
+
+Unofficial, read-only [MCP](https://modelcontextprotocol.io) server for [Fidibo](https://fidibo.com), the Iranian store
+for ebooks and audiobooks (Digikala group). Search by title or author, see the price in Toman with discount, check
+whether a book is free or in the Fidibo Plus subscription, read reviews, and browse bestsellers, new releases,
+categories, authors and publishers, all from Claude, Cursor or Copilot. No account, no API key, nothing is bought or
+changed.
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+claude mcp add fidibo -- uvx fidibo-mcp
+```
+
+Any other MCP client: command `uvx`, args `["fidibo-mcp"]`.
+
+## What it can do
+
+- Search books and audiobooks by title, author or keyword; sort by price or date; filter by price range, free, Fidibo Plus
+- Full record of a book: price and discount in **Toman**, format, pages or duration, narrators, rating with star distribution, Plus flag, description, printed price
+- Reader reviews, similar books, an author's or publisher's books
+- Bestsellers (week, month, all time), new releases, free books, any category
+
+## Tools
+
+All tools are read-only and start with `fd_`. Every book in a result is a compact card: `id`, `title`, `type` (ebook /
+audiobook / microbook ...), `authors`, `publisher`, `final_price` (what you pay) and `price` (before discount) in Toman,
+`discount_pct`, `free`, `in_plus`, `rating`, `url`.
+
+### Find books
+
+| Tool | What it does |
+|---|---|
+| `fd_search` | Search by title, author or keyword; `kind` ebook / audio; sort relevance, cheapest, most expensive, newest; price range, free and Plus filters |
+| `fd_browse` | List books of a category (or everything) by bestseller, popular, newest or price; free / Plus / price filters |
+| `fd_bestsellers` | Top sellers of the week, month or all time, per kind and category |
+| `fd_new` | Newest books and audiobooks |
+| `fd_free` | Free ebooks and audiobooks |
+| `fd_categories` | Category and sub-category slugs of a top level (ebooks, audiobooks, education, magazines, podcasts) |
+
+### One book, people
+
+| Tool | What it does |
+|---|---|
+| `fd_book` | Full record: price, discount, pages or duration, size, narrators, rating distribution, Plus flag, description, printed price |
+| `fd_reviews` | Reader reviews with stars, date and likes |
+| `fd_similar` | Bestsellers of the book's category (Fidibo has no similar-books endpoint) |
+| `fd_author` | An author's, translator's or narrator's profile and books (by id or name) |
+| `fd_publisher` | A publisher's profile and books (by id or name) |
+
+## Good to know
+
+- **Prices are Toman.** The API returns Toman (checked against the site); `final_price` is the price to pay after a campaign discount, `price` is before it. Free books have price 0.
+- `in_plus` means the book is in the Fidibo Plus subscription catalog; it still has a normal buy price.
+- Price range, free and Plus filters of `fd_search` are applied after fetching (up to 3 pages per call); use `next_page` to continue. `fd_browse` filters free and Plus on the server and the price range after fetching.
+- Fidibo lists are capped: the book list reports at most 150 matches, `fd_search` `total_matches` is the real count.
+- Persian queries work best.
+
+## Configuration
+
+The server calls `api.fidibo.com` directly and ignores system proxy variables. To use a proxy set `FIDIBO_MCP_PROXY=http://host:port`.
+
+## 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 `../fidibo/`.
+
+## Disclaimer
+
+Unofficial; not affiliated with Fidibo or Digikala. Read-only access to the data of public pages. Keep request rates low.
+
+## License
+
+MIT

fidibo_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "fidibo-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for Fidibo: search Persian ebooks and audiobooks, compare prices, find free and Fidibo Plus books, read reviews."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sepehr", email = "sepehr@nextofx.com" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "fidibo", "iran", "ebook", "audiobook", "books", "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",
+]
+
+[project.urls]
+Homepage = "https://github.com/sepehr071/fidibo-mcp"
+Source = "https://github.com/sepehr071/fidibo-mcp"
+Changelog = "https://github.com/sepehr071/fidibo-mcp/releases"
+Issues = "https://github.com/sepehr071/fidibo-mcp/issues"
+
+[project.scripts]
+fidibo-mcp = "fidibo_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 Fidibo API (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

fidibo_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/fidibo-mcp",
+  "title": "Fidibo",
+  "description": "Unofficial read-only Fidibo: search Persian ebooks and audiobooks, compare prices, free and Plus books, reviews.",
+  "repository": {
+    "url": "https://github.com/sepehr071/fidibo-mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/sepehr071/fidibo-mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "fidibo-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "FIDIBO_MCP_PROXY",
+          "description": "Optional HTTP proxy URL for requests to fidibo.com; system proxy settings are ignored.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

fidibo_mcp-0.1.0/src/fidibo_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Unofficial MCP server for Fidibo."""
+
+from importlib.metadata import version
+
+__version__ = version("fidibo-mcp")