masterkala-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.
Files changed (45) hide show
  1. masterkala_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +42 -0
  2. masterkala_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
  3. masterkala_mcp-0.1.0/.github/dependabot.yml +10 -0
  4. masterkala_mcp-0.1.0/.github/workflows/ci.yml +21 -0
  5. masterkala_mcp-0.1.0/.github/workflows/publish.yml +51 -0
  6. masterkala_mcp-0.1.0/.gitignore +6 -0
  7. masterkala_mcp-0.1.0/LICENSE +21 -0
  8. masterkala_mcp-0.1.0/PKG-INFO +297 -0
  9. masterkala_mcp-0.1.0/README.md +273 -0
  10. masterkala_mcp-0.1.0/pyproject.toml +52 -0
  11. masterkala_mcp-0.1.0/server.json +32 -0
  12. masterkala_mcp-0.1.0/src/masterkala_mcp/__init__.py +5 -0
  13. masterkala_mcp-0.1.0/src/masterkala_mcp/blog.py +100 -0
  14. masterkala_mcp-0.1.0/src/masterkala_mcp/catalog.py +409 -0
  15. masterkala_mcp-0.1.0/src/masterkala_mcp/http.py +116 -0
  16. masterkala_mcp-0.1.0/src/masterkala_mcp/product.py +302 -0
  17. masterkala_mcp-0.1.0/src/masterkala_mcp/registry.py +16 -0
  18. masterkala_mcp-0.1.0/src/masterkala_mcp/server.py +57 -0
  19. masterkala_mcp-0.1.0/tests/conftest.py +69 -0
  20. masterkala_mcp-0.1.0/tests/fixtures/attributes.json +77 -0
  21. masterkala_mcp-0.1.0/tests/fixtures/attributes_24855.json +36 -0
  22. masterkala_mcp-0.1.0/tests/fixtures/blog_comments.json +166 -0
  23. masterkala_mcp-0.1.0/tests/fixtures/blog_posts.json +44 -0
  24. masterkala_mcp-0.1.0/tests/fixtures/brands.html +30 -0
  25. masterkala_mcp-0.1.0/tests/fixtures/categories.html +42 -0
  26. masterkala_mcp-0.1.0/tests/fixtures/category.html +4 -0
  27. masterkala_mcp-0.1.0/tests/fixtures/delivery_badge.json +3 -0
  28. masterkala_mcp-0.1.0/tests/fixtures/offer.html +263 -0
  29. masterkala_mcp-0.1.0/tests/fixtures/product_24855.html +75 -0
  30. masterkala_mcp-0.1.0/tests/fixtures/product_26634.html +75 -0
  31. masterkala_mcp-0.1.0/tests/fixtures/product_27034.html +109 -0
  32. masterkala_mcp-0.1.0/tests/fixtures/product_list.html +304 -0
  33. masterkala_mcp-0.1.0/tests/fixtures/reviews.json +65 -0
  34. masterkala_mcp-0.1.0/tests/fixtures/search.json +136 -0
  35. masterkala_mcp-0.1.0/tests/fixtures/shipping.json +34 -0
  36. masterkala_mcp-0.1.0/tests/fixtures/shipping_free.json +34 -0
  37. masterkala_mcp-0.1.0/tests/fixtures/stores.html +107 -0
  38. masterkala_mcp-0.1.0/tests/test_blog.py +39 -0
  39. masterkala_mcp-0.1.0/tests/test_catalog.py +209 -0
  40. masterkala_mcp-0.1.0/tests/test_http.py +80 -0
  41. masterkala_mcp-0.1.0/tests/test_live_blog.py +23 -0
  42. masterkala_mcp-0.1.0/tests/test_live_catalog.py +55 -0
  43. masterkala_mcp-0.1.0/tests/test_live_product.py +38 -0
  44. masterkala_mcp-0.1.0/tests/test_product.py +157 -0
  45. masterkala_mcp-0.1.0/uv.lock +1112 -0
