taaghche-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- taaghche_mcp-0.1.0/.github/workflows/ci.yml +22 -0
- taaghche_mcp-0.1.0/.github/workflows/publish.yml +51 -0
- taaghche_mcp-0.1.0/.gitignore +6 -0
- taaghche_mcp-0.1.0/CLAUDE.md +61 -0
- taaghche_mcp-0.1.0/LICENSE +21 -0
- taaghche_mcp-0.1.0/PKG-INFO +121 -0
- taaghche_mcp-0.1.0/README.md +95 -0
- taaghche_mcp-0.1.0/pyproject.toml +54 -0
- taaghche_mcp-0.1.0/server.json +32 -0
- taaghche_mcp-0.1.0/src/taaghche_mcp/__init__.py +5 -0
- taaghche_mcp-0.1.0/src/taaghche_mcp/books.py +334 -0
- taaghche_mcp-0.1.0/src/taaghche_mcp/browse.py +320 -0
- taaghche_mcp-0.1.0/src/taaghche_mcp/http.py +126 -0
- taaghche_mcp-0.1.0/src/taaghche_mcp/registry.py +16 -0
- taaghche_mcp-0.1.0/src/taaghche_mcp/server.py +57 -0
- taaghche_mcp-0.1.0/tests/conftest.py +71 -0
- taaghche_mcp-0.1.0/tests/fixtures/book_audio.json +736 -0
- taaghche_mcp-0.1.0/tests/fixtures/book_ebook.json +698 -0
- taaghche_mcp-0.1.0/tests/fixtures/comments.json +95 -0
- taaghche_mcp-0.1.0/tests/fixtures/hint.json +53 -0
- taaghche_mcp-0.1.0/tests/fixtures/home_nav.html +1 -0
- taaghche_mcp-0.1.0/tests/fixtures/listing.json +450 -0
- taaghche_mcp-0.1.0/tests/fixtures/listing_p2.json +370 -0
- taaghche_mcp-0.1.0/tests/fixtures/priceinfo.json +13 -0
- taaghche_mcp-0.1.0/tests/fixtures/search.json +335 -0
- taaghche_mcp-0.1.0/tests/fixtures/slug_author.json +937 -0
- taaghche_mcp-0.1.0/tests/fixtures/slug_category.json +844 -0
- taaghche_mcp-0.1.0/tests/fixtures/slug_publisher.json +850 -0
- taaghche_mcp-0.1.0/tests/test_books.py +133 -0
- taaghche_mcp-0.1.0/tests/test_browse.py +121 -0
- taaghche_mcp-0.1.0/tests/test_http.py +96 -0
- taaghche_mcp-0.1.0/tests/test_live_books.py +56 -0
- taaghche_mcp-0.1.0/tests/test_live_browse.py +62 -0
- taaghche_mcp-0.1.0/uv.lock +1173 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ["3.10", "3.11", "3.12", "3.13"]
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v7
|
|
16
|
+
- uses: astral-sh/setup-uv@v10.2.0
|
|
17
|
+
with:
|
|
18
|
+
python-version: ${{ matrix.python }}
|
|
19
|
+
- run: uv sync --locked
|
|
20
|
+
- run: uv run ruff check .
|
|
21
|
+
- run: uv run ruff format --check .
|
|
22
|
+
- run: uv run pytest -q
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
name: Publish
|
|
2
|
+
|
|
3
|
+
# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
|
|
4
|
+
# pyproject.toml and server.json.
|
|
5
|
+
on:
|
|
6
|
+
push:
|
|
7
|
+
tags: ["v*"]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
pypi:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
environment: pypi
|
|
13
|
+
permissions:
|
|
14
|
+
id-token: write # PyPI trusted publishing
|
|
15
|
+
contents: write # GitHub Release
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v7
|
|
18
|
+
- uses: astral-sh/setup-uv@v10.2.0
|
|
19
|
+
- name: Check versions match the tag
|
|
20
|
+
run: |
|
|
21
|
+
TAG=${GITHUB_REF_NAME#v}
|
|
22
|
+
grep -q "^version = \"$TAG\"" pyproject.toml
|
|
23
|
+
test "$(jq -r .version server.json)" = "$TAG"
|
|
24
|
+
test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
|
|
25
|
+
- run: uv sync --locked && uv run pytest -q
|
|
26
|
+
- run: uv build
|
|
27
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
28
|
+
- run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
|
|
29
|
+
env:
|
|
30
|
+
GH_TOKEN: ${{ github.token }}
|
|
31
|
+
|
|
32
|
+
mcp-registry:
|
|
33
|
+
needs: pypi
|
|
34
|
+
runs-on: ubuntu-latest
|
|
35
|
+
permissions:
|
|
36
|
+
id-token: write # MCP Registry login via GitHub OIDC
|
|
37
|
+
contents: read
|
|
38
|
+
steps:
|
|
39
|
+
- uses: actions/checkout@v7
|
|
40
|
+
- name: Wait for PyPI to serve the new version
|
|
41
|
+
run: |
|
|
42
|
+
for i in $(seq 1 30); do
|
|
43
|
+
curl -sf "https://pypi.org/pypi/taaghche-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
|
|
44
|
+
sleep 10
|
|
45
|
+
done
|
|
46
|
+
exit 1
|
|
47
|
+
- name: Install mcp-publisher
|
|
48
|
+
run: |
|
|
49
|
+
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
|
|
50
|
+
- run: ./mcp-publisher login github-oidc
|
|
51
|
+
- run: ./mcp-publisher publish
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# taaghche-mcp
|
|
2
|
+
|
|
3
|
+
Unofficial, read-only MCP server for Taaghche (taaghche.com), an Iranian ebook and audiobook store (about 220,000 titles).
|
|
4
|
+
Not published yet (no git repo, no PyPI / registry entry). It is a sibling of `../shopino-mcp` and copies its layout and idioms; keep them in step.
|
|
5
|
+
|
|
6
|
+
API map this server is built on (endpoints, samples, quirks, test report): `../taaghche/`.
|
|
7
|
+
|
|
8
|
+
## Layout
|
|
9
|
+
|
|
10
|
+
- `src/taaghche_mcp/http.py`: the only HTTP code. One shared `httpx.AsyncClient` (`trust_env=False`, proxy only from
|
|
11
|
+
`TAAGHCHE_MCP_PROXY`), a concurrency semaphore, `api(path, params, host=GET)` for JSON on `get.taaghche.com`
|
|
12
|
+
(or `EXPLORE`), `page(path)` for the home page HTML, one retry on dropped connections and on an empty 200 body,
|
|
13
|
+
`ApiError(ToolError)`, `set_transport()` for tests. Always sends `trackingData` where the site does (see quirks).
|
|
14
|
+
- `registry.py`: `@tool("Title")` collects tools. `server.py`: registers them with read-only annotations, holds `INSTRUCTIONS`.
|
|
15
|
+
- Tools: `books.py` (search, suggest, book, reviews, similar; also the shared `_card` / `_prices` helpers) and
|
|
16
|
+
`browse.py` (categories, browse, bestsellers, new releases, free books, author, publisher). 12 tools, all `tg_*`.
|
|
17
|
+
- `tests/`: `test_<module>.py` unit tests (MockTransport + trimmed real fixtures in `tests/fixtures/`),
|
|
18
|
+
`test_live_<module>.py` live tests (`@pytest.mark.live`), `test_http.py` for the client and the README tool tables.
|
|
19
|
+
|
|
20
|
+
## Commands
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
export HTTPS_PROXY=http://127.0.0.1:10898 HTTP_PROXY=http://127.0.0.1:10898 # uv downloads only
|
|
24
|
+
uv sync
|
|
25
|
+
uv run ruff check . && uv run ruff format --check .
|
|
26
|
+
uv run pytest -q # unit tests, offline
|
|
27
|
+
uv run pytest -m live -q # one live test per tool, about 10 s
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Rules for changes
|
|
31
|
+
|
|
32
|
+
- Read-only only. Never call login / OTP (`/v4/site/auth/*`), `/mybook/*` (library, orders, purchase), reviews or
|
|
33
|
+
quote like / reply / post (`/v2/reviews*` POST, `/v1/quotes/*` POST), `/v3/click`, `/api/metrics`, profile, payment or
|
|
34
|
+
gift endpoints.
|
|
35
|
+
- Prices: the API returns **Toman**; nothing to convert. `final_price` = API `price` (what the customer pays),
|
|
36
|
+
`price` = `beforeOffPrice` when higher, `discount_pct` computed, `free` when 0. Rating 0-5, `null` with no votes.
|
|
37
|
+
- New tool: `@tool("Title")` async function, every param `Annotated[..., Field(...)]` with constraints and an example,
|
|
38
|
+
docstring = what it returns + when to use + what to call next, compact dict output. Add a unit test with a real
|
|
39
|
+
trimmed fixture, a live test, a README tool-table row, and an `INSTRUCTIONS` mention.
|
|
40
|
+
- Keep `README.md` tool tables equal to `list_tools()` (a unit test checks it). Deps stay `mcp` + `httpx` only.
|
|
41
|
+
- ZWNJ in code is written ``, never the invisible character.
|
|
42
|
+
|
|
43
|
+
## Taaghche quirks (keep them)
|
|
44
|
+
|
|
45
|
+
- Hosts: `get.taaghche.com` (books, comments, lists, search; same-site CORS, no auth), `explore.taaghche.com`
|
|
46
|
+
(`/v3/hint` suggestions), `quote.taaghche.com` (quotes, not used), home page HTML for the category menu.
|
|
47
|
+
`gw.taaghche.com` is the account / library gateway: not used.
|
|
48
|
+
- `/v2/everything` needs `trackingData=110160240` (the site's constant): without it the reply is the shelf layout
|
|
49
|
+
(`boxes`) instead of `bookList`. With `filters=` it lists 16 books; with `slug=` it returns the page (shelves, bio,
|
|
50
|
+
`breadcrumb` = type + id of the category / author / publisher). First page `offset=null`, then the reply's `nextOffset`
|
|
51
|
+
(looks like `0-0-16-16`). `offset=0-0-0-0` gives an empty list.
|
|
52
|
+
- Filter types (`{"list":[{"type":N,"value":V}]}`): 1 category id, 2 author id, 3 publisher id, 6 price (only `"0"` = free works;
|
|
53
|
+
`"-30000"` and `"10000-30000"` are accepted and ignored, so price ceilings are applied client-side, up to 5 pages), 21 book type (0 ebook, 1 audiobook), 22 discounted (value 1),
|
|
54
|
+
50 target (1 = audio only, 0 = no filter), 20 collection / tag id. Several filters combine. Orders: 1 hot, 5 newest,
|
|
55
|
+
7 most downloaded, 2 alphabetical, 8 cheapest, 11 most expensive.
|
|
56
|
+
- Search `/v3/search/filters`: `term`, `offset` (`null`, then `nextOffset` = a plain number), `sort` 0-5, `type` 0/1/2
|
|
57
|
+
(all / ebook / audio), `hasOff=true`, `inSubscription=true` (`hasOff=1` is a 400). No price filter, 12 per page.
|
|
58
|
+
- Unknown book id: `/v2/book/{id}` answers 200 with body `null`; non-numeric id 400. Comments: `/v2/book/{id}/comments?start&size`
|
|
59
|
+
(size up to 40, most liked first), replies `/v2/comment/{id}/replies`.
|
|
60
|
+
- The category menu exists only in the home page HTML (`id="category-list-1|2"`, `id="category-children-<fmt>-<id>"`), no JSON.
|
|
61
|
+
- Book detail `/v2/book/{id}` is large (about 600 KB, with related books and quotes); `/v2/book/{id}/priceinfo` is the tiny live price.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sepehr
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: taaghche-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Unofficial read-only MCP server for Taaghche: search Persian ebooks and audiobooks, compare prices and formats, read reviews, browse bestsellers, new and free books.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sepehr071/taaghche-mcp
|
|
6
|
+
Project-URL: Source, https://github.com/sepehr071/taaghche-mcp
|
|
7
|
+
Project-URL: Changelog, https://github.com/sepehr071/taaghche-mcp/releases
|
|
8
|
+
Project-URL: Issues, https://github.com/sepehr071/taaghche-mcp/issues
|
|
9
|
+
Author-email: Sepehr <sepehr@nextofx.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: audiobook,books,ebook,iran,mcp,model-context-protocol,persian,taaghche
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: httpx>=0.27
|
|
24
|
+
Requires-Dist: mcp<3,>=2.2
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
<!-- mcp-name: io.github.sepehr071/taaghche-mcp -->
|
|
28
|
+
|
|
29
|
+
# taaghche-mcp
|
|
30
|
+
|
|
31
|
+
**Let your AI agent search Taaghche, the Iranian ebook and audiobook store: compare prices and formats, read reviews, browse bestsellers, new and free books.**
|
|
32
|
+
|
|
33
|
+
Unofficial and read-only. Covers about 220,000 Persian and translated ebooks and audiobooks on
|
|
34
|
+
[taaghche.com](https://taaghche.com), prices in Toman. No API key, no account.
|
|
35
|
+
|
|
36
|
+
## Quick start
|
|
37
|
+
|
|
38
|
+
You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
claude mcp add taaghche -- uvx taaghche-mcp
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Any other MCP client (Claude Desktop, Cursor, VS Code): run `uvx taaghche-mcp` as a stdio server, e.g.
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"mcpServers": {
|
|
49
|
+
"taaghche": { "command": "uvx", "args": ["taaghche-mcp"] }
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Then ask, for example:
|
|
55
|
+
|
|
56
|
+
- "Is there an audiobook of شازده کوچولو, and which edition is the cheapest?"
|
|
57
|
+
- "Free audiobooks about history, most downloaded first."
|
|
58
|
+
- "What do readers say about book 6426? Show the most liked reviews."
|
|
59
|
+
- <span dir="rtl">پرفروش‌ترین کتاب‌های روان‌شناسی زیر ۱۰۰ هزار تومان کدامند؟</span>
|
|
60
|
+
|
|
61
|
+
## How it works
|
|
62
|
+
|
|
63
|
+
`taaghche-mcp` runs locally and calls the same public JSON endpoints the taaghche.com website uses
|
|
64
|
+
(`get.taaghche.com` for books, reviews, lists and search, `explore.taaghche.com` for suggestions; the category menu is
|
|
65
|
+
read from the home page). No hosted server in between. API map and quirks: `../taaghche/`.
|
|
66
|
+
|
|
67
|
+
## Tools
|
|
68
|
+
|
|
69
|
+
All 12 tools are annotated `readOnlyHint: true` and return compact structured JSON.
|
|
70
|
+
|
|
71
|
+
**Find and read a book**
|
|
72
|
+
|
|
73
|
+
| Tool | What it does |
|
|
74
|
+
|---|---|
|
|
75
|
+
| `tg_search` | Search by title, author or topic; format ebook / audiobook; sort (relevance, bestselling, cheapest, newest, ...); discounted, free, subscription, price range |
|
|
76
|
+
| `tg_suggest` | Typeahead: matching titles with their publisher |
|
|
77
|
+
| `tg_book` | Price and discount, format, pages or listening time, publisher, translator, narrator, rating breakdown, review count, categories, ISBN, availability |
|
|
78
|
+
| `tg_reviews` | Reader reviews (most liked first) with stars and likes; replies to one review |
|
|
79
|
+
| `tg_similar` | Similar books, other books of the same author and publisher |
|
|
80
|
+
|
|
81
|
+
**Browse**
|
|
82
|
+
|
|
83
|
+
| Tool | What it does |
|
|
84
|
+
|---|---|
|
|
85
|
+
| `tg_categories` | The category tree for ebooks and audiobooks with ids and slugs |
|
|
86
|
+
| `tg_browse` | A category or the whole catalog: format, sort, price ceiling, discounted, free; 16 per page |
|
|
87
|
+
| `tg_bestsellers` | The hottest books («داغترین»), overall or per category and format |
|
|
88
|
+
| `tg_new_releases` | Newest books, overall or per category and format |
|
|
89
|
+
| `tg_free_books` | Free books and audiobooks, most downloaded first |
|
|
90
|
+
| `tg_author` | An author's profile (nationality, life dates, biography) and books |
|
|
91
|
+
| `tg_publisher` | A publisher's description and books |
|
|
92
|
+
|
|
93
|
+
## Good to know
|
|
94
|
+
|
|
95
|
+
- **Prices are in Toman.** The API returns Toman (book 6426 is `58500` in the API and `۵۸,۵۰۰ تومان` on the page). `final_price` is what you pay, `price` is before discount, `discount_pct` a whole percent, `free` is true for 0.
|
|
96
|
+
- **The site cannot filter by price, so the price range is applied here.** `tg_search` applies `min_price`, `max_price` and `free_only` to the results it scans (up to 5 pages of 12); the browse tools, `tg_author` and `tg_publisher` do the same with `max_price` (up to 5 pages of 16). `scanned` tells how many books were looked at; with `sort="cheapest"` the ceiling is exact and the scan stops early. Only free and discounted lists are filtered by the site.
|
|
97
|
+
- **Paging:** `tg_search` returns 12 books per page, the browse tools and `tg_author` / `tg_publisher` 16. Pass `next_cursor` back as `cursor` with the same other arguments.
|
|
98
|
+
- **«Bestsellers» is the site's «hot» ranking.** Taaghche publishes no sales numbers; for the true best-selling order of a keyword use `tg_search(sort="bestselling")`.
|
|
99
|
+
- **Binahayat (بینهایت) subscription:** `in_subscription` marks books included in it; the price is for buying the book permanently.
|
|
100
|
+
- **Dates ending `_fa` are Persian (Jalali).**
|
|
101
|
+
- Persian queries match best.
|
|
102
|
+
|
|
103
|
+
## Configuration
|
|
104
|
+
|
|
105
|
+
| Variable | Default | Meaning |
|
|
106
|
+
|---|---|---|
|
|
107
|
+
| `TAAGHCHE_MCP_PROXY` | unset | HTTP proxy for every request, e.g. `http://user:pass@host:port` (system proxy variables are ignored) |
|
|
108
|
+
|
|
109
|
+
## Development
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
export HTTPS_PROXY=http://127.0.0.1:10898 HTTP_PROXY=http://127.0.0.1:10898 # uv downloads only
|
|
113
|
+
uv sync
|
|
114
|
+
uv run ruff check . && uv run ruff format --check .
|
|
115
|
+
uv run pytest -q # offline, on recorded fixtures
|
|
116
|
+
uv run pytest -m live -q # real API
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## License
|
|
120
|
+
|
|
121
|
+
MIT
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
<!-- mcp-name: io.github.sepehr071/taaghche-mcp -->
|
|
2
|
+
|
|
3
|
+
# taaghche-mcp
|
|
4
|
+
|
|
5
|
+
**Let your AI agent search Taaghche, the Iranian ebook and audiobook store: compare prices and formats, read reviews, browse bestsellers, new and free books.**
|
|
6
|
+
|
|
7
|
+
Unofficial and read-only. Covers about 220,000 Persian and translated ebooks and audiobooks on
|
|
8
|
+
[taaghche.com](https://taaghche.com), prices in Toman. No API key, no account.
|
|
9
|
+
|
|
10
|
+
## Quick start
|
|
11
|
+
|
|
12
|
+
You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
claude mcp add taaghche -- uvx taaghche-mcp
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Any other MCP client (Claude Desktop, Cursor, VS Code): run `uvx taaghche-mcp` as a stdio server, e.g.
|
|
19
|
+
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"mcpServers": {
|
|
23
|
+
"taaghche": { "command": "uvx", "args": ["taaghche-mcp"] }
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Then ask, for example:
|
|
29
|
+
|
|
30
|
+
- "Is there an audiobook of شازده کوچولو, and which edition is the cheapest?"
|
|
31
|
+
- "Free audiobooks about history, most downloaded first."
|
|
32
|
+
- "What do readers say about book 6426? Show the most liked reviews."
|
|
33
|
+
- <span dir="rtl">پرفروش‌ترین کتاب‌های روان‌شناسی زیر ۱۰۰ هزار تومان کدامند؟</span>
|
|
34
|
+
|
|
35
|
+
## How it works
|
|
36
|
+
|
|
37
|
+
`taaghche-mcp` runs locally and calls the same public JSON endpoints the taaghche.com website uses
|
|
38
|
+
(`get.taaghche.com` for books, reviews, lists and search, `explore.taaghche.com` for suggestions; the category menu is
|
|
39
|
+
read from the home page). No hosted server in between. API map and quirks: `../taaghche/`.
|
|
40
|
+
|
|
41
|
+
## Tools
|
|
42
|
+
|
|
43
|
+
All 12 tools are annotated `readOnlyHint: true` and return compact structured JSON.
|
|
44
|
+
|
|
45
|
+
**Find and read a book**
|
|
46
|
+
|
|
47
|
+
| Tool | What it does |
|
|
48
|
+
|---|---|
|
|
49
|
+
| `tg_search` | Search by title, author or topic; format ebook / audiobook; sort (relevance, bestselling, cheapest, newest, ...); discounted, free, subscription, price range |
|
|
50
|
+
| `tg_suggest` | Typeahead: matching titles with their publisher |
|
|
51
|
+
| `tg_book` | Price and discount, format, pages or listening time, publisher, translator, narrator, rating breakdown, review count, categories, ISBN, availability |
|
|
52
|
+
| `tg_reviews` | Reader reviews (most liked first) with stars and likes; replies to one review |
|
|
53
|
+
| `tg_similar` | Similar books, other books of the same author and publisher |
|
|
54
|
+
|
|
55
|
+
**Browse**
|
|
56
|
+
|
|
57
|
+
| Tool | What it does |
|
|
58
|
+
|---|---|
|
|
59
|
+
| `tg_categories` | The category tree for ebooks and audiobooks with ids and slugs |
|
|
60
|
+
| `tg_browse` | A category or the whole catalog: format, sort, price ceiling, discounted, free; 16 per page |
|
|
61
|
+
| `tg_bestsellers` | The hottest books («داغترین»), overall or per category and format |
|
|
62
|
+
| `tg_new_releases` | Newest books, overall or per category and format |
|
|
63
|
+
| `tg_free_books` | Free books and audiobooks, most downloaded first |
|
|
64
|
+
| `tg_author` | An author's profile (nationality, life dates, biography) and books |
|
|
65
|
+
| `tg_publisher` | A publisher's description and books |
|
|
66
|
+
|
|
67
|
+
## Good to know
|
|
68
|
+
|
|
69
|
+
- **Prices are in Toman.** The API returns Toman (book 6426 is `58500` in the API and `۵۸,۵۰۰ تومان` on the page). `final_price` is what you pay, `price` is before discount, `discount_pct` a whole percent, `free` is true for 0.
|
|
70
|
+
- **The site cannot filter by price, so the price range is applied here.** `tg_search` applies `min_price`, `max_price` and `free_only` to the results it scans (up to 5 pages of 12); the browse tools, `tg_author` and `tg_publisher` do the same with `max_price` (up to 5 pages of 16). `scanned` tells how many books were looked at; with `sort="cheapest"` the ceiling is exact and the scan stops early. Only free and discounted lists are filtered by the site.
|
|
71
|
+
- **Paging:** `tg_search` returns 12 books per page, the browse tools and `tg_author` / `tg_publisher` 16. Pass `next_cursor` back as `cursor` with the same other arguments.
|
|
72
|
+
- **«Bestsellers» is the site's «hot» ranking.** Taaghche publishes no sales numbers; for the true best-selling order of a keyword use `tg_search(sort="bestselling")`.
|
|
73
|
+
- **Binahayat (بینهایت) subscription:** `in_subscription` marks books included in it; the price is for buying the book permanently.
|
|
74
|
+
- **Dates ending `_fa` are Persian (Jalali).**
|
|
75
|
+
- Persian queries match best.
|
|
76
|
+
|
|
77
|
+
## Configuration
|
|
78
|
+
|
|
79
|
+
| Variable | Default | Meaning |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| `TAAGHCHE_MCP_PROXY` | unset | HTTP proxy for every request, e.g. `http://user:pass@host:port` (system proxy variables are ignored) |
|
|
82
|
+
|
|
83
|
+
## Development
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
export HTTPS_PROXY=http://127.0.0.1:10898 HTTP_PROXY=http://127.0.0.1:10898 # uv downloads only
|
|
87
|
+
uv sync
|
|
88
|
+
uv run ruff check . && uv run ruff format --check .
|
|
89
|
+
uv run pytest -q # offline, on recorded fixtures
|
|
90
|
+
uv run pytest -m live -q # real API
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## License
|
|
94
|
+
|
|
95
|
+
MIT
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "taaghche-mcp"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Unofficial read-only MCP server for Taaghche: search Persian ebooks and audiobooks, compare prices and formats, read reviews, browse bestsellers, new and free books."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
authors = [{ name = "Sepehr", email = "sepehr@nextofx.com" }]
|
|
9
|
+
requires-python = ">=3.10"
|
|
10
|
+
keywords = ["mcp", "model-context-protocol", "taaghche", "iran", "ebook", "audiobook", "books", "persian"]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 4 - Beta",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Operating System :: OS Independent",
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Programming Language :: Python :: 3.10",
|
|
17
|
+
"Programming Language :: Python :: 3.11",
|
|
18
|
+
"Programming Language :: Python :: 3.12",
|
|
19
|
+
"Programming Language :: Python :: 3.13",
|
|
20
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
21
|
+
]
|
|
22
|
+
dependencies = [
|
|
23
|
+
"mcp>=2.2,<3",
|
|
24
|
+
"httpx>=0.27",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[project.urls]
|
|
28
|
+
Homepage = "https://github.com/sepehr071/taaghche-mcp"
|
|
29
|
+
Source = "https://github.com/sepehr071/taaghche-mcp"
|
|
30
|
+
Changelog = "https://github.com/sepehr071/taaghche-mcp/releases"
|
|
31
|
+
Issues = "https://github.com/sepehr071/taaghche-mcp/issues"
|
|
32
|
+
|
|
33
|
+
[project.scripts]
|
|
34
|
+
taaghche-mcp = "taaghche_mcp.server:main"
|
|
35
|
+
|
|
36
|
+
[dependency-groups]
|
|
37
|
+
dev = ["pytest>=8", "ruff>=0.6"]
|
|
38
|
+
|
|
39
|
+
[build-system]
|
|
40
|
+
requires = ["hatchling"]
|
|
41
|
+
build-backend = "hatchling.build"
|
|
42
|
+
|
|
43
|
+
[tool.pytest.ini_options]
|
|
44
|
+
testpaths = ["tests"]
|
|
45
|
+
addopts = "-m 'not live'"
|
|
46
|
+
markers = ["live: calls the real Taaghche API (run with -m live)"]
|
|
47
|
+
|
|
48
|
+
[tool.ruff]
|
|
49
|
+
line-length = 120
|
|
50
|
+
target-version = "py310"
|
|
51
|
+
|
|
52
|
+
[tool.ruff.lint]
|
|
53
|
+
select = ["E", "F", "I", "B", "UP"]
|
|
54
|
+
ignore = ["E501"] # long Field(description=...) strings read better on one line
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "io.github.sepehr071/taaghche-mcp",
|
|
4
|
+
"title": "Taaghche",
|
|
5
|
+
"description": "Unofficial read-only Taaghche: search Persian ebooks and audiobooks, compare prices, read reviews.",
|
|
6
|
+
"repository": {
|
|
7
|
+
"url": "https://github.com/sepehr071/taaghche-mcp",
|
|
8
|
+
"source": "github"
|
|
9
|
+
},
|
|
10
|
+
"websiteUrl": "https://github.com/sepehr071/taaghche-mcp",
|
|
11
|
+
"version": "0.1.0",
|
|
12
|
+
"packages": [
|
|
13
|
+
{
|
|
14
|
+
"registryType": "pypi",
|
|
15
|
+
"registryBaseUrl": "https://pypi.org",
|
|
16
|
+
"identifier": "taaghche-mcp",
|
|
17
|
+
"version": "0.1.0",
|
|
18
|
+
"runtimeHint": "uvx",
|
|
19
|
+
"transport": {
|
|
20
|
+
"type": "stdio"
|
|
21
|
+
},
|
|
22
|
+
"environmentVariables": [
|
|
23
|
+
{
|
|
24
|
+
"name": "TAAGHCHE_MCP_PROXY",
|
|
25
|
+
"description": "Optional HTTP proxy URL for requests to taaghche.com; system proxy settings are ignored.",
|
|
26
|
+
"isRequired": false,
|
|
27
|
+
"isSecret": false
|
|
28
|
+
}
|
|
29
|
+
]
|
|
30
|
+
}
|
|
31
|
+
]
|
|
32
|
+
}
|