30book-mcp 0.1.0__tar.gz

30book_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

30book_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/30book-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

30book_mcp-0.1.0/.gitignore

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

30book_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,71 @@
+# 30book-mcp
+
+Unofficial, read-only MCP server for 30book (30book.com), an Iranian online bookstore with about 200,000 printed books.
+Intended GitHub `sepehr071/30book-mcp`, PyPI `30book-mcp`, MCP Registry `io.github.sepehr071/30book-mcp` (not published yet,
+no git repo yet). Python package `sibook_mcp` (a module name cannot start with a digit). Sibling of `../shopino-mcp`
+and `../masterkala-mcp`; same layout and idioms, keep them in step.
+
+API map this server is built on (pages, circuit transport, quirks, test report): `../30book/`.
+
+## Layout
+
+- `src/sibook_mcp/http.py`: the only HTTP code. One shared `httpx.AsyncClient` (`trust_env=False`, proxy only from
+  `SIBOOK_MCP_PROXY`), `html(path)` for plain pages, `render(path, ready, type_into=)` for list pages (opens a Blazor
+  circuit, up to 3 attempts), `ApiError(ToolError)`, `set_transport()` for tests, `query()` builds `?a=1&b=True`.
+- `blazor.py`: the Blazor Server client (MessagePack + SignalR long polling + render-batch DOM). `dom.py`: tiny DOM and
+  HTML parser. `parse.py`: cards, book page, reviews to dicts (Toman ints). `registry.py` / `server.py`: tool registry,
+  `INSTRUCTIONS`.
+- Tools: `catalog.py` (search, browse, publisher, author, best sellers, new releases, deals, find publisher / person),
+  `product.py` (book, similar, reviews, categories, collections). 14 tools, all `sb_*`.
+- `tests/`: `test_tools.py` (tools on trimmed real pages in `tests/fixtures/`, `http.html` / `http.render` patched),
+  `test_blazor.py` (codecs, a synthetic render-batch writer, a scripted fake SignalR server), `test_http.py` (client,
+  errors, README tables), `test_live.py` (`@pytest.mark.live`, one test per tool, about 2 minutes).
+
+## Commands
+
+uv needs the local proxy to download packages; the server and tests call 30book 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            # offline
+uv run pytest -m live -q    # real site
+uv build
+```
+
+Git Bash mangles `/path` arguments: prefix with `MSYS_NO_PATHCONV=1` when passing site paths to scripts or curl.
+
+## Rules for changes
+
+- Read-only only. Never log in, never touch `/login`, `/basket`, `/profile`, the like / want-to-read / recommend buttons,
+  the comment form, contact forms or the analytics hosts. The only events ever fired are `input` and `click` on the
+  name box of `/publisher` and `/person`.
+- Output units: prices in **Toman**. HTML prices are Toman; the JSON-LD on book pages is Rial (x10) and only fills the
+  price of sold-out books. `price` = list price, `final_price` = to pay, `discount_pct` computed; `in_stock` false when
+  the page shows no price («ناموجود»). Stock is yes/no, never a count.
+- 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 on a real trimmed
+  fixture, a live test, a README tool-table row (a test checks the tables) and an `INSTRUCTIONS` mention.
+- Deps stay `mcp` + `httpx`. Write ZWNJ as `‌`, never the invisible character. Keep `Field(pattern=...)` small.
+
+## 30book quirks (keep them)
+
+- No JSON API. Book page / home / landing are plain HTML (cards present). Every list page is an empty shell until a
+  Blazor circuit draws it, so `http.render` is used; one list costs 2-5 s and about 10 requests. About 1 in 20 circuits
+  fails to render: `render` retries. Keep at most 2 circuits at once (`MAX_CIRCUITS`).
+- A markup frame counts as ONE logical child (the browser wraps its nodes in a container); components are logical
+  containers too. Getting this wrong shows up as a `stepIn` into a text node. Handler attributes are kept as `@click`.
+- Query params are the state: `pg` (0-based), `sort` 1-7, `qt=True`, `pub`, `wtr`, `inp`, `stp=True`. Dummy slugs redirect
+  (301) to the canonical URL and the redirect drops the query: resolve first, then append (done in `http.render`).
+- Category: `bts-N` section pages are landing pages only (no list); lists work for `bta-N-M` / `btf-N-M-K` (1 / 2 / 3
+  dummy slug segments). Award pages use a different layout (`loose` ready test, about 22 cards per page, sort ignored).
+- `/special-offers` is mostly stationery (`/product/..` links); `sb_deals` uses best sellers or a subject with `sort=7`.
+- Person / publisher name boxes match name fragments and miss some people (Arabic yeh / kaf in stored names).
+- `sort=4/5` follow the list price. No price-range filter, no result count (only the last page number).
+- `robots.txt` disallows `*/search` for crawlers; keep request rates low.
+
+## Release
+
+Bump `version` in `pyproject.toml` and both versions in `server.json`, `uv lock`, commit, `git tag vX.Y.Z && git push --tags`
+once a publish workflow is added (copy `.github/workflows` from `../shopino-mcp`). This file is local only.

30book_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.

30book_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: 30book-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for 30book (30book.com): search Iranian printed books, compare editions and publishers, prices in Toman, discounts, authors and bestsellers.
+Project-URL: Homepage, https://github.com/sepehr071/30book-mcp
+Project-URL: Source, https://github.com/sepehr071/30book-mcp
+Project-URL: Changelog, https://github.com/sepehr071/30book-mcp/releases
+Project-URL: Issues, https://github.com/sepehr071/30book-mcp/issues
+Author-email: Sepehr <sepehr@nextofx.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 30book,books,e-commerce,iran,mcp,model-context-protocol,persian,shopping
+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/30book-mcp -->
+
+# 30book-mcp
+
+**Let your AI agent search Iran's 30book bookstore.** Unofficial, read-only MCP server for [30book](https://www.30book.com)
+(about 200,000 printed books, Persian and foreign): search by title, compare editions and publishers, see list and
+discounted price in Toman, stock, pages, cover type, ISBN, print run, authors, translators, reviews, best sellers and
+discounts. No account, no API key, no login, no cart.
+
+[Quick start](#quick-start) · [Tools](#tools) · [How it works](#how-it-works) · [FAQ](#faq) · [فارسی](#فارسی)
+
+## Why
+
+30book has no public API and its list pages are drawn by a live Blazor Server session, so a plain scraper sees empty
+pages. This server speaks that protocol (SignalR long polling, no browser needed) and parses the book pages, so an
+agent can answer "cheapest edition of Little Prince with a hard cover", "everything by this translator under
+300,000 Toman" or "what are the best sellers in history" in a few calls.
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+claude mcp add 30book -- uvx 30book-mcp
+```
+
+Other clients (Claude Desktop, Cursor, VS Code): run the command `uvx` with argument `30book-mcp`.
+Behind a proxy, set `SIBOOK_MCP_PROXY=http://host:port` (system proxy variables are ignored on purpose).
+
+## Tools
+
+All tools are read-only and prefixed `sb_`. Prices are Toman.
+
+### Find books
+
+| Tool | What it does |
+|---|---|
+| `sb_search` | Search by title (exact phrase or word by word) with sort, in-stock, publisher, author and translator filters; 20 per page |
+| `sb_browse` | Books of a category (section, subject, topic), fiction genre, national literature, literary award or tag |
+| `sb_publisher` | One publisher's catalogue with a short description |
+| `sb_author` | Everything by one author or translator |
+| `sb_find_publisher` | Publisher name to id |
+| `sb_find_person` | Author / translator name to id |
+| `sb_categories` | Category sections and their subjects (codes for `sb_browse`) |
+| `sb_collections` | Genres, national literatures, award lists and current tags |
+
+### One book
+
+| Tool | What it does |
+|---|---|
+| `sb_book` | Price, final price, discount %, stock, authors, translators, publisher, pages, cover, size, ISBN, print run, year, categories, rating, description |
+| `sb_similar` | Similar books, more by the author, more by the translator |
+| `sb_reviews` | Reader comments with stars, plus the rating summary |
+
+### Popular and cheap
+
+| Tool | What it does |
+|---|---|
+| `sb_bestsellers` | Site-wide best sellers |
+| `sb_new_releases` | Newest books |
+| `sb_deals` | The discounted-books page, biggest discount first on request |
+
+## How it works
+
+- Book pages, the home page and landing pages are plain server-rendered HTML and are parsed directly.
+- Search, category, publisher, author, genre and tag pages are built after load by a Blazor Server circuit. The server
+  opens one over SignalR long polling, applies the binary render batches to a small DOM (`blazor.py`) and reads the
+  cards. Paging, sort and filters are URL query parameters (`pg`, `sort`, `qt`, `pub`, `wtr`, `inp`, `stp`), so no
+  clicks are simulated; only the name boxes on the publisher and author index pages use a fired event.
+- HTML prices are Toman; the JSON-LD on book pages is Rial (x10) and is only used for sold-out books.
+- List pages take 2 to 5 seconds, book pages about 1 second. Stock is yes/no only.
+
+## 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 pages
+uv run pytest -m live -q    # real site, one test per tool
+```
+
+API map and test report: `../30book/`.
+
+## FAQ
+
+**Does it buy anything?** No. It never logs in and never calls cart, checkout, wishlist or review endpoints.
+
+**Why is a search sometimes empty?** The site stores some names with Arabic yeh / kaf; try a shorter word or `extended=true`.
+
+**Is it affiliated with 30book?** No. Unofficial; keep the request rate low.
+
+## فارسی
+
+سرور MCP غیررسمی و فقط‌خواندنی برای فروشگاه کتاب ۳۰بوک: جستجوی کتاب، مقایسهٔ چاپ‌ها و ناشران، قیمت (تومان) و
+تخفیف، موجودی، مشخصات کتاب، نویسنده و مترجم، نظرات، پرفروش‌ها و تخفیف‌ها. نیازی به حساب یا کلید ندارد.
+
+نصب: `claude mcp add 30book -- uvx 30book-mcp`

30book_mcp-0.1.0/README.md

@@ -0,0 +1,98 @@
+<!-- mcp-name: io.github.sepehr071/30book-mcp -->
+
+# 30book-mcp
+
+**Let your AI agent search Iran's 30book bookstore.** Unofficial, read-only MCP server for [30book](https://www.30book.com)
+(about 200,000 printed books, Persian and foreign): search by title, compare editions and publishers, see list and
+discounted price in Toman, stock, pages, cover type, ISBN, print run, authors, translators, reviews, best sellers and
+discounts. No account, no API key, no login, no cart.
+
+[Quick start](#quick-start) · [Tools](#tools) · [How it works](#how-it-works) · [FAQ](#faq) · [فارسی](#فارسی)
+
+## Why
+
+30book has no public API and its list pages are drawn by a live Blazor Server session, so a plain scraper sees empty
+pages. This server speaks that protocol (SignalR long polling, no browser needed) and parses the book pages, so an
+agent can answer "cheapest edition of Little Prince with a hard cover", "everything by this translator under
+300,000 Toman" or "what are the best sellers in history" in a few calls.
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+claude mcp add 30book -- uvx 30book-mcp
+```
+
+Other clients (Claude Desktop, Cursor, VS Code): run the command `uvx` with argument `30book-mcp`.
+Behind a proxy, set `SIBOOK_MCP_PROXY=http://host:port` (system proxy variables are ignored on purpose).
+
+## Tools
+
+All tools are read-only and prefixed `sb_`. Prices are Toman.
+
+### Find books
+
+| Tool | What it does |
+|---|---|
+| `sb_search` | Search by title (exact phrase or word by word) with sort, in-stock, publisher, author and translator filters; 20 per page |
+| `sb_browse` | Books of a category (section, subject, topic), fiction genre, national literature, literary award or tag |
+| `sb_publisher` | One publisher's catalogue with a short description |
+| `sb_author` | Everything by one author or translator |
+| `sb_find_publisher` | Publisher name to id |
+| `sb_find_person` | Author / translator name to id |
+| `sb_categories` | Category sections and their subjects (codes for `sb_browse`) |
+| `sb_collections` | Genres, national literatures, award lists and current tags |
+
+### One book
+
+| Tool | What it does |
+|---|---|
+| `sb_book` | Price, final price, discount %, stock, authors, translators, publisher, pages, cover, size, ISBN, print run, year, categories, rating, description |
+| `sb_similar` | Similar books, more by the author, more by the translator |
+| `sb_reviews` | Reader comments with stars, plus the rating summary |
+
+### Popular and cheap
+
+| Tool | What it does |
+|---|---|
+| `sb_bestsellers` | Site-wide best sellers |
+| `sb_new_releases` | Newest books |
+| `sb_deals` | The discounted-books page, biggest discount first on request |
+
+## How it works
+
+- Book pages, the home page and landing pages are plain server-rendered HTML and are parsed directly.
+- Search, category, publisher, author, genre and tag pages are built after load by a Blazor Server circuit. The server
+  opens one over SignalR long polling, applies the binary render batches to a small DOM (`blazor.py`) and reads the
+  cards. Paging, sort and filters are URL query parameters (`pg`, `sort`, `qt`, `pub`, `wtr`, `inp`, `stp`), so no
+  clicks are simulated; only the name boxes on the publisher and author index pages use a fired event.
+- HTML prices are Toman; the JSON-LD on book pages is Rial (x10) and is only used for sold-out books.
+- List pages take 2 to 5 seconds, book pages about 1 second. Stock is yes/no only.
+
+## 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 pages
+uv run pytest -m live -q    # real site, one test per tool
+```
+
+API map and test report: `../30book/`.
+
+## FAQ
+
+**Does it buy anything?** No. It never logs in and never calls cart, checkout, wishlist or review endpoints.
+
+**Why is a search sometimes empty?** The site stores some names with Arabic yeh / kaf; try a shorter word or `extended=true`.
+
+**Is it affiliated with 30book?** No. Unofficial; keep the request rate low.
+
+## فارسی
+
+سرور MCP غیررسمی و فقط‌خواندنی برای فروشگاه کتاب ۳۰بوک: جستجوی کتاب، مقایسهٔ چاپ‌ها و ناشران، قیمت (تومان) و
+تخفیف، موجودی، مشخصات کتاب، نویسنده و مترجم، نظرات، پرفروش‌ها و تخفیف‌ها. نیازی به حساب یا کلید ندارد.
+
+نصب: `claude mcp add 30book -- uvx 30book-mcp`

30book_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "30book-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for 30book (30book.com): search Iranian printed books, compare editions and publishers, prices in Toman, discounts, authors and bestsellers."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sepehr", email = "sepehr@nextofx.com" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "30book", "iran", "books", "e-commerce", "shopping", "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/30book-mcp"
+Source = "https://github.com/sepehr071/30book-mcp"
+Changelog = "https://github.com/sepehr071/30book-mcp/releases"
+Issues = "https://github.com/sepehr071/30book-mcp/issues"
+
+[project.scripts]
+30book-mcp = "sibook_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sibook_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not live'"
+markers = ["live: calls the real 30book 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

30book_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/30book-mcp",
+  "title": "30book",
+  "description": "Unofficial read-only 30book: search Iranian printed books, compare editions and prices.",
+  "repository": {
+    "url": "https://github.com/sepehr071/30book-mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/sepehr071/30book-mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "30book-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "SIBOOK_MCP_PROXY",
+          "description": "Optional HTTP proxy URL for requests to 30book.com; system proxy settings are ignored.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

30book_mcp-0.1.0/src/sibook_mcp/__init__.py

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