@@ -0,0 +1,42 @@
1
+ name: Bug report
2
+ description: A tool failed or returned wrong data
3
+ labels: [bug]
4
+ body:
5
+ - type: input
6
+ id: tool
7
+ attributes:
8
+ label: Tool
9
+ description: Which tool, e.g. mk_find_cheapest
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: input
14
+ attributes:
15
+ label: Arguments and result
16
+ description: The arguments the agent sent and the error or wrong output. Remove anything personal.
17
+ render: json
18
+ validations:
19
+ required: true
20
+ - type: textarea
21
+ id: expected
22
+ attributes:
23
+ label: What you expected
24
+ description: e.g. the price shown on masterkala.com for the same product
25
+ - type: input
26
+ id: client
27
+ attributes:
28
+ label: MCP client and OS
29
+ placeholder: Claude Desktop 1.x on Windows 11
30
+ - type: dropdown
31
+ id: network
32
+ attributes:
33
+ label: Network
34
+ options:
35
+ - Direct, no VPN
36
+ - VPN or proxy
37
+ - MASTERKALA_MCP_PROXY set
38
+ - type: input
39
+ id: version
40
+ attributes:
41
+ label: masterkala-mcp version
42
+ placeholder: "0.1.0"
@@ -0,0 +1,5 @@
1
+ blank_issues_enabled: true
2
+ contact_links:
3
+ - name: Question or idea
4
+ url: https://github.com/sepehr071/masterkala-mcp/discussions
5
+ about: Ask how to use it or suggest a new tool
@@ -0,0 +1,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: monthly
7
+ - package-ecosystem: uv
8
+ directory: /
9
+ schedule:
10
+ interval: monthly
@@ -0,0 +1,21 @@
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 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/masterkala-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/latest/download/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,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ .pytest_cache/
6
+ .ruff_cache/
@@ -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,297 @@
1
+ Metadata-Version: 2.5
2
+ Name: masterkala-mcp
3
+ Version: 0.1.0
4
+ Summary: Unofficial read-only MCP server for MasterKala: search gadgets and accessories, compare prices and specs, find deals.
5
+ Project-URL: Homepage, https://github.com/sepehr071/masterkala-mcp
6
+ Project-URL: Issues, https://github.com/sepehr071/masterkala-mcp/issues
7
+ Author-email: Sepehr <sepehr@nextofx.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: e-commerce,gadgets,iran,masterkala,mcp,model-context-protocol,shopping
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
20
+ Requires-Python: >=3.10
21
+ Requires-Dist: httpx>=0.27
22
+ Requires-Dist: mcp<3,>=2.2
23
+ Description-Content-Type: text/markdown
24
+
25
+ <!-- mcp-name: io.github.sepehr071/masterkala-mcp -->
26
+
27
+ <div align="center">
28
+
29
+ # 🎧 masterkala-mcp
30
+
31
+ **Let your AI agent shop for gadgets on MasterKala.**<br>
32
+ Search earbuds, chargers, power banks and smart watches, compare real prices and specs,<br>
33
+ read reviews, check stock and delivery dates, and catch today's discounts, all from Claude, Cursor or Copilot.
34
+
35
+ [![PyPI](https://img.shields.io/pypi/v/masterkala-mcp?color=2563eb)](https://pypi.org/project/masterkala-mcp/)
36
+ [![Python](https://img.shields.io/pypi/pyversions/masterkala-mcp)](https://pypi.org/project/masterkala-mcp/)
37
+ [![CI](https://github.com/sepehr071/masterkala-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/masterkala-mcp/actions/workflows/ci.yml)
38
+ [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fmasterkala--mcp-7c3aed)](https://registry.modelcontextprotocol.io/v0/servers?search=masterkala-mcp)
39
+ [![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/masterkala-mcp/blob/main/LICENSE)
40
+
41
+ [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=masterkala&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtYXN0ZXJrYWxhLW1jcCJdfQ==)
42
+ [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_masterkala--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=masterkala&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22masterkala-mcp%22%5D%7D)
43
+
44
+ [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
45
+
46
+ </div>
47
+
48
+ ---
49
+
50
+ ## Why
51
+
52
+ MasterKala lists thousands of accessories, and a search for "power bank" mixes real power banks with
53
+ silicone covers, out-of-stock items and things sold only in its shops. Finding *the cheapest one you can
54
+ actually order, and what it costs delivered*, means paging through results and opening product pages.
55
+ An agent with `masterkala-mcp` does that in seconds:
56
+
57
+ > **You:** Cheapest Xiaomi power bank I can order now, delivered in Tehran?
58
+ >
59
+ > **Agent:** *calls* `mk_find_cheapest(query="پاوربانک شیائومی")` → `mk_shipping(product_id=26935)`
60
+ >
61
+ > | Total | Product | Price | Shipping |
62
+ > |---:|---|---:|---|
63
+ > | **4,338,000** | پاوربانک 10000 شیائومی گلوریمی Glorimi LightCore 22.5W | 4,188,000 (5% off) | 150,000, Saturday 15:00-18:00 |
64
+ > | **5,291,000** | پاوربانک فوق نازک مگنتی 5000 Glorimi FitCore Mag 20W | 5,291,000 (4% off) | free (over 5M) |
65
+ > | **5,401,000** | پاوربانک 20000 شیائومی گلوریمی Glorimi LightCore 22.5W | 5,401,000 (6% off) | free (over 5M) |
66
+ >
67
+ > The 10,000 mAh LightCore is cheapest even with the 150,000 courier fee. The 20,000 mAh LightCore ships
68
+ > free and costs 1,063,000 more for twice the capacity. Want me to compare their specs with `mk_specs`?
69
+
70
+ <sub>Real tool output from 2026-10-03; prices change all the time. Prices are in Toman.</sub>
71
+
72
+ ## What it can do
73
+
74
+ - 🔎 **Search** products by name in Persian or English, with price, discount and stock
75
+ - 💸 **Find the cheapest** in-stock match, with cases and covers filtered out
76
+ - 🗂️ **Browse** any category, brand or tag sorted by price, stock or date, with price range and brand/color filters
77
+ - 📋 **Read** full product details: colors, stock count, specs, side-by-side comparison, reviews
78
+ - 🚚 **Check delivery**: next Tehran courier slot, post to other cities, shipping fee, same-day cut-off
79
+ - ⚡ **Catch deals** on the discount page, plus buying guides from the MasterKala blog
80
+ - 🔒 **Read-only by design**: no login, no cart, no orders, no reviews posted
81
+
82
+ ## Quick start
83
+
84
+ You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
85
+
86
+ <details open>
87
+ <summary><b>Claude Code</b></summary>
88
+
89
+ ```bash
90
+ claude mcp add masterkala -- uvx masterkala-mcp
91
+ ```
92
+ </details>
93
+
94
+ <details>
95
+ <summary><b>Claude Desktop</b></summary>
96
+
97
+ Settings → Developer → Edit Config, then add:
98
+
99
+ ```json
100
+ {
101
+ "mcpServers": {
102
+ "masterkala": { "command": "uvx", "args": ["masterkala-mcp"] }
103
+ }
104
+ }
105
+ ```
106
+ </details>
107
+
108
+ <details>
109
+ <summary><b>Cursor</b></summary>
110
+
111
+ Click **Install in Cursor** above, or add the Claude Desktop block to `~/.cursor/mcp.json`.
112
+ </details>
113
+
114
+ <details>
115
+ <summary><b>VS Code (Copilot agent mode)</b></summary>
116
+
117
+ Click **Install in VS Code** above, or add to `.vscode/mcp.json`:
118
+
119
+ ```json
120
+ {
121
+ "servers": {
122
+ "masterkala": { "type": "stdio", "command": "uvx", "args": ["masterkala-mcp"] }
123
+ }
124
+ }
125
+ ```
126
+ </details>
127
+
128
+ <details>
129
+ <summary><b>Anything else</b></summary>
130
+
131
+ It's a standard stdio MCP server: run `uvx masterkala-mcp`, or `pip install masterkala-mcp` and run `masterkala-mcp`.
132
+ </details>
133
+
134
+ Then just ask:
135
+
136
+ - "Cheapest Bluetooth earbuds between 3 and 5 million Toman, and which one has the best reviews?"
137
+ - "Compare the specs of the Green Lion Ocean and the Awei T66."
138
+ - "Is the blue CMF Buds Pro 2 in stock? When would it reach Tehran?"
139
+ - <span dir="rtl">بهترین تخفیف&zwnj;های امروز مسترکالا روی پاوربانک چیه؟</span>
140
+
141
+ ## How it works
142
+
143
+ ```text
144
+ AI agent (Claude, Cursor, Copilot, ...)
145
+ │
146
+ │ MCP over stdio
147
+ ▼
148
+ masterkala-mcp (runs on your machine)
149
+ │
150
+ │ HTTPS
151
+ └──────▶ masterkala.com JSON API, listing fragments, product pages
152
+ ```
153
+
154
+ `masterkala-mcp` runs locally and calls the same public endpoints the masterkala.com website uses.
155
+ There's no hosted server in between, no API key, and nothing about you is sent anywhere else.
156
+
157
+ ## Tools
158
+
159
+ <details open>
160
+ <summary><b>🔎 Find products</b> (7)</summary>
161
+
162
+ | Tool | What it does |
163
+ |---|---|
164
+ | `mk_search` | Search by keyword: price, discount, stock, plus matching categories and tag pages |
165
+ | `mk_find_cheapest` | Cheapest in-stock matches for a keyword, one flat list (accessories filtered out) |
166
+ | `mk_browse` | A category, brand or tag sorted by price / stock / date, with price range and filters |
167
+ | `mk_filters` | Brand, color and feature filter ids and the price range of a category, brand or tag |
168
+ | `mk_categories` | Product categories and their ids |
169
+ | `mk_brands` | Brands and their slugs |
170
+ | `mk_deals` | Everything on the discount page, biggest discount first, with the time left |
171
+ </details>
172
+
173
+ <details open>
174
+ <summary><b>📦 One product</b> (5)</summary>
175
+
176
+ | Tool | What it does |
177
+ |---|---|
178
+ | `mk_product` | Price, discount, stock status and count, colors, brand, category, rating, shops that have it |
179
+ | `mk_specs` | Specification table of 1-4 products side by side |
180
+ | `mk_reviews` | Customer reviews with star breakdown and the store's replies |
181
+ | `mk_shipping` | Next delivery slot and fee for Tehran and other cities, same-day cut-off |
182
+ | `mk_branches` | MasterKala's physical shops with address, phone and map location |
183
+ </details>
184
+
185
+ <details open>
186
+ <summary><b>📝 Blog</b> (2)</summary>
187
+
188
+ | Tool | What it does |
189
+ |---|---|
190
+ | `mk_blog_posts` | Buying guides, comparisons and how-tos, newest first |
191
+ | `mk_blog_comments` | Readers' questions on a post with the store writer's answers |
192
+ </details>
193
+
194
+ All tools are annotated `readOnlyHint: true` and return compact structured JSON, so they don't flood the agent's context.
195
+
196
+ ## Good to know
197
+
198
+ - **Prices are in Toman.** `final_price` is what you pay, `price` is before discount, `discount_pct` is a whole percent. The site's structured data is in Rial; the server converts it.
199
+ - **Shipping is free from 5,000,000 Toman** per order for most items (bulky goods such as large speakers never ship free; `mk_shipping` gives `free_shipping_from: null` for them); below that, Tehran courier and post were 150,000 / 155,000 Toman on 2026-10-03. There is no address API, so `mk_shipping` estimates for Tehran and "other cities by post".
200
+ - **Stock**: `in_stock` means orderable online now. Other statuses: ناموجود (sold out), به زودی (coming soon), موجود در شعب حضوری (only in the physical shops).
201
+ - **Ratings are 1–5**, `null` when nobody has reviewed the product yet.
202
+ - **Persian queries match best** (`هندزفری`, `پاوربانک`), but English brand and model names work too (`xiaomi`, `Buds Pro`).
203
+
204
+ ## FAQ
205
+
206
+ <details>
207
+ <summary><b>Can it place an order for me?</b></summary>
208
+
209
+ No, and that's deliberate. It has no login and never touches the cart, order, payment, wishlist or review endpoints.
210
+ The agent finds the best option; you buy it on masterkala.com.
211
+ </details>
212
+
213
+ <details>
214
+ <summary><b>Why does <code>mk_find_cheapest</code> skip some items?</b></summary>
215
+
216
+ It keeps only items you can order online now, whose title contains every word of your query, and drops cases,
217
+ covers and screen protectors unless you ask for them (`include_accessories: true`, or a query like "کاور ...").
218
+ It scans the first 500 results by default (in-stock items come first); `complete: false` in the reply means more
219
+ in-stock items lie past that, so raise `scan` (up to 1500). `mk_search` shows everything.
220
+ </details>
221
+
222
+ <details>
223
+ <summary><b>I get "Could not reach masterkala.com"</b></summary>
224
+
225
+ The server retries a dropped connection once. If it still fails, check your internet connection. System proxy
226
+ variables are ignored on purpose; set `MASTERKALA_MCP_PROXY` if you need a proxy.
227
+ </details>
228
+
229
+ <details>
230
+ <summary><b>Claude Desktop says <code>uvx</code> is not found</b></summary>
231
+
232
+ Use the full path to `uvx` (`where uvx` on Windows, `which uvx` on macOS/Linux) as `command`.
233
+ </details>
234
+
235
+ <details>
236
+ <summary><b>How do I debug what the agent sees?</b></summary>
237
+
238
+ ```bash
239
+ npx @modelcontextprotocol/inspector uvx masterkala-mcp
240
+ ```
241
+ </details>
242
+
243
+ ## Configuration
244
+
245
+ | Variable | Default | Meaning |
246
+ |---|---|---|
247
+ | `MASTERKALA_MCP_PROXY` | unset | HTTP proxy for every request, e.g. `http://user:pass@host:port` |
248
+
249
+ ## فارسی
250
+
251
+ <div dir="rtl">
252
+
253
+ **masterkala-mcp** به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می&zwnj;دهد در مسترکالا جستجو کند،
254
+ ارزان&zwnj;ترین کالای موجود را پیدا کند، مشخصات و نظرات را مقایسه کند و زمان و هزینه ارسال و تخفیف&zwnj;های روز را ببیند.
255
+
256
+ - فقط خواندنی است: وارد حساب نمی&zwnj;شود، سبد خرید نمی&zwnj;سازد، سفارش ثبت نمی&zwnj;کند و نظر نمی&zwnj;فرستد.
257
+ - قیمت&zwnj;ها به تومان است و کاور و قاب را از نتایج «ارزان&zwnj;ترین» جدا می&zwnj;کند.
258
+ - روی سیستم خود شما اجرا می&zwnj;شود و به هیچ سرور واسطی داده نمی&zwnj;فرستد.
259
+
260
+ **نصب در Claude Code:**
261
+
262
+ </div>
263
+
264
+ ```bash
265
+ claude mcp add masterkala -- uvx masterkala-mcp
266
+ ```
267
+
268
+ <div dir="rtl">
269
+
270
+ بعد بپرسید: «ارزان&zwnj;ترین هندزفری بلوتوث بین ۳ تا ۵ میلیون تومان کدام است و کی به تهران می&zwnj;رسد؟»
271
+
272
+ </div>
273
+
274
+ ## Development
275
+
276
+ ```bash
277
+ git clone https://github.com/sepehr071/masterkala-mcp && cd masterkala-mcp
278
+ uv sync
279
+ uv run pytest # offline, against recorded responses
280
+ uv run pytest -m live # real masterkala.com
281
+ uv run ruff check .
282
+ ```
283
+
284
+ Tools live in `src/masterkala_mcp/catalog.py`, `product.py` and `blog.py`; each is a typed async function with a
285
+ docstring that tells the agent when to use it. Issues and PRs are welcome, especially new tools and fixes for site changes.
286
+
287
+ Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions tests,
288
+ publishes to PyPI and the [MCP Registry](https://registry.modelcontextprotocol.io), and creates the GitHub Release.
289
+
290
+ ## Disclaimer
291
+
292
+ Unofficial and not affiliated with or endorsed by MasterKala. It uses the public endpoints of the masterkala.com
293
+ website, which can change without notice. Please keep request rates reasonable.
294
+
295
+ ## License
296
+
297
+ [MIT](https://github.com/sepehr071/masterkala-mcp/blob/main/LICENSE)